PWA & Offline Support

​

Installing as PWA

​

Desktop Installation

​

Chrome / Edge / Brave

1. Visit the Kayston’s Forge website
2. Look for the install icon in the address bar (⊕ or computer icon)
3. Click the icon and select Install
4. The app will open in its own window without browser UI

1. Click the three-dot menu (⋮) in the browser
2. Select Install Kayston’s Forge or Create Shortcut
3. Check Open as window for a native app experience

​

Firefox

1. Visit the Kayston’s Forge website
2. Click the three-line menu (≡) > Install Kayston’s Forge
3. Confirm installation in the dialog

​

Safari (macOS)

1. Visit the Kayston’s Forge website
2. Go to File > Add to Dock (macOS Sonoma+)
3. The app will be added to your Dock as a standalone app

​

Mobile Installation

​

iOS Safari

1. Open Kayston’s Forge in Safari
2. Tap the Share button (square with arrow)
3. Scroll down and tap Add to Home Screen
4. Edit the name if desired and tap Add
5. The app icon appears on your home screen

​

Android Chrome

1. Open Kayston’s Forge in Chrome
2. Tap the three-dot menu (⋮)
3. Select Add to Home screen or Install app
4. Follow the prompts to install
5. The app icon appears on your home screen

​

PWA Manifest

{
  "name": "Kayston's Forge",
  "short_name": "Kaystons",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#fdf6e3",
  "theme_color": "#b58900",
  "icons": [
    {
      "src": "/icons/icon-192.svg",
      "sizes": "192x192",
      "type": "image/svg+xml"
    },
    {
      "src": "/icons/icon-512.svg",
      "sizes": "512x512",
      "type": "image/svg+xml"
    }
  ]
}

​

Manifest Properties

• name: Full app name shown during installation
• short_name: Short name for home screen icons (limited space)
• start_url: URL to load when the app is launched
• display: standalone removes browser UI for a native app feel
• background_color: Warm cream (#fdf6e3) from Solarized Light theme
• theme_color: Brand gold (#b58900) for OS-level UI elements
• icons: SVG icons at 192x192 and 512x512 for crisp display at any size

​

Service Worker

​

Caching Strategy

​

Network-First for HTML

• Navigation requests (HTML pages) fetch from the network first
• If the network is unavailable, fall back to the cache
• Successful responses are cached for future offline use

// Network-first for HTML navigation
if (event.request.mode === 'navigate') {
  event.respondWith(
    fetch(event.request)
      .then((response) => {
        const copy = response.clone();
        caches.open(CACHE).then((cache) => 
          cache.put(event.request, copy)
        );
        return response;
      })
      .catch(() => caches.match(event.request))
  );
}

​

Cache-First for Static Assets

• JavaScript, CSS, images, and other static assets load from cache first
• If not cached, fetch from the network and cache the response
• This provides instant load times for repeat visits

// Cache-first for static assets
event.respondWith(
  caches.match(event.request).then((cached) => {
    if (cached) return cached;
    return fetch(event.request).then((response) => {
      const copy = response.clone();
      caches.open(CACHE).then((cache) => 
        cache.put(event.request, copy)
      );
      return response;
    });
  })
);

​

Cache Versioning

• When the cache version changes, old caches are automatically deleted
• This prevents stale assets from persisting across updates

const CACHE = 'kaystons-forge-v2';

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(
        keys
          .filter((key) => key !== CACHE)
          .map((key) => caches.delete(key))
      )
    )
  );
});

​

Registration

useEffect(() => {
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker
      .register('/sw.js')
      .catch(() => {});
  }
}, []);

​

Offline Functionality

​

What Works Offline

​

What Requires Internet

​

Benefits of PWA

​

Performance

• Instant load — Static site cached after first visit
• No round trips — All processing happens in your browser
• Fast execution — No server latency or API calls

​

Privacy

• Zero data transmission — All data stays on your device
• No tracking — No analytics, no cookies (except for app state)
• Offline operation — Works in air-gapped environments

​

User Experience

• Native feel — Standalone window, no browser UI
• App launcher — Appears in OS app switcher and spotlight search
• Keyboard shortcuts — Full support for app-wide shortcuts
• Notifications — Could support push notifications (not currently implemented)

​

Browser Support

​

Updating the App

1. Service worker detects update — New sw.js with different cache version
2. New assets download — Next navigation fetches fresh HTML/JS/CSS
3. Old cache cleared — Previous cache version is deleted on activation
4. User sees update — Changes appear on next page load or reload

​

Uninstalling the PWA

​

Desktop

​

Chrome / Edge / Brave

1. Open the installed app
2. Click the three-dot menu in the title bar
3. Select Uninstall Kayston’s Forge

1. Go to chrome://apps (Chrome) or edge://apps (Edge)
2. Right-click the Kayston’s Forge icon
3. Select Remove from Chrome/Edge

​

Firefox

1. Visit about:preferences#applications
2. Find Kayston’s Forge in the list
3. Click Remove

​

Safari (macOS)

1. Locate the app icon in your Dock
2. Right-click and select Options > Remove from Dock

​

Mobile

​

iOS

1. Long-press the app icon on your home screen
2. Tap Remove App > Delete App

​

Android

1. Long-press the app icon
2. Drag to Uninstall or tap App info > Uninstall

​

Troubleshooting

​

App Won’t Install

• Check HTTPS: PWAs require HTTPS (production site) or localhost (development)
• Clear cache: Old service workers can interfere — clear browser cache and try again
• Update browser: Ensure you’re using a recent browser version

​

Offline Mode Not Working

1. Check service worker status in DevTools:
   • Chrome: DevTools > Application > Service Workers
   • Firefox: DevTools > Application > Service Workers
2. Verify the service worker is activated and running
3. Check cache storage has entries for the app

​

App Not Updating

1. Do a hard refresh: Cmd/Ctrl+Shift+R
2. Clear site data: DevTools > Application > Clear storage
3. Unregister service worker manually in DevTools

​

Future Enhancements

• Background sync — Sync history to cloud when connection is restored
• Push notifications — Notify when new tools are added
• Share target — Accept shared text from other apps
• Shortcuts — Quick actions from app icon (e.g., “New JSON Formatter”)
• File handlers — Open JSON/YAML files directly in the app