Pwa Development

{
  // === REQUIRED FIELDS ===

  // Full application name (max 45 chars)
  // Used in: install prompt, app launcher, splash screen
  "name": "Your Application Name",

  // Short name for home screen (max 12 chars)
  // Used in: home screen icon label
  "short_name": "App",

  // URL to open when app launches
  // Should be within scope
  // Tip: Add query param for analytics (e.g., "/?source=pwa")
  "start_url": "/",

  // Display mode:
  // - "fullscreen": No browser UI, fills entire screen
  // - "standalone": Native app look, minimal browser UI (recommended)
  // - "minimal-ui": Some browser UI visible
  // - "browser": Normal browser tab
  "display": "standalone",

  // Icons - minimum 192x192 and 512x512 required
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      // Maskable icon for adaptive icons on Android
      // Design with safe zone: 80% centered circle
      "src": "/icons/icon-maskable-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],

  // === RECOMMENDED FIELDS ===

  // Background color for splash screen
  // Should match your app's initial background
  "background_color": "#ffffff",

  // Theme color for browser UI (title bar, task switcher)
  // Also add as <meta name="theme-color"> in HTML
  "theme_color": "#4285f4",

  // Application description (max 300 chars)
  // Used in: app stores, search results, install UI
  "description": "A brief description of what your app does.",

  // Navigation scope - URLs outside this open in browser
  // Default: parent directory of start_url
  "scope": "/",

  // === OPTIONAL FIELDS ===

  // Default orientation
  // Options: "any", "natural", "portrait", "portrait-primary",
  //          "portrait-secondary", "landscape", "landscape-primary",
  //          "landscape-secondary"
  "orientation": "any",

  // App categories (for app stores)
  // "categories": ["productivity", "utilities"],

  // Screenshots for richer install experience
  // "screenshots": [
  //   {
  //     "src": "/screenshots/mobile-home.png",
  //     "sizes": "1080x1920",
  //     "type": "image/png",
  //     "form_factor": "narrow",
  //     "label": "Home screen on mobile"
  //   },
  //   {
  //     "src": "/screenshots/desktop-home.png",
  //     "sizes": "1920x1080",
  //     "type": "image/png",
  //     "form_factor": "wide",
  //     "label": "Home screen on desktop"
  //   }
  // ],

  // App shortcuts (right-click/long-press menu)
  // "shortcuts": [
  //   {
  //     "name": "New Task",
  //     "short_name": "New",
  //     "description": "Create a new task",
  //     "url": "/tasks/new",
  //     "icons": [
  //       {
  //         "src": "/icons/shortcut-new-task.png",
  //         "sizes": "96x96"
  //       }
  //     ]
  //   }
  // ],

  // Related native apps
  // "related_applications": [
  //   {
  //     "platform": "play",
  //     "url": "https://play.google.com/store/apps/details?id=com.example.app",
  //     "id": "com.example.app"
  //   }
  // ],
  // "prefer_related_applications": false,

  // === ADVANCED FEATURES ===

  // Share Target - receive shared content
  // "share_target": {
  //   "action": "/share",
  //   "method": "POST",
  //   "enctype": "multipart/form-data",
  //   "params": {
  //     "title": "title",
  //     "text": "text",
  //     "url": "url"
  //   }
  // },

  // Protocol handlers - handle custom URL schemes
  // "protocol_handlers": [
  //   {
  //     "protocol": "web+myapp",
  //     "url": "/open?url=%s"
  //   }
  // ],

  // File handlers - open specific file types
  // "file_handlers": [
  //   {
  //     "action": "/open-file",
  //     "accept": {
  //       "text/plain": [".txt"],
  //       "application/json": [".json"]
  //     }
  //   }
  // ],

  // Language and text direction
  "lang": "en-US",
  "dir": "ltr"
}

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="theme-color" content="#4285f4">
  <title>Offline - App Name</title>
  <style>
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
    }

    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
      min-height: 100vh;
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      text-align: center;
      padding: 20px;
    }

    .container {
      max-width: 400px;
    }

    .icon {
      width: 120px;
      height: 120px;
      margin-bottom: 24px;
    }

    .icon svg {
      width: 100%;
      height: 100%;
    }

    h1 {
      font-size: 28px;
      font-weight: 600;
      margin-bottom: 16px;
    }

    p {
      font-size: 16px;
      line-height: 1.5;
      opacity: 0.9;
      margin-bottom: 32px;
    }

    .retry-button {
      display: inline-flex;
      align-items: center;
      gap: 8px;
      background: white;
      color: #667eea;
      border: none;
      padding: 12px 32px;
      font-size: 16px;
      font-weight: 600;
      border-radius: 50px;
      cursor: pointer;
      transition: transform 0.2s, box-shadow 0.2s;
    }

    .retry-button:hover {
      transform: translateY(-2px);
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
    }

    .retry-button:active {
      transform: translateY(0);
    }

    .retry-button svg {
      width: 20px;
      height: 20px;
    }

    .status {
      margin-top: 24px;
      font-size: 14px;
      opacity: 0.7;
    }

    .status.online {
      color: #4ade80;
      opacity: 1;
    }

    /* Animation for the cloud icon */
    @keyframes float {
      0%, 100% { transform: translateY(0); }
      50% { transform: translateY(-10px); }
    }

    .icon {
      animation: float 3s ease-in-out infinite;
    }

    /* Loading spinner for retry button */
    .retry-button.loading svg {
      animation: spin 1s linear infinite;
    }

    @keyframes spin {
      from { transform: rotate(0deg); }
      to { transform: rotate(360deg); }
    }
  </style>
</head>
<body>
  <div class="container">
    <!-- Offline Cloud Icon -->
    <div class="icon">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
        <path d="M3 15a4 4 0 0 0 4 4h9a5 5 0 0 0 0-10 5 5 0 0 0-9.9-.5A4 4 0 0 0 3 15z" />
        <line x1="1" y1="1" x2="23" y2="23" stroke-width="2" />
      </svg>
    </div>

    <h1>You're Offline</h1>

    <p>
      It looks like you've lost your internet connection.
      Don't worry - some features may still work offline.
    </p>

    <button class="retry-button" onclick="retry()">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
        <path d="M1 4v6h6M23 20v-6h-6" />
        <path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15" />
      </svg>
      Try Again
    </button>

    <p class="status" id="status">Waiting for connection...</p>
  </div>

  <script>
    // Update status when online/offline
    function updateStatus() {
      const statusEl = document.getElementById('status');
      if (navigator.onLine) {
        statusEl.textContent = 'Connection restored! Reloading...';
        statusEl.classList.add('online');
        setTimeout(() => window.location.reload(), 1000);
      } else {
        statusEl.textContent = 'Still offline...';
        statusEl.classList.remove('online');
      }
    }

    // Listen for online/offline events
    window.addEventListener('online', updateStatus);
    window.addEventListener('offline', updateStatus);

    // Retry button handler
    function retry() {
      const button = document.querySelector('.retry-button');
      button.classList.add('loading');
      button.disabled = true;

      // Check if we're online
      fetch(window.location.href, { method: 'HEAD', cache: 'no-store' })
        .then(() => {
          window.location.reload();
        })
        .catch(() => {
          button.classList.remove('loading');
          button.disabled = false;
          document.getElementById('status').textContent = 'Still no connection. Try again later.';
        });
    }

    // Initial status check
    if (navigator.onLine) {
      // We're online but got this page - might be a caching issue
      document.getElementById('status').textContent = 'Checking connection...';
      retry();
    }
  </script>
</body>
</html>

/**
 * Service Worker with Workbox
 *
 * A production-ready service worker using Workbox strategies.
 * Customize the caching strategies based on your app's needs.
 *
 * Usage with Vite PWA Plugin:
 *   This file is auto-generated. Configure in vite.config.ts
 *
 * Usage Standalone:
 *   1. Install Workbox: npm i workbox-precaching workbox-routing workbox-strategies workbox-expiration workbox-cacheable-response
 *   2. Build with bundler that handles workbox imports
 *   3. Register in your app entry point
 */

import { precacheAndRoute, cleanupOutdatedCaches, createHandlerBoundToURL } from 'workbox-precaching';
import { registerRoute, NavigationRoute } from 'workbox-routing';
import { CacheFirst, NetworkFirst, StaleWhileRevalidate, NetworkOnly } from 'workbox-strategies';
import { ExpirationPlugin } from 'workbox-expiration';
import { CacheableResponsePlugin } from 'workbox-cacheable-response';

declare let self: ServiceWorkerGlobalScope;

// === PRECACHING ===

// Clean up old precaches from previous versions
cleanupOutdatedCaches();

// Precache static assets (populated by build tool)
// The __WB_MANIFEST placeholder is replaced during build
precacheAndRoute(self.__WB_MANIFEST || []);

// === APP SHELL / NAVIGATION ===

// For SPA: return index.html for all navigation requests
// Uncomment if using SPA routing:
// const handler = createHandlerBoundToURL('/index.html');
// const navigationRoute = new NavigationRoute(handler, {
//   // Exclude specific paths from SPA handling
//   denylist: [/^\/api\//, /^\/auth\//],
// });
// registerRoute(navigationRoute);

// === CACHING STRATEGIES ===

// Static Assets (cache-first)
// For versioned assets with hash in filename
registerRoute(
  ({ request }) =>
    request.destination === 'style' ||
    request.destination === 'script' ||
    request.destination === 'font',
  new CacheFirst({
    cacheName: 'static-assets',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries: 100,
        maxAgeSeconds: 60 * 60 * 24 * 365, // 1 year
      }),
    ],
  })
);

// Images (cache-first with size limit)
registerRoute(
  ({ request }) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'images',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries: 100,
        maxAgeSeconds: 60 * 60 * 24 * 30, // 30 days
      }),
    ],
  })
);

// API Calls (network-first)
// Fresh data when online, cached data when offline
registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new NetworkFirst({
    cacheName: 'api-cache',
    networkTimeoutSeconds: 3, // Fall back to cache after 3s
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries: 50,
        maxAgeSeconds: 60 * 60 * 24, // 24 hours
      }),
    ],
  })
);

// HTML Pages (stale-while-revalidate)
// Fast load from cache, update in background
registerRoute(
  ({ request }) => request.destination === 'document',
  new StaleWhileRevalidate({
    cacheName: 'pages',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries: 50,
        maxAgeSeconds: 60 * 60 * 24 * 7, // 7 days
      }),
    ],
  })
);

// Third-party resources (stale-while-revalidate)
// CDN assets, analytics, etc.
registerRoute(
  ({ url }) => url.origin !== self.location.origin,
  new StaleWhileRevalidate({
    cacheName: 'third-party',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries: 30,
        maxAgeSeconds: 60 * 60 * 24, // 24 hours
      }),
    ],
  })
);

// === OFFLINE FALLBACK ===

import { setCatchHandler } from 'workbox-routing';
import { matchPrecache } from 'workbox-precaching';

// Fallback for failed requests
setCatchHandler(async ({ request }) => {
  // For navigation requests, show offline page
  if (request.destination === 'document') {
    return matchPrecache('/offline.html') || Response.error();
  }

  // For images, could return placeholder
  // if (request.destination === 'image') {
  //   return matchPrecache('/images/offline-placeholder.png');
  // }

  return Response.error();
});

// === UPDATE HANDLING ===

// Skip waiting - activate new SW immediately
// Only use if you handle update UI in your app
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// Claim clients on activation
// Makes SW take control of all pages immediately
self.addEventListener('activate', () => {
  self.clients.claim();
});

// === BACKGROUND SYNC (optional) ===

// Uncomment to enable background sync for failed POST requests
// import { BackgroundSyncPlugin } from 'workbox-background-sync';
//
// const bgSyncPlugin = new BackgroundSyncPlugin('failedRequestsQueue', {
//   maxRetentionTime: 24 * 60, // 24 hours in minutes
// });
//
// registerRoute(
//   ({ url }) => url.pathname.startsWith('/api/') && request.method === 'POST',
//   new NetworkOnly({
//     plugins: [bgSyncPlugin],
//   }),
//   'POST'
// );

// === PUSH NOTIFICATIONS (optional) ===

// Uncomment to handle push notifications
// self.addEventListener('push', (event) => {
//   const data = event.data?.json() ?? {};
//   const title = data.title || 'Notification';
//   const options = {
//     body: data.body,
//     icon: '/icons/icon-192x192.png',
//     badge: '/icons/badge-72x72.png',
//     data: data.url,
//   };
//   event.waitUntil(self.registration.showNotification(title, options));
// });
//
// self.addEventListener('notificationclick', (event) => {
//   event.notification.close();
//   if (event.notification.data) {
//     event.waitUntil(clients.openWindow(event.notification.data));
//   }
// });

<!--
  Svelte PWA Update Prompt Component

  Shows a notification when a new version of the app is available.
  Works with @vite-pwa/sveltekit's virtual:pwa-register/svelte module.

  Usage:
    1. Install @vite-pwa/sveltekit: npm i -D @vite-pwa/sveltekit
    2. Configure registerType: 'prompt' in vite.config.ts
    3. Add <ReloadPrompt /> to your +layout.svelte

  Customization:
    - Modify styles to match your app's design system
    - Adjust positioning with the .pwa-toast class
    - Add transitions as needed
-->

<script lang="ts">
  import { useRegisterSW } from 'virtual:pwa-register/svelte';
  import { fly } from 'svelte/transition';

  const {
    needRefresh,
    offlineReady,
    updateServiceWorker,
  } = useRegisterSW({
    onRegistered(registration) {
      console.log('SW registered:', registration);

      // Optional: Check for updates periodically
      // setInterval(() => {
      //   registration?.update();
      // }, 60 * 60 * 1000); // Check every hour
    },
    onRegisterError(error) {
      console.error('SW registration error:', error);
    },
  });

  let isUpdating = false;

  async function handleUpdate() {
    isUpdating = true;
    try {
      await updateServiceWorker(true);
    } catch (error) {
      console.error('Update failed:', error);
      isUpdating = false;
    }
  }

  function handleDismiss() {
    offlineReady.set(false);
    needRefresh.set(false);
  }
</script>

{#if $offlineReady || $needRefresh}
  <div
    class="pwa-toast"
    role="alert"
    aria-live="polite"
    transition:fly={{ x: 100, duration: 300 }}
  >
    <div class="content">
      {#if $offlineReady}
        <div class="title">Ready to work offline</div>
        <div class="message">
          App has been cached for offline use.
        </div>
      {:else}
        <div class="title">Update available</div>
        <div class="message">
          A new version is ready. Reload to update.
        </div>
      {/if}
    </div>

    <div class="buttons">
      {#if $needRefresh}
        <button
          class="update-button"
          on:click={handleUpdate}
          disabled={isUpdating}
        >
          {isUpdating ? 'Updating...' : 'Update'}
        </button>
      {/if}
      <button
        class="dismiss-button"
        on:click={handleDismiss}
      >
        Dismiss
      </button>
    </div>
  </div>
{/if}

<style>
  .pwa-toast {
    position: fixed;
    bottom: 20px;
    right: 20px;
    padding: 16px 20px;
    background-color: #1f2937;
    color: white;
    border-radius: 12px;
    box-shadow: 0 10px 40px rgba(0, 0, 0, 0.3);
    display: flex;
    align-items: center;
    gap: 16px;
    z-index: 9999;
    max-width: 400px;
  }

  .content {
    flex: 1;
  }

  .title {
    font-weight: 600;
    margin-bottom: 4px;
    font-size: 14px;
  }

  .message {
    font-size: 13px;
    opacity: 0.8;
    line-height: 1.4;
  }

  .buttons {
    display: flex;
    gap: 8px;
    flex-shrink: 0;
  }

  .update-button {
    background-color: #3b82f6;
    color: white;
    border: none;
    padding: 8px 16px;
    border-radius: 6px;
    cursor: pointer;
    font-weight: 500;
    font-size: 13px;
    transition: background-color 0.2s;
  }

  .update-button:hover:not(:disabled) {
    background-color: #2563eb;
  }

  .update-button:disabled {
    opacity: 0.7;
    cursor: not-allowed;
  }

  .dismiss-button {
    background-color: transparent;
    color: #9ca3af;
    border: 1px solid #374151;
    padding: 8px 16px;
    border-radius: 6px;
    cursor: pointer;
    font-weight: 500;
    font-size: 13px;
    transition: background-color 0.2s, border-color 0.2s;
  }

  .dismiss-button:hover {
    background-color: #374151;
    border-color: #4b5563;
  }

  /* Responsive adjustments */
  @media (max-width: 480px) {
    .pwa-toast {
      left: 20px;
      right: 20px;
      bottom: 10px;
      flex-direction: column;
      text-align: center;
    }

    .buttons {
      width: 100%;
      justify-content: center;
    }
  }
</style>

<!--
  TypeScript declaration for virtual module
  Add this to src/app.d.ts or a .d.ts file:

  declare module 'virtual:pwa-register/svelte' {
    import type { Writable } from 'svelte/store';

    export interface RegisterSWOptions {
      immediate?: boolean;
      onNeedRefresh?: () => void;
      onOfflineReady?: () => void;
      onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void;
      onRegisterError?: (error: Error) => void;
    }

    export function useRegisterSW(options?: RegisterSWOptions): {
      needRefresh: Writable<boolean>;
      offlineReady: Writable<boolean>;
      updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
    };
  }
-->

/**
 * React PWA Update Prompt Component
 *
 * Shows a notification when a new version of the app is available.
 * Works with vite-plugin-pwa's virtual:pwa-register/react module.
 *
 * Usage:
 *   1. Install vite-plugin-pwa: npm i -D vite-plugin-pwa
 *   2. Configure registerType: 'prompt' in vite.config.ts
 *   3. Add <ReloadPrompt /> to your App component
 *
 * Customization:
 *   - Modify styles to match your app's design system
 *   - Adjust positioning with the .pwa-toast class
 *   - Add animations as needed
 */

import { useRegisterSW } from 'virtual:pwa-register/react';
import { useState, useEffect } from 'react';

// Styles - customize to match your design system
const styles = {
  toast: {
    position: 'fixed' as const,
    bottom: '20px',
    right: '20px',
    padding: '16px 20px',
    backgroundColor: '#1f2937',
    color: 'white',
    borderRadius: '12px',
    boxShadow: '0 10px 40px rgba(0, 0, 0, 0.3)',
    display: 'flex',
    alignItems: 'center',
    gap: '16px',
    zIndex: 9999,
    maxWidth: '400px',
    animation: 'slideIn 0.3s ease-out',
  },
  content: {
    flex: 1,
  },
  title: {
    fontWeight: 600,
    marginBottom: '4px',
    fontSize: '14px',
  },
  message: {
    fontSize: '13px',
    opacity: 0.8,
    lineHeight: 1.4,
  },
  buttons: {
    display: 'flex',
    gap: '8px',
    flexShrink: 0,
  },
  updateButton: {
    backgroundColor: '#3b82f6',
    color: 'white',
    border: 'none',
    padding: '8px 16px',
    borderRadius: '6px',
    cursor: 'pointer',
    fontWeight: 500,
    fontSize: '13px',
    transition: 'background-color 0.2s',
  },
  dismissButton: {
    backgroundColor: 'transparent',
    color: '#9ca3af',
    border: '1px solid #374151',
    padding: '8px 16px',
    borderRadius: '6px',
    cursor: 'pointer',
    fontWeight: 500,
    fontSize: '13px',
    transition: 'background-color 0.2s, border-color 0.2s',
  },
};

// CSS animation (add to your global styles or inject)
const keyframes = `
  @keyframes slideIn {
    from {
      transform: translateX(100%);
      opacity: 0;
    }
    to {
      transform: translateX(0);
      opacity: 1;
    }
  }
`;

export function ReloadPrompt() {
  const {
    offlineReady: [offlineReady, setOfflineReady],
    needRefresh: [needRefresh, setNeedRefresh],
    updateServiceWorker,
  } = useRegisterSW({
    onRegistered(registration) {
      console.log('SW registered:', registration);

      // Optional: Check for updates periodically
      // setInterval(() => {
      //   registration?.update();
      // }, 60 * 60 * 1000); // Check every hour
    },
    onRegisterError(error) {
      console.error('SW registration error:', error);
    },
  });

  const [isUpdating, setIsUpdating] = useState(false);

  // Inject keyframes on mount
  useEffect(() => {
    const style = document.createElement('style');
    style.textContent = keyframes;
    document.head.appendChild(style);
    return () => {
      document.head.removeChild(style);
    };
  }, []);

  const handleUpdate = async () => {
    setIsUpdating(true);
    try {
      await updateServiceWorker(true);
    } catch (error) {
      console.error('Update failed:', error);
      setIsUpdating(false);
    }
  };

  const handleDismiss = () => {
    setOfflineReady(false);
    setNeedRefresh(false);
  };

  // Show nothing if no updates and not offline-ready
  if (!offlineReady && !needRefresh) {
    return null;
  }

  return (
    <div style={styles.toast} role="alert" aria-live="polite">
      <div style={styles.content}>
        {offlineReady ? (
          <>
            <div style={styles.title}>Ready to work offline</div>
            <div style={styles.message}>
              App has been cached for offline use.
            </div>
          </>
        ) : (
          <>
            <div style={styles.title}>Update available</div>
            <div style={styles.message}>
              A new version is ready. Reload to update.
            </div>
          </>
        )}
      </div>

      <div style={styles.buttons}>
        {needRefresh && (
          <button
            style={styles.updateButton}
            onClick={handleUpdate}
            disabled={isUpdating}
          >
            {isUpdating ? 'Updating...' : 'Update'}
          </button>
        )}
        <button
          style={styles.dismissButton}
          onClick={handleDismiss}
        >
          Dismiss
        </button>
      </div>
    </div>
  );
}

// Alternative: Minimal version with just the hook
export function useUpdatePrompt() {
  const {
    offlineReady: [offlineReady],
    needRefresh: [needRefresh],
    updateServiceWorker,
  } = useRegisterSW();

  return {
    offlineReady,
    needRefresh,
    update: () => updateServiceWorker(true),
  };
}

// TypeScript module declaration for virtual module
declare module 'virtual:pwa-register/react' {
  import type { Dispatch, SetStateAction } from 'react';

  export interface RegisterSWOptions {
    immediate?: boolean;
    onNeedRefresh?: () => void;
    onOfflineReady?: () => void;
    onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void;
    onRegisterError?: (error: Error) => void;
  }

  export function useRegisterSW(options?: RegisterSWOptions): {
    needRefresh: [boolean, Dispatch<SetStateAction<boolean>>];
    offlineReady: [boolean, Dispatch<SetStateAction<boolean>>];
    updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
  };
}

export default ReloadPrompt;

{
  "_meta": {
    "description": "Caching strategy decision matrix for PWA development",
    "usage": "Match resource type to recommended strategy based on freshness vs speed trade-offs",
    "source": "pwa-development skill"
  },
  "strategies": {
    "cache-first": {
      "description": "Check cache first, fall back to network",
      "workbox_class": "CacheFirst",
      "best_for": [
        "Static assets with versioned URLs",
        "Fonts (rarely change)",
        "Images (content images, icons)",
        "App shell HTML (if using app shell pattern)",
        "Third-party libraries with version in URL"
      ],
      "avoid_for": [
        "API responses",
        "Frequently updated content",
        "User-specific data",
        "Opaque responses (CORS without proper headers)"
      ],
      "trade_offs": {
        "speed": "fastest",
        "freshness": "may serve stale",
        "offline": "works offline if cached"
      },
      "typical_config": {
        "maxAgeSeconds": 31536000,
        "maxEntries": 100
      }
    },
    "network-first": {
      "description": "Try network first, fall back to cache",
      "workbox_class": "NetworkFirst",
      "best_for": [
        "API calls",
        "Frequently updated content",
        "HTML pages (if not app shell)",
        "User-specific data",
        "Authenticated content"
      ],
      "avoid_for": [
        "Large static assets (slow repeated downloads)",
        "Resources needed for offline-critical paths"
      ],
      "trade_offs": {
        "speed": "slower (network latency)",
        "freshness": "always fresh when online",
        "offline": "works offline with cached fallback"
      },
      "typical_config": {
        "networkTimeoutSeconds": 3,
        "maxAgeSeconds": 86400,
        "maxEntries": 50
      }
    },
    "stale-while-revalidate": {
      "description": "Return cache immediately, update in background",
      "workbox_class": "StaleWhileRevalidate",
      "best_for": [
        "Semi-static content (articles, product listings)",
        "User avatars",
        "CSS/JS bundles without versioned URLs",
        "Content where eventual consistency is acceptable"
      ],
      "avoid_for": [
        "Real-time data (stock prices, live scores)",
        "Checkout/payment flows",
        "Critical user settings",
        "Opaque responses"
      ],
      "trade_offs": {
        "speed": "fast (serves cache)",
        "freshness": "eventually fresh (next load)",
        "offline": "works offline if cached"
      },
      "typical_config": {
        "maxAgeSeconds": 86400,
        "maxEntries": 50
      }
    },
    "network-only": {
      "description": "Always fetch from network, no caching",
      "workbox_class": "NetworkOnly",
      "best_for": [
        "Analytics endpoints",
        "Authentication/logout endpoints",
        "Real-time APIs (WebSocket fallback)",
        "POST/PUT/DELETE requests"
      ],
      "avoid_for": [
        "Anything needed for offline functionality"
      ],
      "trade_offs": {
        "speed": "network dependent",
        "freshness": "always fresh",
        "offline": "fails offline"
      },
      "typical_config": {}
    },
    "cache-only": {
      "description": "Only serve from cache, never network",
      "workbox_class": "CacheOnly",
      "best_for": [
        "Precached assets that never change",
        "Versioned bundles (hash in filename)",
        "Offline fallback pages"
      ],
      "avoid_for": [
        "Anything that might need updating",
        "Dynamic content"
      ],
      "trade_offs": {
        "speed": "fastest",
        "freshness": "never updates",
        "offline": "works offline if precached"
      },
      "typical_config": {}
    }
  },
  "resource_type_recommendations": {
    "html_pages": {
      "app_like": "cache-first",
      "content_heavy": "network-first",
      "data_intensive": "cache-first",
      "hybrid": "stale-while-revalidate"
    },
    "css_bundles": {
      "versioned_url": "cache-first",
      "unversioned_url": "stale-while-revalidate"
    },
    "js_bundles": {
      "versioned_url": "cache-first",
      "unversioned_url": "stale-while-revalidate"
    },
    "images": {
      "static": "cache-first",
      "user_uploaded": "cache-first",
      "frequently_updated": "stale-while-revalidate"
    },
    "fonts": {
      "default": "cache-first"
    },
    "api_get": {
      "default": "network-first",
      "cached_for_offline": "network-first"
    },
    "api_post": {
      "default": "network-only"
    },
    "third_party": {
      "default": "stale-while-revalidate"
    }
  },
  "decision_tree": {
    "questions": [
      {
        "question": "Does the resource have a versioned URL (hash in filename)?",
        "yes": "cache-first",
        "no": "continue"
      },
      {
        "question": "Is the resource an API call?",
        "yes": "network-first",
        "no": "continue"
      },
      {
        "question": "Does the content change frequently?",
        "yes": "network-first or stale-while-revalidate",
        "no": "continue"
      },
      {
        "question": "Is eventual consistency acceptable?",
        "yes": "stale-while-revalidate",
        "no": "network-first"
      }
    ]
  }
}

{
  "_meta": {
    "description": "Framework-specific PWA implementation patterns",
    "frameworks": ["vite", "sveltekit", "nextjs", "create-react-app"],
    "source": "pwa-development skill"
  },
  "vite": {
    "plugin": "vite-plugin-pwa",
    "install": "npm i -D vite-plugin-pwa",
    "version": "^0.20.0",
    "config_location": "vite.config.ts",
    "documentation": "https://vite-pwa-org.netlify.app/",
    "dev_mode_note": "Service worker disabled in dev by default. Use devOptions: { enabled: true } to test.",
    "basic_config": {
      "description": "Minimal configuration for Vite PWA plugin",
      "code": "import { VitePWA } from 'vite-plugin-pwa';\n\nexport default defineConfig({\n  plugins: [\n    VitePWA({\n      registerType: 'prompt',\n      manifest: {\n        name: 'My App',\n        short_name: 'App',\n        theme_color: '#ffffff',\n        icons: [\n          { src: 'pwa-192x192.png', sizes: '192x192', type: 'image/png' },\n          { src: 'pwa-512x512.png', sizes: '512x512', type: 'image/png' }\n        ]\n      }\n    })\n  ]\n});"
    },
    "with_prompt_config": {
      "description": "Configuration with update prompt UI",
      "code": "import { VitePWA } from 'vite-plugin-pwa';\n\nexport default defineConfig({\n  plugins: [\n    VitePWA({\n      registerType: 'prompt',\n      includeAssets: ['favicon.ico', 'apple-touch-icon.png'],\n      manifest: { /* ... */ },\n      workbox: {\n        globPatterns: ['**/*.{js,css,html,ico,png,svg}']\n      }\n    })\n  ]\n});"
    },
    "auto_update_config": {
      "description": "Configuration for automatic silent updates",
      "code": "VitePWA({\n  registerType: 'autoUpdate',\n  // ... rest of config\n})"
    },
    "runtime_caching": {
      "description": "Add runtime caching for API calls",
      "code": "workbox: {\n  runtimeCaching: [\n    {\n      urlPattern: /^https:\\/\\/api\\.example\\.com\\/.*/i,\n      handler: 'NetworkFirst',\n      options: {\n        cacheName: 'api-cache',\n        expiration: {\n          maxEntries: 50,\n          maxAgeSeconds: 60 * 60 * 24\n        }\n      }\n    }\n  ]\n}"
    },
    "react_prompt_component": {
      "description": "React component for update prompt",
      "code": "import { useRegisterSW } from 'virtual:pwa-register/react';\n\nfunction ReloadPrompt() {\n  const {\n    needRefresh: [needRefresh, setNeedRefresh],\n    updateServiceWorker,\n  } = useRegisterSW();\n\n  return needRefresh && (\n    <div className=\"pwa-toast\">\n      <span>New version available!</span>\n      <button onClick={() => updateServiceWorker(true)}>Update</button>\n      <button onClick={() => setNeedRefresh(false)}>Close</button>\n    </div>\n  );\n}"
    }
  },
  "sveltekit": {
    "plugin": "@vite-pwa/sveltekit",
    "install": "npm i -D @vite-pwa/sveltekit",
    "version": "^0.6.0",
    "config_location": "vite.config.ts",
    "service_worker_location": "src/service-worker.ts",
    "documentation": "https://vite-pwa-org.netlify.app/frameworks/sveltekit.html",
    "native_sw_note": "SvelteKit has built-in SW support via src/service-worker.ts. Use plugin for more features.",
    "basic_config": {
      "description": "Basic SvelteKit PWA configuration",
      "code": "import { sveltekit } from '@sveltejs/kit/vite';\nimport { SvelteKitPWA } from '@vite-pwa/sveltekit';\n\nexport default defineConfig({\n  plugins: [\n    sveltekit(),\n    SvelteKitPWA({\n      manifest: {\n        name: 'My SvelteKit App',\n        short_name: 'App',\n        theme_color: '#ffffff',\n        icons: [\n          { src: 'pwa-192x192.png', sizes: '192x192', type: 'image/png' },\n          { src: 'pwa-512x512.png', sizes: '512x512', type: 'image/png' }\n        ]\n      }\n    })\n  ]\n});"
    },
    "native_sw": {
      "description": "Using SvelteKit's built-in service worker",
      "location": "src/service-worker.ts",
      "code": "/// <reference types=\"@sveltejs/kit\" />\n/// <reference no-default-lib=\"true\"/>\n/// <reference lib=\"esnext\" />\n/// <reference lib=\"webworker\" />\n\nimport { build, files, version } from '$service-worker';\n\nconst CACHE = `cache-${version}`;\nconst ASSETS = [...build, ...files];\n\nself.addEventListener('install', (event) => {\n  event.waitUntil(\n    caches.open(CACHE)\n      .then((cache) => cache.addAll(ASSETS))\n      .then(() => self.skipWaiting())\n  );\n});\n\nself.addEventListener('activate', (event) => {\n  event.waitUntil(\n    caches.keys().then((keys) => {\n      return Promise.all(\n        keys.filter((key) => key !== CACHE).map((key) => caches.delete(key))\n      );\n    })\n  );\n});\n\nself.addEventListener('fetch', (event) => {\n  if (event.request.method !== 'GET') return;\n  \n  event.respondWith(\n    caches.match(event.request)\n      .then((cached) => cached || fetch(event.request))\n  );\n});"
    },
    "svelte_prompt_component": {
      "description": "Svelte component for update prompt",
      "code": "<script>\n  import { useRegisterSW } from 'virtual:pwa-register/svelte';\n  \n  const { needRefresh, updateServiceWorker } = useRegisterSW();\n</script>\n\n{#if $needRefresh}\n  <div class=\"pwa-toast\">\n    <span>New version available!</span>\n    <button on:click={() => updateServiceWorker(true)}>Update</button>\n    <button on:click={() => needRefresh.set(false)}>Close</button>\n  </div>\n{/if}"
    }
  },
  "nextjs": {
    "plugin": "next-pwa",
    "install": "npm i next-pwa",
    "version": "^5.6.0",
    "config_location": "next.config.js",
    "documentation": "https://github.com/shadowwalker/next-pwa",
    "notes": [
      "Creates sw.js and workbox files automatically",
      "Disable in development to avoid caching issues"
    ],
    "basic_config": {
      "description": "Basic Next.js PWA configuration",
      "code": "const withPWA = require('next-pwa')({\n  dest: 'public',\n  disable: process.env.NODE_ENV === 'development'\n});\n\nmodule.exports = withPWA({\n  // Your Next.js config\n});"
    },
    "with_caching": {
      "description": "Configuration with custom runtime caching",
      "code": "const withPWA = require('next-pwa')({\n  dest: 'public',\n  disable: process.env.NODE_ENV === 'development',\n  runtimeCaching: [\n    {\n      urlPattern: /^https:\\/\\/api\\./,\n      handler: 'NetworkFirst',\n      options: {\n        cacheName: 'api-cache',\n        expiration: {\n          maxEntries: 50,\n          maxAgeSeconds: 60 * 60 * 24\n        }\n      }\n    }\n  ]\n});\n\nmodule.exports = withPWA({});"
    },
    "manifest_location": "public/manifest.json",
    "manifest_link": "<link rel=\"manifest\" href=\"/manifest.json\" />"
  },
  "create_react_app": {
    "status": "legacy",
    "note": "CRA has limited PWA support. Consider migrating to Vite.",
    "built_in_sw": "src/serviceWorkerRegistration.js",
    "enable_sw": {
      "description": "Enable service worker in CRA",
      "code": "// In src/index.js, change:\nserviceWorkerRegistration.unregister();\n// to:\nserviceWorkerRegistration.register();"
    },
    "manifest_location": "public/manifest.json",
    "limitations": [
      "Less control over caching strategies",
      "No Workbox integration by default",
      "Limited customization options"
    ],
    "migration_recommendation": "Migrate to Vite using 'npm create vite@latest' for better PWA support"
  },
  "common_patterns": {
    "register_service_worker": {
      "description": "Manual service worker registration",
      "code": "if ('serviceWorker' in navigator) {\n  window.addEventListener('load', () => {\n    navigator.serviceWorker.register('/sw.js')\n      .then((reg) => console.log('SW registered:', reg.scope))\n      .catch((err) => console.error('SW registration failed:', err));\n  });\n}"
    },
    "update_detection": {
      "description": "Detect and handle service worker updates",
      "code": "navigator.serviceWorker.register('/sw.js').then((reg) => {\n  reg.addEventListener('updatefound', () => {\n    const newWorker = reg.installing;\n    newWorker.addEventListener('statechange', () => {\n      if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {\n        // New version available\n        showUpdateNotification();\n      }\n    });\n  });\n});"
    },
    "force_update": {
      "description": "Force update and reload",
      "code": "function updateApp() {\n  navigator.serviceWorker.ready.then((reg) => {\n    reg.waiting?.postMessage({ type: 'SKIP_WAITING' });\n  });\n  window.location.reload();\n}"
    }
  }
}

{
  "_meta": {
    "description": "iOS PWA quirks, limitations, and workarounds",
    "last_updated": "2025-01",
    "ios_versions_covered": ["15", "16", "17", "18"],
    "source": "pwa-development skill"
  },
  "quirks": {
    "no_beforeinstallprompt": {
      "description": "iOS Safari does not fire the beforeinstallprompt event",
      "impact": "Cannot programmatically detect installability or show custom install prompt",
      "affected_versions": "all",
      "workaround": "Show manual 'Add to Home Screen' instructions for iOS users",
      "detection": "Check for iOS via userAgent: /iPhone|iPad|iPod/.test(navigator.userAgent) && !window.MSStream",
      "code_example": "if (iOS && !window.matchMedia('(display-mode: standalone)').matches) { showIOSInstallBanner(); }"
    },
    "storage_eviction": {
      "description": "WebKit may evict storage after 7 days of non-use",
      "impact": "IndexedDB and Cache Storage data may be deleted if PWA not accessed",
      "affected_versions": "all",
      "workaround": "Request persistent storage, sync critical data to server, design for data loss",
      "detection": "navigator.storage.persisted() to check persistence status",
      "code_example": "const persistent = await navigator.storage.persist(); // Returns false on iOS"
    },
    "cache_storage_limit": {
      "description": "Cache Storage limited to approximately 50MB",
      "impact": "Cannot cache large amounts of content for offline use",
      "affected_versions": "all",
      "workaround": "Be selective about what to cache, implement LRU eviction, use IndexedDB for structured data",
      "detection": "navigator.storage.estimate() returns quota information"
    },
    "no_push_before_16.4": {
      "description": "Push notifications not supported until iOS 16.4",
      "impact": "Cannot send push notifications to older iOS devices",
      "affected_versions": "< 16.4",
      "fixed_in": "16.4",
      "workaround": "Use in-app polling, email notifications, or inform users of limitation",
      "detection": "Check iOS version and 'PushManager' in window"
    },
    "push_requires_home_screen": {
      "description": "Push notifications only work when PWA is installed to home screen",
      "impact": "Safari browser PWAs don't receive push notifications even on 16.4+",
      "affected_versions": "16.4+",
      "workaround": "Prompt users to add to home screen before enabling notifications",
      "detection": "window.matchMedia('(display-mode: standalone)').matches"
    },
    "no_background_sync": {
      "description": "Background Sync API not supported on iOS",
      "impact": "Cannot queue and retry failed requests in background",
      "affected_versions": "all",
      "workaround": "Store pending actions in IndexedDB, retry on next app open",
      "detection": "'SyncManager' in window"
    },
    "scope_navigation": {
      "description": "Navigating outside PWA scope opens Safari instead of staying in app",
      "impact": "External links and out-of-scope pages break the app experience",
      "affected_versions": "all",
      "workaround": "Keep all content within scope, use target='_blank' intentionally for external links",
      "detection": "N/A - design consideration"
    },
    "status_bar_styling": {
      "description": "Status bar appearance requires specific meta tags",
      "impact": "Status bar may clash with app theme or be unreadable",
      "affected_versions": "all",
      "workaround": "Add apple-mobile-web-app-status-bar-style meta tag",
      "meta_tags": [
        "<meta name=\"apple-mobile-web-app-status-bar-style\" content=\"default\">",
        "<meta name=\"apple-mobile-web-app-status-bar-style\" content=\"black\">",
        "<meta name=\"apple-mobile-web-app-status-bar-style\" content=\"black-translucent\">"
      ],
      "options": {
        "default": "Black text, white background",
        "black": "White text, black background",
        "black-translucent": "White text, app content extends behind status bar"
      }
    },
    "splash_screen_caching": {
      "description": "Splash screen aggressively cached, may not update with manifest changes",
      "impact": "Old splash screen shows even after manifest updates",
      "affected_versions": "all",
      "workaround": "Change start_url query parameter to bust cache (e.g., /?v=2)",
      "code_example": "\"start_url\": \"/?v=2\""
    },
    "apple_touch_icon_required": {
      "description": "iOS ignores manifest icons, requires separate apple-touch-icon link",
      "impact": "Home screen icon may be wrong or missing",
      "affected_versions": "all",
      "workaround": "Add apple-touch-icon link tag",
      "meta_tags": [
        "<link rel=\"apple-touch-icon\" href=\"/apple-touch-icon.png\">",
        "<link rel=\"apple-touch-icon\" sizes=\"180x180\" href=\"/apple-touch-icon-180x180.png\">"
      ],
      "recommended_size": "180x180"
    },
    "indexeddb_private_browsing": {
      "description": "IndexedDB quota severely limited in private browsing",
      "impact": "Storage operations may fail in private browsing mode",
      "affected_versions": "all",
      "workaround": "Detect private mode, show warning, use localStorage fallback for small data",
      "detection": "Try to use IndexedDB and catch QuotaExceededError"
    },
    "audio_autoplay_restrictions": {
      "description": "Audio/video autoplay requires user interaction first",
      "impact": "Background audio, notification sounds may not play",
      "affected_versions": "all",
      "workaround": "Wait for user gesture (click/tap) before playing audio"
    },
    "no_file_system_access": {
      "description": "File System Access API not supported",
      "impact": "Cannot read/write local files like native apps",
      "affected_versions": "all",
      "workaround": "Use input[type=file] for file selection, download links for saving"
    },
    "orientation_lock_limitations": {
      "description": "Screen orientation lock may not work reliably",
      "impact": "App may rotate unexpectedly",
      "affected_versions": "varies",
      "workaround": "Design responsive layouts, use CSS media queries for orientation"
    }
  },
  "required_meta_tags": [
    {
      "tag": "<meta name=\"apple-mobile-web-app-capable\" content=\"yes\">",
      "purpose": "Enable standalone mode on iOS"
    },
    {
      "tag": "<meta name=\"apple-mobile-web-app-title\" content=\"App Name\">",
      "purpose": "Set app title on home screen"
    },
    {
      "tag": "<link rel=\"apple-touch-icon\" href=\"/apple-touch-icon.png\">",
      "purpose": "Home screen icon"
    },
    {
      "tag": "<meta name=\"apple-mobile-web-app-status-bar-style\" content=\"default\">",
      "purpose": "Status bar styling"
    },
    {
      "tag": "<meta name=\"theme-color\" content=\"#ffffff\">",
      "purpose": "Theme color (also needed in manifest)"
    }
  ],
  "testing_checklist": [
    "Test on actual iOS device (not just Chrome DevTools simulation)",
    "Test add to home screen flow",
    "Test offline functionality after 7+ days of non-use",
    "Test storage eviction by filling storage then waiting",
    "Verify splash screen appearance",
    "Check status bar styling",
    "Test orientation changes",
    "Verify push notifications (iOS 16.4+, home screen only)",
    "Test Safari browser vs installed PWA behavior differences"
  ]
}

{
  "_meta": {
    "description": "Complete Web App Manifest property reference",
    "specification": "https://www.w3.org/TR/appmanifest/",
    "source": "pwa-development skill"
  },
  "required_fields": {
    "name": {
      "type": "string",
      "description": "Full name of the application",
      "max_length": 45,
      "example": "My Awesome Application",
      "used_for": "Install prompt, app launcher, splash screen"
    },
    "short_name": {
      "type": "string",
      "description": "Short name for home screen and limited space",
      "max_length": 12,
      "example": "MyApp",
      "used_for": "Home screen icon label"
    },
    "start_url": {
      "type": "string",
      "description": "URL to open when app is launched",
      "example": "/",
      "notes": "Should be within scope. Can include query params for analytics."
    },
    "display": {
      "type": "enum",
      "description": "How the app should be displayed",
      "values": {
        "fullscreen": "Takes up entire display, no browser UI",
        "standalone": "Looks like native app, minimal browser UI",
        "minimal-ui": "Some browser UI elements visible",
        "browser": "Opens in normal browser tab"
      },
      "default": "browser",
      "recommended": "standalone"
    },
    "icons": {
      "type": "array",
      "description": "Array of icon objects for various uses",
      "required_sizes": ["192x192", "512x512"],
      "properties": {
        "src": "Path to icon file",
        "sizes": "Icon dimensions (e.g., '192x192')",
        "type": "MIME type (e.g., 'image/png')",
        "purpose": "Icon purpose: 'any', 'maskable', or 'any maskable'"
      },
      "example": [
        { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
        { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
        { "src": "/icons/icon-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
      ]
    }
  },
  "recommended_fields": {
    "background_color": {
      "type": "string",
      "description": "Background color for splash screen",
      "format": "CSS color (hex, rgb, named)",
      "example": "#ffffff",
      "notes": "Should match app's initial background"
    },
    "theme_color": {
      "type": "string",
      "description": "Theme color for browser UI and title bar",
      "format": "CSS color (hex, rgb, named)",
      "example": "#4285f4",
      "notes": "Also add as <meta name='theme-color'> for broader support"
    },
    "description": {
      "type": "string",
      "description": "Description of the application",
      "max_length": 300,
      "example": "A productivity app for managing daily tasks",
      "used_for": "App stores, search results"
    },
    "scope": {
      "type": "string",
      "description": "Navigation scope - URLs outside open in browser",
      "example": "/app/",
      "default": "Parent directory of start_url",
      "notes": "start_url must be within scope"
    },
    "orientation": {
      "type": "enum",
      "description": "Default orientation for the app",
      "values": ["any", "natural", "portrait", "portrait-primary", "portrait-secondary", "landscape", "landscape-primary", "landscape-secondary"],
      "default": "any"
    }
  },
  "optional_fields": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the app",
      "example": "com.example.myapp",
      "notes": "Helps with app identity across manifest changes"
    },
    "screenshots": {
      "type": "array",
      "description": "Screenshots for richer install UI",
      "properties": {
        "src": "Path to screenshot",
        "sizes": "Dimensions",
        "type": "MIME type",
        "form_factor": "'narrow' (mobile) or 'wide' (desktop)",
        "label": "Description of screenshot"
      },
      "example": [
        { "src": "/screenshots/mobile.png", "sizes": "1080x1920", "type": "image/png", "form_factor": "narrow" },
        { "src": "/screenshots/desktop.png", "sizes": "1920x1080", "type": "image/png", "form_factor": "wide" }
      ]
    },
    "shortcuts": {
      "type": "array",
      "description": "App shortcuts for quick actions (right-click menu)",
      "properties": {
        "name": "Shortcut label",
        "short_name": "Short label",
        "description": "Shortcut description",
        "url": "URL to open",
        "icons": "Icon for shortcut"
      },
      "example": [
        { "name": "New Task", "url": "/tasks/new", "icons": [{ "src": "/icons/new-task.png", "sizes": "96x96" }] }
      ]
    },
    "categories": {
      "type": "array",
      "description": "App store categories",
      "values": ["books", "business", "education", "entertainment", "finance", "fitness", "food", "games", "government", "health", "kids", "lifestyle", "magazines", "medical", "music", "navigation", "news", "personalization", "photo", "politics", "productivity", "security", "shopping", "social", "sports", "travel", "utilities", "weather"],
      "example": ["productivity", "utilities"]
    },
    "related_applications": {
      "type": "array",
      "description": "Related native apps",
      "properties": {
        "platform": "App store platform",
        "url": "App store URL",
        "id": "App ID"
      },
      "example": [
        { "platform": "play", "url": "https://play.google.com/store/apps/details?id=com.example", "id": "com.example" }
      ]
    },
    "prefer_related_applications": {
      "type": "boolean",
      "description": "Prefer native app over PWA",
      "default": false,
      "notes": "Set true to prefer native app install"
    },
    "dir": {
      "type": "enum",
      "description": "Text direction",
      "values": ["auto", "ltr", "rtl"],
      "default": "auto"
    },
    "lang": {
      "type": "string",
      "description": "Primary language",
      "format": "BCP 47 language tag",
      "example": "en-US"
    },
    "iarc_rating_id": {
      "type": "string",
      "description": "IARC certification code for content rating",
      "notes": "Required for some app stores"
    }
  },
  "advanced_fields": {
    "share_target": {
      "type": "object",
      "description": "Enable app as share target",
      "properties": {
        "action": "URL to handle share",
        "method": "HTTP method (GET or POST)",
        "enctype": "Encoding type for POST",
        "params": "Parameter mapping"
      },
      "example": {
        "action": "/share",
        "method": "POST",
        "enctype": "multipart/form-data",
        "params": {
          "title": "title",
          "text": "text",
          "url": "url",
          "files": [{ "name": "media", "accept": ["image/*"] }]
        }
      }
    },
    "protocol_handlers": {
      "type": "array",
      "description": "Handle custom URL protocols",
      "properties": {
        "protocol": "Protocol scheme (without ://)",
        "url": "Handler URL with %s placeholder"
      },
      "example": [
        { "protocol": "web+myapp", "url": "/open?url=%s" }
      ]
    },
    "file_handlers": {
      "type": "array",
      "description": "Handle file types",
      "properties": {
        "action": "Handler URL",
        "accept": "Object mapping MIME types to extensions"
      },
      "example": [
        { "action": "/open-file", "accept": { "text/plain": [".txt"] } }
      ]
    },
    "launch_handler": {
      "type": "object",
      "description": "Control launch behavior",
      "properties": {
        "client_mode": ["auto", "navigate-new", "navigate-existing", "focus-existing"]
      }
    },
    "handle_links": {
      "type": "enum",
      "description": "How to handle links clicked in other apps",
      "values": ["auto", "preferred", "not-preferred"],
      "notes": "Experimental feature"
    }
  },
  "validation_rules": [
    "name is required and should be <= 45 characters",
    "short_name is required and should be <= 12 characters",
    "start_url is required and must be within scope",
    "icons must include at least 192x192 and 512x512 sizes",
    "display must be one of: fullscreen, standalone, minimal-ui, browser",
    "Colors should be valid CSS color values",
    "URLs should be relative paths or absolute URLs within same origin"
  ]
}

#!/usr/bin/env -S deno run --allow-read

/**
 * Cache Strategy Advisor
 *
 * Recommends caching strategies based on app type and resource inventory.
 * Uses decision matrix from caching-strategies.json.
 *
 * Usage:
 *   deno run --allow-read cache-strategy-advisor.ts --app-type content-heavy
 *   deno run --allow-read cache-strategy-advisor.ts --app-type app-like
 *   deno run --allow-read cache-strategy-advisor.ts --resources resources.json
 */

// === INTERFACES ===

type AppType = "content-heavy" | "app-like" | "data-intensive" | "hybrid";
type CachingStrategy = "cache-first" | "network-first" | "stale-while-revalidate" | "network-only" | "cache-only";
type ResourceType = "html" | "css" | "js" | "images" | "fonts" | "api" | "video" | "audio" | "documents" | "third-party";

interface ResourceEntry {
  path: string;
  type: ResourceType;
  changeFrequency?: "never" | "rarely" | "sometimes" | "often" | "always";
  size?: "small" | "medium" | "large";
  critical?: boolean;
}

interface StrategyRecommendation {
  resourceType: ResourceType;
  strategy: CachingStrategy;
  cacheName: string;
  maxAge?: number;
  maxEntries?: number;
  reasoning: string;
}

interface AppTypeProfile {
  description: string;
  defaultStrategies: Record<ResourceType, CachingStrategy>;
  precacheRecommendation: string[];
  notes: string[];
}

// === DECISION MATRIX ===

const APP_TYPE_PROFILES: Record<AppType, AppTypeProfile> = {
  "content-heavy": {
    description: "Blogs, news sites, documentation - content changes but should be readable offline",
    defaultStrategies: {
      html: "network-first",
      css: "stale-while-revalidate",
      js: "stale-while-revalidate",
      images: "cache-first",
      fonts: "cache-first",
      api: "network-first",
      video: "cache-first",
      audio: "cache-first",
      documents: "cache-first",
      "third-party": "stale-while-revalidate",
    },
    precacheRecommendation: ["app shell", "critical CSS", "fonts", "logo"],
    notes: [
      "Use stale-while-revalidate for articles - fast load, eventual freshness",
      "Cache images aggressively with expiration",
      "Consider offline reading list feature",
    ],
  },
  "app-like": {
    description: "SPAs, dashboards, tools - app shell is stable, data is dynamic",
    defaultStrategies: {
      html: "cache-first",
      css: "cache-first",
      js: "cache-first",
      images: "cache-first",
      fonts: "cache-first",
      api: "network-first",
      video: "network-only",
      audio: "network-only",
      documents: "network-first",
      "third-party": "stale-while-revalidate",
    },
    precacheRecommendation: ["index.html", "app shell", "all JS bundles", "all CSS", "fonts", "icons"],
    notes: [
      "Precache the entire app shell for instant load",
      "API calls should be network-first with offline fallback",
      "Consider IndexedDB for offline data persistence",
    ],
  },
  "data-intensive": {
    description: "Forms, CRMs, data entry - user actions must work offline",
    defaultStrategies: {
      html: "cache-first",
      css: "cache-first",
      js: "cache-first",
      images: "cache-first",
      fonts: "cache-first",
      api: "network-first",
      video: "network-only",
      audio: "network-only",
      documents: "stale-while-revalidate",
      "third-party": "network-first",
    },
    precacheRecommendation: ["app shell", "form templates", "validation logic"],
    notes: [
      "Implement Background Sync for offline form submissions",
      "Use IndexedDB to queue offline actions",
      "Show sync status indicator to users",
      "Design conflict resolution strategy",
    ],
  },
  "hybrid": {
    description: "Mix of content and functionality - balance freshness and availability",
    defaultStrategies: {
      html: "stale-while-revalidate",
      css: "stale-while-revalidate",
      js: "stale-while-revalidate",
      images: "cache-first",
      fonts: "cache-first",
      api: "network-first",
      video: "cache-first",
      audio: "cache-first",
      documents: "stale-while-revalidate",
      "third-party": "stale-while-revalidate",
    },
    precacheRecommendation: ["critical path only", "offline fallback page"],
    notes: [
      "Use route-specific strategies",
      "Identify critical vs. nice-to-have offline content",
      "Consider lazy-caching for secondary content",
    ],
  },
};

const STRATEGY_DETAILS: Record<CachingStrategy, { description: string; tradeoffs: string; workboxClass: string }> = {
  "cache-first": {
    description: "Check cache first, fall back to network",
    tradeoffs: "Fast but may serve stale content",
    workboxClass: "CacheFirst",
  },
  "network-first": {
    description: "Try network first, fall back to cache",
    tradeoffs: "Fresh but slower, requires network for best experience",
    workboxClass: "NetworkFirst",
  },
  "stale-while-revalidate": {
    description: "Return cache immediately, update in background",
    tradeoffs: "Fast AND eventually fresh, but first view may be stale",
    workboxClass: "StaleWhileRevalidate",
  },
  "network-only": {
    description: "Always fetch from network",
    tradeoffs: "Always fresh but fails offline",
    workboxClass: "NetworkOnly",
  },
  "cache-only": {
    description: "Only serve from cache",
    tradeoffs: "Fast and reliable but never updates",
    workboxClass: "CacheOnly",
  },
};

const RESOURCE_TYPE_DEFAULTS: Record<ResourceType, { cacheName: string; maxAge: number; maxEntries: number }> = {
  html: { cacheName: "pages-cache", maxAge: 60 * 60, maxEntries: 50 },
  css: { cacheName: "static-cache", maxAge: 60 * 60 * 24 * 30, maxEntries: 30 },
  js: { cacheName: "static-cache", maxAge: 60 * 60 * 24 * 30, maxEntries: 30 },
  images: { cacheName: "image-cache", maxAge: 60 * 60 * 24 * 30, maxEntries: 100 },
  fonts: { cacheName: "font-cache", maxAge: 60 * 60 * 24 * 365, maxEntries: 10 },
  api: { cacheName: "api-cache", maxAge: 60 * 5, maxEntries: 50 },
  video: { cacheName: "media-cache", maxAge: 60 * 60 * 24 * 7, maxEntries: 20 },
  audio: { cacheName: "media-cache", maxAge: 60 * 60 * 24 * 7, maxEntries: 20 },
  documents: { cacheName: "document-cache", maxAge: 60 * 60 * 24, maxEntries: 30 },
  "third-party": { cacheName: "external-cache", maxAge: 60 * 60 * 24, maxEntries: 20 },
};

// === ANALYSIS ===

function analyzeAppType(appType: AppType): void {
  const profile = APP_TYPE_PROFILES[appType];

  console.log(`\n=== Cache Strategy Recommendations ===`);
  console.log(`\nApp Type: ${appType}`);
  console.log(`Description: ${profile.description}\n`);

  console.log("Resource Strategies:");
  console.log("-".repeat(70));

  const resourceTypes: ResourceType[] = ["html", "css", "js", "images", "fonts", "api", "video", "audio", "documents", "third-party"];

  for (const resourceType of resourceTypes) {
    const strategy = profile.defaultStrategies[resourceType];
    const details = STRATEGY_DETAILS[strategy];
    const defaults = RESOURCE_TYPE_DEFAULTS[resourceType];

    console.log(`\n${resourceType.toUpperCase()}`);
    console.log(`  Strategy: ${strategy}`);
    console.log(`  ${details.description}`);
    console.log(`  Cache: ${defaults.cacheName}, max ${defaults.maxEntries} entries, ${formatAge(defaults.maxAge)}`);
  }

  console.log("\n" + "-".repeat(70));
  console.log("\nPrecache Recommendations:");
  profile.precacheRecommendation.forEach(item => console.log(`  - ${item}`));

  console.log("\nNotes:");
  profile.notes.forEach(note => console.log(`  - ${note}`));

  console.log("\n" + "-".repeat(70));
  generateWorkboxConfig(appType);
}

function analyzeResources(resources: ResourceEntry[]): void {
  console.log(`\n=== Resource-Specific Recommendations ===\n`);
  console.log(`Analyzing ${resources.length} resources...\n`);

  const recommendations: StrategyRecommendation[] = [];

  for (const resource of resources) {
    const recommendation = recommendStrategy(resource);
    recommendations.push(recommendation);
  }

  // Group by strategy
  const byStrategy = new Map<CachingStrategy, StrategyRecommendation[]>();
  for (const rec of recommendations) {
    const existing = byStrategy.get(rec.strategy) || [];
    existing.push(rec);
    byStrategy.set(rec.strategy, existing);
  }

  for (const [strategy, recs] of byStrategy) {
    const details = STRATEGY_DETAILS[strategy];
    console.log(`\n${strategy.toUpperCase()}`);
    console.log(`  ${details.description}`);
    console.log(`  Resources:`);
    for (const rec of recs) {
      console.log(`    - ${rec.resourceType}: ${rec.reasoning}`);
    }
  }
}

function recommendStrategy(resource: ResourceEntry): StrategyRecommendation {
  const defaults = RESOURCE_TYPE_DEFAULTS[resource.type];
  let strategy: CachingStrategy;
  let reasoning: string;

  // Decision logic based on change frequency and criticality
  if (resource.changeFrequency === "never" || resource.changeFrequency === "rarely") {
    strategy = "cache-first";
    reasoning = "Rarely changes, prioritize speed";
  } else if (resource.changeFrequency === "always") {
    strategy = "network-only";
    reasoning = "Always needs fresh data";
  } else if (resource.critical) {
    strategy = "stale-while-revalidate";
    reasoning = "Critical resource, balance speed and freshness";
  } else if (resource.type === "api") {
    strategy = "network-first";
    reasoning = "API data should be fresh when possible";
  } else if (resource.size === "large") {
    strategy = "cache-first";
    reasoning = "Large resource, avoid repeated downloads";
  } else {
    strategy = "stale-while-revalidate";
    reasoning = "Default balanced approach";
  }

  return {
    resourceType: resource.type,
    strategy,
    cacheName: defaults.cacheName,
    maxAge: defaults.maxAge,
    maxEntries: defaults.maxEntries,
    reasoning,
  };
}

function formatAge(seconds: number): string {
  if (seconds >= 60 * 60 * 24 * 365) {
    return `${Math.round(seconds / (60 * 60 * 24 * 365))} year(s)`;
  } else if (seconds >= 60 * 60 * 24) {
    return `${Math.round(seconds / (60 * 60 * 24))} day(s)`;
  } else if (seconds >= 60 * 60) {
    return `${Math.round(seconds / (60 * 60))} hour(s)`;
  } else if (seconds >= 60) {
    return `${Math.round(seconds / 60)} minute(s)`;
  }
  return `${seconds} seconds`;
}

function generateWorkboxConfig(appType: AppType): void {
  const profile = APP_TYPE_PROFILES[appType];

  console.log("\nWorkbox Configuration:");
  console.log("```javascript");
  console.log("// workbox-config.js or vite.config.ts runtimeCaching");
  console.log("runtimeCaching: [");

  const routes: Array<{ pattern: string; handler: string; cacheName: string; maxEntries: number; maxAge: number }> = [
    { pattern: "/*.html", handler: STRATEGY_DETAILS[profile.defaultStrategies.html].workboxClass, cacheName: "pages-cache", maxEntries: 50, maxAge: 3600 },
    { pattern: "/*.{css,js}", handler: STRATEGY_DETAILS[profile.defaultStrategies.css].workboxClass, cacheName: "static-cache", maxEntries: 60, maxAge: 2592000 },
    { pattern: "/*.{png,jpg,jpeg,svg,gif,webp}", handler: STRATEGY_DETAILS[profile.defaultStrategies.images].workboxClass, cacheName: "image-cache", maxEntries: 100, maxAge: 2592000 },
    { pattern: "/*.{woff,woff2,ttf,eot}", handler: STRATEGY_DETAILS[profile.defaultStrategies.fonts].workboxClass, cacheName: "font-cache", maxEntries: 10, maxAge: 31536000 },
    { pattern: "/api/*", handler: STRATEGY_DETAILS[profile.defaultStrategies.api].workboxClass, cacheName: "api-cache", maxEntries: 50, maxAge: 300 },
  ];

  for (const route of routes) {
    console.log(`  {`);
    console.log(`    urlPattern: new RegExp('${route.pattern.replace(/\*/g, ".*")}'),`);
    console.log(`    handler: '${route.handler}',`);
    console.log(`    options: {`);
    console.log(`      cacheName: '${route.cacheName}',`);
    console.log(`      expiration: {`);
    console.log(`        maxEntries: ${route.maxEntries},`);
    console.log(`        maxAgeSeconds: ${route.maxAge}`);
    console.log(`      }`);
    console.log(`    }`);
    console.log(`  },`);
  }

  console.log("]");
  console.log("```");
}

// === ARGUMENT PARSING ===

function parseArgs(args: string[]): { appType?: AppType; resourcesFile?: string; json?: boolean } {
  let appType: AppType | undefined;
  let resourcesFile: string | undefined;
  let json = false;

  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const nextArg = args[i + 1];

    switch (arg) {
      case "--help":
      case "-h":
        printHelp();
        Deno.exit(0);
        break;
      case "--app-type":
      case "-t":
        appType = nextArg as AppType;
        i++;
        break;
      case "--resources":
      case "-r":
        resourcesFile = nextArg;
        i++;
        break;
      case "--json":
        json = true;
        break;
    }
  }

  return { appType, resourcesFile, json };
}

function printHelp(): void {
  console.log(`
Cache Strategy Advisor

Recommend caching strategies based on app type or resource inventory.

USAGE:
  cache-strategy-advisor.ts [OPTIONS]

OPTIONS:
  --app-type, -t <type>     App type for strategy recommendations:
                            content-heavy, app-like, data-intensive, hybrid

  --resources, -r <file>    JSON file with resource inventory

  --json                    Output as JSON (for automation)

  --help, -h                Show this help

APP TYPES:
  content-heavy      Blogs, news, docs - readable offline
  app-like           SPAs, dashboards - stable shell, dynamic data
  data-intensive     Forms, CRMs - offline actions must work
  hybrid             Mix of content and functionality

RESOURCE FILE FORMAT:
  [
    {
      "path": "/api/users",
      "type": "api",
      "changeFrequency": "often",
      "critical": true
    },
    {
      "path": "/images/*.png",
      "type": "images",
      "changeFrequency": "rarely",
      "size": "large"
    }
  ]

  Types: html, css, js, images, fonts, api, video, audio, documents, third-party
  Change Frequency: never, rarely, sometimes, often, always
  Size: small, medium, large

EXAMPLES:
  # Get recommendations for a content-heavy site
  cache-strategy-advisor.ts --app-type content-heavy

  # Analyze specific resources
  cache-strategy-advisor.ts --resources resources.json

  # Output as JSON
  cache-strategy-advisor.ts --app-type app-like --json
`);
}

// === MAIN ===

async function main(): Promise<void> {
  const { appType, resourcesFile, json } = parseArgs(Deno.args);

  if (!appType && !resourcesFile) {
    console.log("Specify --app-type or --resources. Use --help for options.");
    Deno.exit(1);
  }

  if (resourcesFile) {
    try {
      const content = await Deno.readTextFile(resourcesFile);
      const resources: ResourceEntry[] = JSON.parse(content);

      if (json) {
        const recommendations = resources.map(r => recommendStrategy(r));
        console.log(JSON.stringify(recommendations, null, 2));
      } else {
        analyzeResources(resources);
      }
    } catch (error) {
      console.error(`Error reading resources file: ${error}`);
      Deno.exit(1);
    }
  } else if (appType) {
    if (!APP_TYPE_PROFILES[appType]) {
      console.error(`Unknown app type: ${appType}`);
      console.error("Valid types: content-heavy, app-like, data-intensive, hybrid");
      Deno.exit(1);
    }

    if (json) {
      const profile = APP_TYPE_PROFILES[appType];
      console.log(JSON.stringify({ appType, profile }, null, 2));
    } else {
      analyzeAppType(appType);
    }
  }
}

main();