@fairfox/polly 0.1.5 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",
@@ -44,7 +44,7 @@
       "types": "./dist/shared/types/messages.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": ["dist", "templates", "README.md", "LICENSE"],
   "scripts": {
     "dev": "bun run build.ts --watch",
     "build": "bun run build.ts",

package/templates/pwa/.gitignore.template

@@ -0,0 +1,4 @@
+node_modules
+dist
+.DS_Store
+*.log

package/templates/pwa/README.md.template

@@ -0,0 +1,144 @@
+# {{PROJECT_NAME}}
+
+A Progressive Web App (PWA) built with Polly framework, demonstrating multi-context architecture with:
+
+- **Main Context** - UI application
+- **Service Worker** - Background tasks, caching, push notifications
+- **Shared Worker** - Shared state across tabs/windows
+
+## Architecture
+
+```
+┌─────────────────┐
+│  Main Context   │  ← User Interface
+│   (main.ts)     │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+┌─────────┐ ┌──────────────┐
+│ Service │ │    Shared    │
+│ Worker  │ │    Worker    │
+│         │ │              │
+│ Caching │ │ Shared State │
+│ Offline │ │ Multi-tab    │
+└─────────┘ └──────────────┘
+```
+
+## Getting Started
+
+1. **Install dependencies:**
+   ```bash
+   bun install
+   ```
+
+2. **Start development server:**
+   ```bash
+   bun run serve
+   ```
+
+3. **Open in browser:**
+   ```
+   http://localhost:3000
+   ```
+
+4. **Try the features:**
+   - Click "Ping Service Worker" - tests communication with SW
+   - Click "Ping Shared Worker" - tests communication with shared worker
+   - Click "Broadcast" - sends message to all workers
+   - Open multiple tabs to see shared worker coordination
+
+## Development
+
+- `bun run serve` - Start development server with hot reload
+- `bun run build` - Build for production
+- `bun run typecheck` - Type check TypeScript
+- `bun run visualize` - Generate architecture diagrams
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── src/
+│   ├── main.ts            # Main application context
+│   ├── service-worker.ts  # Service Worker (caching, offline)
+│   └── shared-worker.ts   # Shared Worker (cross-tab state)
+├── public/
+│   └── manifest.json      # PWA manifest
+├── index.html             # Entry point
+├── server.ts              # Dev server
+├── build.ts               # Build script
+├── package.json
+└── tsconfig.json
+```
+
+## Features Demonstrated
+
+### Service Worker
+- Asset caching for offline support
+- Background fetch and sync
+- Push notifications (requires HTTPS)
+- Message passing with main context
+
+### Shared Worker
+- State shared across multiple tabs
+- Broadcast messages to all connected tabs
+- Connection tracking
+- Periodic heartbeat
+
+### Main Context
+- Service Worker registration
+- Shared Worker connection
+- Bidirectional communication
+- UI updates from worker messages
+
+## Visualization
+
+Generate architecture diagrams:
+
+```bash
+bun run visualize
+```
+
+This will create:
+- System context diagram
+- Container diagram showing all 3 contexts
+- Message flow diagrams
+
+View diagrams:
+```bash
+bun run visualize --serve
+```
+
+## Testing
+
+Open multiple browser tabs to test:
+1. Shared worker coordination across tabs
+2. Service worker message broadcasting
+3. State synchronization
+
+## Production Build
+
+```bash
+bun run build
+```
+
+Output in `dist/` directory. Serve with any static file server or deploy to:
+- Netlify
+- Vercel
+- GitHub Pages
+- Cloudflare Pages
+
+## Notes
+
+- Service Worker requires HTTPS in production (or localhost for dev)
+- Shared Worker support varies by browser (Chrome, Firefox, Edge)
+- Check browser DevTools → Application tab to debug workers
+
+## Learn More
+
+- [Polly Documentation](https://github.com/fairfox/polly)
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+- [Shared Worker API](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker)
+- [PWA Documentation](https://web.dev/progressive-web-apps/)

package/templates/pwa/build.ts.template

@@ -0,0 +1,56 @@
+/**
+ * Build script for PWA
+ * Uses Bun's built-in bundler
+ */
+
+import { rmSync, cpSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const distDir = './dist'
+
+// Clean dist directory
+console.log('🧹 Cleaning dist directory...')
+rmSync(distDir, { recursive: true, force: true })
+mkdirSync(distDir, { recursive: true })
+
+// Copy static files
+console.log('📋 Copying static files...')
+cpSync('./public', distDir, { recursive: true, force: true })
+cpSync('./index.html', join(distDir, 'index.html'))
+
+// Build main application
+console.log('📦 Building main application...')
+await Bun.build({
+  entrypoints: ['./src/main.ts'],
+  outdir: join(distDir, 'src'),
+  format: 'esm',
+  minify: true,
+  sourcemap: 'external',
+  target: 'browser',
+})
+
+// Build service worker
+console.log('⚙️  Building service worker...')
+await Bun.build({
+  entrypoints: ['./src/service-worker.ts'],
+  outdir: join(distDir, 'src'),
+  format: 'esm',
+  minify: true,
+  sourcemap: 'external',
+  target: 'browser',
+})
+
+// Build shared worker
+console.log('👥 Building shared worker...')
+await Bun.build({
+  entrypoints: ['./src/shared-worker.ts'],
+  outdir: join(distDir, 'src'),
+  format: 'esm',
+  minify: true,
+  sourcemap: 'external',
+  target: 'browser',
+})
+
+console.log('✅ Build complete!')
+console.log(`\n📦 Output: ${distDir}/`)
+console.log('\n💡 To serve: bun run serve')

package/templates/pwa/index.html.template

@@ -0,0 +1,127 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="{{PROJECT_NAME}} - A PWA with Polly" />
+    <link rel="manifest" href="/manifest.json" />
+    <title>{{PROJECT_NAME}}</title>
+    <style>
+      * {
+        box-sizing: border-box;
+        margin: 0;
+        padding: 0;
+      }
+
+      body {
+        font-family: system-ui, -apple-system, sans-serif;
+        padding: 20px;
+        max-width: 800px;
+        margin: 0 auto;
+      }
+
+      h1 {
+        margin-bottom: 20px;
+        color: #333;
+      }
+
+      .status {
+        margin-bottom: 20px;
+        padding: 15px;
+        background: #f5f5f5;
+        border-radius: 8px;
+      }
+
+      .status-item {
+        display: flex;
+        justify-content: space-between;
+        margin-bottom: 8px;
+      }
+
+      .status-label {
+        font-weight: 600;
+      }
+
+      .status-value {
+        color: #666;
+      }
+
+      .actions {
+        display: flex;
+        gap: 10px;
+        margin-bottom: 20px;
+      }
+
+      button {
+        padding: 10px 20px;
+        background: #007bff;
+        color: white;
+        border: none;
+        border-radius: 5px;
+        cursor: pointer;
+        font-size: 14px;
+      }
+
+      button:hover {
+        background: #0056b3;
+      }
+
+      button:disabled {
+        background: #ccc;
+        cursor: not-allowed;
+      }
+
+      #messages {
+        border: 1px solid #ddd;
+        border-radius: 8px;
+        padding: 15px;
+        min-height: 200px;
+        background: white;
+      }
+
+      .message {
+        padding: 8px;
+        margin-bottom: 8px;
+        background: #f9f9f9;
+        border-left: 3px solid #007bff;
+        border-radius: 4px;
+        font-size: 14px;
+      }
+
+      .message-time {
+        color: #666;
+        font-size: 12px;
+        margin-right: 8px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>{{PROJECT_NAME}}</h1>
+
+    <div class="status">
+      <div class="status-item">
+        <span class="status-label">Service Worker:</span>
+        <span id="sw-status" class="status-value">Checking...</span>
+      </div>
+      <div class="status-item">
+        <span class="status-label">Shared Worker:</span>
+        <span id="shared-worker-status" class="status-value">Checking...</span>
+      </div>
+      <div class="status-item">
+        <span class="status-label">Messages Received:</span>
+        <span id="message-count" class="status-value">0</span>
+      </div>
+    </div>
+
+    <div class="actions">
+      <button id="ping-sw">Ping Service Worker</button>
+      <button id="ping-shared">Ping Shared Worker</button>
+      <button id="broadcast">Broadcast Message</button>
+    </div>
+
+    <h2>Messages</h2>
+    <div id="messages"></div>
+
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/pwa/package.json.template

@@ -0,0 +1,19 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --hot src/main.ts",
+    "build": "bun build.ts",
+    "serve": "bun --hot server.ts",
+    "typecheck": "bun tsc --noEmit",
+    "visualize": "bun ../../visualize/src/cli.ts"
+  },
+  "dependencies": {
+    "@fairfox/polly": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/bun": "latest"
+  }
+}

package/templates/pwa/public/manifest.json.template

@@ -0,0 +1,21 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "short_name": "{{PROJECT_NAME}}",
+  "description": "A PWA built with Polly framework",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#000000",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ]
+}

package/templates/pwa/server.ts.template

@@ -0,0 +1,58 @@
+/**
+ * Development server for PWA
+ * Serves the application with hot reload support
+ */
+
+const port = 3000
+
+const server = Bun.serve({
+  port,
+  async fetch(req) {
+    const url = new URL(req.url)
+    let filePath = url.pathname
+
+    // Serve root
+    if (filePath === '/') {
+      filePath = '/index.html'
+    }
+
+    // Try to serve from public directory first
+    const publicFile = Bun.file(`./public${filePath}`)
+    if (await publicFile.exists()) {
+      return new Response(publicFile)
+    }
+
+    // Try to serve from root
+    const rootFile = Bun.file(`.${filePath}`)
+    if (await rootFile.exists()) {
+      return new Response(rootFile)
+    }
+
+    // Handle TypeScript files - transpile on the fly
+    if (filePath.endsWith('.ts')) {
+      const tsFile = Bun.file(`.${filePath}`)
+      if (await tsFile.exists()) {
+        const transpiled = await Bun.build({
+          entrypoints: [`.${filePath}`],
+          format: 'esm',
+          target: 'browser',
+        })
+
+        if (transpiled.outputs.length > 0) {
+          return new Response(transpiled.outputs[0], {
+            headers: {
+              'Content-Type': 'application/javascript',
+            },
+          })
+        }
+      }
+    }
+
+    // 404
+    return new Response('Not Found', { status: 404 })
+  },
+})
+
+console.log(`🚀 Server running at http://localhost:${port}`)
+console.log(`\n📱 PWA: {{PROJECT_NAME}}`)
+console.log(`\n💡 Open in browser and check the console for worker messages`)

package/templates/pwa/src/main.ts.template

@@ -0,0 +1,133 @@
+/**
+ * Main Application Context
+ * Coordinates between Service Worker and Shared Worker
+ */
+
+// Register Service Worker
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', async () => {
+    try {
+      const registration = await navigator.serviceWorker.register('/src/service-worker.ts', {
+        type: 'module'
+      })
+      console.log('Service Worker registered:', registration.scope)
+      updateStatus('sw-status', '✓ Active')
+    } catch (error) {
+      console.error('Service Worker registration failed:', error)
+      updateStatus('sw-status', '✗ Failed')
+    }
+  })
+
+  // Listen for messages from Service Worker
+  navigator.serviceWorker.addEventListener('message', (event) => {
+    console.log('Message from Service Worker:', event.data)
+    addMessage(`[SW] ${JSON.stringify(event.data)}`)
+  })
+}
+
+// Initialize Shared Worker
+let sharedWorker: SharedWorker | null = null
+let messageCount = 0
+
+if (typeof SharedWorker !== 'undefined') {
+  sharedWorker = new SharedWorker(
+    new URL('./shared-worker.ts', import.meta.url),
+    { type: 'module', name: 'polly-shared-worker' }
+  )
+
+  sharedWorker.port.start()
+
+  // Listen for messages from Shared Worker
+  sharedWorker.port.addEventListener('message', (event) => {
+    console.log('Message from Shared Worker:', event.data)
+    addMessage(`[Shared] ${JSON.stringify(event.data)}`)
+    messageCount++
+    updateMessageCount()
+  })
+
+  updateStatus('shared-worker-status', '✓ Connected')
+} else {
+  updateStatus('shared-worker-status', '✗ Not Supported')
+}
+
+// UI Event Handlers
+document.getElementById('ping-sw')?.addEventListener('click', async () => {
+  if (navigator.serviceWorker.controller) {
+    navigator.serviceWorker.controller.postMessage({
+      type: 'PING',
+      timestamp: Date.now()
+    })
+    addMessage('[Main] Sent PING to Service Worker')
+  } else {
+    addMessage('[Main] Service Worker not active')
+  }
+})
+
+document.getElementById('ping-shared')?.addEventListener('click', () => {
+  if (sharedWorker) {
+    sharedWorker.port.postMessage({
+      type: 'PING',
+      timestamp: Date.now()
+    })
+    addMessage('[Main] Sent PING to Shared Worker')
+  } else {
+    addMessage('[Main] Shared Worker not available')
+  }
+})
+
+document.getElementById('broadcast')?.addEventListener('click', () => {
+  const message = {
+    type: 'BROADCAST',
+    data: 'Hello from main context',
+    timestamp: Date.now()
+  }
+
+  // Send to both workers
+  if (navigator.serviceWorker.controller) {
+    navigator.serviceWorker.controller.postMessage(message)
+  }
+
+  if (sharedWorker) {
+    sharedWorker.port.postMessage(message)
+  }
+
+  addMessage('[Main] Broadcast sent to all workers')
+})
+
+// UI Helper Functions
+function updateStatus(elementId: string, status: string) {
+  const element = document.getElementById(elementId)
+  if (element) {
+    element.textContent = status
+  }
+}
+
+function updateMessageCount() {
+  const element = document.getElementById('message-count')
+  if (element) {
+    element.textContent = messageCount.toString()
+  }
+}
+
+function addMessage(text: string) {
+  const messagesDiv = document.getElementById('messages')
+  if (!messagesDiv) return
+
+  const messageDiv = document.createElement('div')
+  messageDiv.className = 'message'
+
+  const time = new Date().toLocaleTimeString()
+  messageDiv.innerHTML = `<span class="message-time">${time}</span>${text}`
+
+  messagesDiv.insertBefore(messageDiv, messagesDiv.firstChild)
+
+  // Keep only last 20 messages
+  while (messagesDiv.children.length > 20) {
+    messagesDiv.removeChild(messagesDiv.lastChild!)
+  }
+}
+
+// Initial message
+addMessage('[Main] Application initialized')
+
+console.log('{{PROJECT_NAME}} initialized')