@portel/photon 1.11.0 → 1.13.0

package/dist/auto-ui/beam.js

@@ -8,11 +8,28 @@
 import * as http from 'http';
 import * as net from 'net';
 import * as fs from 'fs/promises';
-import { existsSync, lstatSync, mkdirSync, realpathSync, watch } from 'fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, watch, } from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { setSecurityHeaders, SimpleRateLimiter } from '../shared/security.js';
+/**
+ * Check if shell integration has been installed (photon init cli).
+ * Cached at module load since it won't change during a Beam session.
+ */
+const _shellIntegrationInstalled = (() => {
+    const shell = process.env.SHELL || '';
+    const rcFile = shell.includes('zsh')
+        ? path.join(os.homedir(), '.zshrc')
+        : path.join(os.homedir(), '.bashrc');
+    try {
+        return readFileSync(rcFile, 'utf-8').includes('# photon shell integration');
+    }
+    catch {
+        return false;
+    }
+})();
 /**
  * Generate a unique ID for a photon based on its path.
  * This ensures photons with the same name from different paths are distinguishable.
@@ -21,6 +38,52 @@ import { setSecurityHeaders, SimpleRateLimiter } from '../shared/security.js';
 function generatePhotonId(photonPath) {
     return createHash('sha256').update(photonPath).digest('hex').slice(0, 12);
 }
+/**
+ * MIME type map for icon images
+ */
+const ICON_MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+};
+/**
+ * Resolve raw icon image paths to MCP Icon[] format (data URIs)
+ */
+async function resolveIconImages(iconImages, photonPath) {
+    if (!iconImages || iconImages.length === 0)
+        return undefined;
+    const photonDir = path.dirname(photonPath);
+    const icons = [];
+    for (const entry of iconImages) {
+        try {
+            const resolvedPath = path.resolve(photonDir, entry.path);
+            const ext = path.extname(resolvedPath).toLowerCase();
+            const mimeType = ICON_MIME_TYPES[ext];
+            if (!mimeType)
+                continue;
+            const data = await fs.readFile(resolvedPath);
+            const base64 = data.toString('base64');
+            const dataUri = `data:${mimeType};base64,${base64}`;
+            const icon = {
+                src: dataUri,
+                mimeType,
+            };
+            if (entry.sizes)
+                icon.sizes = entry.sizes;
+            if (entry.theme)
+                icon.theme = entry.theme;
+            icons.push(icon);
+        }
+        catch {
+            // Skip unreadable icon files silently
+        }
+    }
+    return icons.length > 0 ? icons : undefined;
+}
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 import { withTimeout } from '../async/index.js';
@@ -69,6 +132,318 @@ const backfillEnvDefaults = backfillEnvDefaultsFromModule;
 const extractClassMetadataFromSource = extractClassMetadataFromModule;
 const applyMethodVisibility = applyMethodVisibilityFromModule;
 const extractCspFromSource = extractCspFromModule;
+// ═══════════════════════════════════════════════════════════════════════════════
+// NOTIFICATION SUBSCRIPTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Map to store notification subscriptions per photon
+ * Key: photon name, Value: list of event types this photon cares about
+ * Example: { "chat": ["mentions", "direct-messages"], "tasks": ["deadline", "assigned-to-me"] }
+ */
+const photonNotificationSubscriptions = new Map();
+/**
+ * Generate the service worker JS that validates the Beam backend
+ * on PWA launch and shows a diagnostic page if something is wrong.
+ */
+function generateServiceWorker(workingDir) {
+    return `
+// Photon Beam Service Worker
+// Validates the backend is running and healthy before serving the app.
+const CACHE_NAME = 'photon-pwa-v1';
+const EXPECTED_WORKING_DIR = ${JSON.stringify(workingDir)};
+const HEALTH_ENDPOINT = '/api/diagnostics';
+
+// Cache the boot page on install
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.put('/_pwa_boot', new Response(BOOT_PAGE, {
+      headers: { 'Content-Type': 'text/html' }
+    }))).then(() => self.skipWaiting())
+  );
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+
+  // PWA icon PNG generation — intercept /api/pwa/icon-png requests and render
+  // the SVG icon onto OffscreenCanvas, returning a real PNG response that
+  // satisfies Chrome's installability requirement for raster icons.
+  if (url.pathname === '/api/pwa/icon-png') {
+    event.respondWith(handleIconPng(url));
+    return;
+  }
+
+  // Only intercept navigation requests (page loads, not API/asset fetches)
+  if (event.request.mode !== 'navigate') return;
+
+  // Skip API routes and static assets — let them pass through
+  if (url.pathname.startsWith('/api/') || url.pathname === '/sw.js' || url.pathname === '/beam.bundle.js') return;
+
+  // All navigation requests go through health check
+  event.respondWith(handlePWANavigation(event.request));
+});
+
+async function handlePWANavigation(request) {
+  try {
+    // Try to reach the backend
+    const healthRes = await fetch(HEALTH_ENDPOINT, { signal: AbortSignal.timeout(3000) });
+    if (!healthRes.ok) throw new Error('Health check failed');
+
+    const health = await healthRes.json();
+
+    // Validate this is actually Beam serving the expected directory
+    if (!health.photonVersion) {
+      return serveBoot('wrong-service', JSON.stringify(health));
+    }
+    if (health.workingDir !== EXPECTED_WORKING_DIR) {
+      return serveBoot('wrong-directory', JSON.stringify({
+        expected: EXPECTED_WORKING_DIR,
+        actual: health.workingDir
+      }));
+    }
+
+    // Backend is healthy and correct — serve the real page
+    return fetch(request);
+  } catch (err) {
+    // Backend is unreachable
+    return serveBoot('not-running', err.message);
+  }
+}
+
+async function handleIconPng(url) {
+  const photon = url.searchParams.get('photon') || '';
+  const size = parseInt(url.searchParams.get('size') || '192', 10);
+  const cacheKey = '/_pwa_icon_' + photon + '_' + size;
+
+  // Check cache first
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(cacheKey);
+  if (cached) return cached;
+
+  try {
+    // Fetch the icon from the server (may be SVG, PNG, JPEG, etc.)
+    const iconRes = await fetch('/api/pwa/icon?photon=' + encodeURIComponent(photon), { signal: AbortSignal.timeout(10000) });
+    if (!iconRes.ok) throw new Error('Icon fetch failed: ' + iconRes.status);
+
+    const contentType = (iconRes.headers.get('Content-Type') || '').toLowerCase();
+
+    // For raster images (PNG, JPEG, WebP), resize via OffscreenCanvas if needed
+    // For SVG or emoji-generated SVG, render to canvas at target size
+    let bmp;
+    if (contentType.includes('svg')) {
+      // SVG (emoji-generated or file) — parse as text, create bitmap
+      const svgText = await iconRes.text();
+      const svgBlob = new Blob([svgText], { type: 'image/svg+xml' });
+      bmp = await createImageBitmap(svgBlob, { resizeWidth: size, resizeHeight: size });
+    } else {
+      // Raster image (PNG, JPEG, WebP) — decode directly
+      const imgBlob = await iconRes.blob();
+      bmp = await createImageBitmap(imgBlob, { resizeWidth: size, resizeHeight: size });
+    }
+
+    const canvas = new OffscreenCanvas(size, size);
+    const ctx = canvas.getContext('2d');
+
+    // Dark rounded-rect background
+    ctx.fillStyle = '#1a1a1a';
+    const r = size * 0.2;
+    ctx.beginPath();
+    ctx.moveTo(r, 0);
+    ctx.lineTo(size - r, 0);
+    ctx.quadraticCurveTo(size, 0, size, r);
+    ctx.lineTo(size, size - r);
+    ctx.quadraticCurveTo(size, size, size - r, size);
+    ctx.lineTo(r, size);
+    ctx.quadraticCurveTo(0, size, 0, size - r);
+    ctx.lineTo(0, r);
+    ctx.quadraticCurveTo(0, 0, r, 0);
+    ctx.closePath();
+    ctx.fill();
+
+    // Draw the icon
+    ctx.drawImage(bmp, 0, 0, size, size);
+
+    const pngBlob = await canvas.convertToBlob({ type: 'image/png' });
+    const pngResponse = new Response(pngBlob, {
+      headers: {
+        'Content-Type': 'image/png',
+        'Cache-Control': 'public, max-age=86400'
+      }
+    });
+
+    // Cache the generated PNG
+    await cache.put(cacheKey, pngResponse.clone());
+    return pngResponse;
+  } catch (err) {
+    // Fallback: generate a simple colored square with initial letter
+    const canvas = new OffscreenCanvas(size, size);
+    const ctx = canvas.getContext('2d');
+    ctx.fillStyle = '#1a1a1a';
+    ctx.fillRect(0, 0, size, size);
+    ctx.fillStyle = '#4ade80';
+    ctx.font = (size * 0.4) + 'px sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(photon.charAt(0).toUpperCase() || 'P', size / 2, size / 2);
+    const pngBlob = await canvas.convertToBlob({ type: 'image/png' });
+    return new Response(pngBlob, {
+      headers: { 'Content-Type': 'image/png' }
+    });
+  }
+}
+
+async function serveBoot(reason, detail) {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match('/_pwa_boot');
+  if (cached) {
+    const html = await cached.text();
+    const injected = html
+      .replace('__BOOT_REASON__', reason)
+      .replace('__BOOT_DETAIL__', detail || '')
+      .replace('__EXPECTED_DIR__', EXPECTED_WORKING_DIR);
+    return new Response(injected, { headers: { 'Content-Type': 'text/html' } });
+  }
+  return new Response('Photon Beam is not available. Run: photon beam', {
+    status: 503, headers: { 'Content-Type': 'text/plain' }
+  });
+}
+
+const BOOT_PAGE = \`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Photon Beam</title>
+  <meta name="theme-color" content="#1a1a1a">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      min-height: 100vh; display: flex; align-items: center; justify-content: center;
+      background: #1a1a1a; color: #e5e5e5; font-family: system-ui, -apple-system, sans-serif;
+    }
+    .container { text-align: center; padding: 40px; max-width: 500px; }
+    .icon { font-size: 56px; margin-bottom: 24px; }
+    h1 { font-size: 22px; font-weight: 600; margin-bottom: 12px; color: #fff; }
+    .message { font-size: 15px; line-height: 1.6; color: #999; margin-bottom: 28px; }
+    .command {
+      display: inline-block; background: #2a2a2a; border: 1px solid #333;
+      padding: 10px 20px; border-radius: 8px; font-family: 'JetBrains Mono', monospace;
+      font-size: 14px; color: #4ade80; margin-bottom: 20px; user-select: all;
+    }
+    .detail {
+      font-size: 12px; color: #666; font-family: 'JetBrains Mono', monospace;
+      background: #222; border-radius: 6px; padding: 10px; margin-bottom: 20px;
+      word-break: break-all; display: none;
+    }
+    .detail.show { display: block; }
+    .retry {
+      padding: 10px 24px; background: #333; border: 1px solid #444; border-radius: 8px;
+      color: #fff; cursor: pointer; font-size: 14px; transition: background 0.2s;
+    }
+    .retry:hover { background: #444; }
+    .spinner {
+      display: none; width: 20px; height: 20px; border: 2px solid #444;
+      border-top-color: #4ade80; border-radius: 50%; animation: spin 0.8s linear infinite;
+      margin: 0 auto 16px;
+    }
+    .spinner.show { display: block; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="spinner" id="spinner"></div>
+    <div id="content">
+      <div class="icon" id="icon"></div>
+      <h1 id="title"></h1>
+      <p class="message" id="message"></p>
+      <div class="detail" id="detail"></div>
+      <code class="command" id="command" style="display:none"></code>
+      <br><br>
+      <button class="retry" onclick="checkAndRetry()">Retry</button>
+    </div>
+  </div>
+  <script>
+    const reason = '__BOOT_REASON__';
+    const detail = '__BOOT_DETAIL__';
+    const expectedDir = '__EXPECTED_DIR__';
+
+    const states = {
+      'not-running': {
+        icon: '\\u26a1',
+        title: 'Beam is not running',
+        message: 'Start Photon Beam to use this app:',
+        command: 'photon beam'
+      },
+      'wrong-service': {
+        icon: '\\u26a0\\ufe0f',
+        title: 'Port is in use by another service',
+        message: 'Something else is running on this port. Stop the other service or reconfigure Beam:',
+        command: 'photon beam --port <available-port>',
+        showDetail: true
+      },
+      'wrong-directory': {
+        icon: '\\ud83d\\udcc1',
+        title: 'Beam is serving a different project',
+        message: 'Beam is running but pointing to a different directory. Start it with the correct path:',
+        command: 'photon beam ' + expectedDir,
+        showDetail: true
+      }
+    };
+
+    function render() {
+      const s = states[reason] || states['not-running'];
+      document.getElementById('icon').textContent = s.icon;
+      document.getElementById('title').textContent = s.title;
+      document.getElementById('message').textContent = s.message;
+      const cmdEl = document.getElementById('command');
+      cmdEl.textContent = s.command;
+      cmdEl.style.display = 'inline-block';
+      if (s.showDetail && detail) {
+        const el = document.getElementById('detail');
+        el.textContent = detail;
+        el.classList.add('show');
+      }
+    }
+
+    async function checkAndRetry() {
+      document.getElementById('content').style.display = 'none';
+      document.getElementById('spinner').classList.add('show');
+      try {
+        const res = await fetch('/api/diagnostics', { signal: AbortSignal.timeout(3000) });
+        if (res.ok) {
+          const h = await res.json();
+          if (h.photonVersion && h.workingDir === expectedDir) {
+            location.reload();
+            return;
+          }
+        }
+      } catch {}
+      document.getElementById('spinner').classList.remove('show');
+      document.getElementById('content').style.display = '';
+      render();
+    }
+
+    render();
+    // Auto-retry every 5 seconds
+    setInterval(async () => {
+      try {
+        const res = await fetch('/api/diagnostics', { signal: AbortSignal.timeout(2000) });
+        if (res.ok) {
+          const h = await res.json();
+          if (h.photonVersion && h.workingDir === expectedDir) location.reload();
+        }
+      } catch {}
+    }, 5000);
+  </script>
+</body>
+</html>\`;
+`;
+}
 export async function startBeam(rawWorkingDir, port) {
     const workingDir = path.resolve(rawWorkingDir);
     const { PHOTON_VERSION } = await import('../version.js');
@@ -229,8 +604,18 @@ export async function startBeam(rawWorkingDir, port) {
             backfillEnvDefaults(instance, constructorParams);
             // Extract schema for UI — reuse source read from above
             const schemaSource = source || (await fs.readFile(photonPath, 'utf-8'));
-            const { tools: schemas, templates } = extractor.extractAllFromSource(schemaSource);
+            const metadata = extractor.extractAllFromSource(schemaSource);
+            const schemas = metadata.tools;
+            const templates = metadata.templates;
             mcp.schemas = schemas;
+            // Store notification subscriptions per photon
+            if (metadata.notificationSubscriptions?.watchFor) {
+                photonNotificationSubscriptions.set(name, metadata.notificationSubscriptions.watchFor);
+            }
+            else {
+                // Clear previous subscription if photon no longer has @notify-on
+                photonNotificationSubscriptions.delete(name);
+            }
             // Get UI assets for linking
             const uiAssets = mcp.assets?.ui || [];
             // Filter out lifecycle methods
@@ -256,8 +641,30 @@ export async function startBeam(rawWorkingDir, port) {
                         ? { scheduled: schema.scheduled || schema.cron }
                         : {}),
                     ...(schema.locked ? { locked: schema.locked } : {}),
+                    // MCP standard annotations
+                    ...(schema.title ? { title: schema.title } : {}),
+                    ...(schema.readOnlyHint ? { readOnlyHint: true } : {}),
+                    ...(schema.destructiveHint ? { destructiveHint: true } : {}),
+                    ...(schema.idempotentHint ? { idempotentHint: true } : {}),
+                    ...(schema.openWorldHint !== undefined ? { openWorldHint: schema.openWorldHint } : {}),
+                    ...(schema.audience ? { audience: schema.audience } : {}),
+                    ...(schema.contentPriority !== undefined
+                        ? { contentPriority: schema.contentPriority }
+                        : {}),
+                    ...(schema.outputSchema ? { outputSchema: schema.outputSchema } : {}),
                 };
             });
+            // Resolve icon images (file paths → data URIs) for methods that have them
+            for (const schema of schemas) {
+                if (!schema.iconImages)
+                    continue;
+                const method = methods.find((m) => m.name === schema.name);
+                if (!method)
+                    continue;
+                const resolved = await resolveIconImages(schema.iconImages, photonPath);
+                if (resolved)
+                    method.icons = resolved;
+            }
             // Add templates as methods with isTemplate flag and markdown output format
             templates.forEach((template) => {
                 if (!lifecycleMethods.includes(template.name)) {
@@ -536,12 +943,25 @@ export async function startBeam(rawWorkingDir, port) {
                 if (await handleConfigRoutes(req, res, url, beamState))
                     return;
             }
+            // Service worker for PWA support
+            if (url.pathname === '/sw.js') {
+                res.writeHead(200, {
+                    'Content-Type': 'application/javascript',
+                    'Service-Worker-Allowed': '/',
+                    'Cache-Control': 'no-cache',
+                });
+                res.end(generateServiceWorker(beamState.workingDir));
+                return;
+            }
             // Serve static frontend bundle
             if (url.pathname === '/beam.bundle.js') {
                 try {
                     const bundlePath = path.join(__dirname, '../../dist/beam.bundle.js');
                     const content = await fs.readFile(bundlePath, 'utf-8');
-                    res.writeHead(200, { 'Content-Type': 'text/javascript' });
+                    res.writeHead(200, {
+                        'Content-Type': 'text/javascript',
+                        'Cache-Control': 'no-cache',
+                    });
                     res.end(content);
                 }
                 catch {
@@ -550,11 +970,458 @@ export async function startBeam(rawWorkingDir, port) {
                 }
                 return;
             }
+            // Standalone PWA app route: /app/{photonName}
+            // Full-featured PWA host shell with diagnostics, postMessage bridge, service worker, and install prompt
+            const appMatch = url.pathname.match(/^\/app\/([^/]+)$/);
+            if (appMatch) {
+                const photonName = appMatch[1];
+                const photon = beamState.photons.find((p) => p.name === photonName);
+                if (!photon) {
+                    res.writeHead(404);
+                    res.end(`Photon not found: ${photonName}`);
+                    return;
+                }
+                const label = photon?.label ||
+                    photonName.charAt(0).toUpperCase() + photonName.slice(1).replace(/-/g, ' ');
+                const description = photon?.description || `${label} - Photon App`;
+                const iconValue = photon?.icon || '📦';
+                const encodedName = encodeURIComponent(photonName);
+                // Sanitize strings for safe embedding in HTML
+                const safeLabel = label.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] || c);
+                const safeDesc = description.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] || c);
+                const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+  <title>${safeLabel}</title>
+  <meta name="description" content="${safeDesc}">
+  <meta name="theme-color" content="#1a1a1a">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <meta name="apple-mobile-web-app-title" content="${safeLabel}">
+  <link rel="manifest" href="/api/pwa/manifest.json?photon=${encodedName}">
+  <link rel="apple-touch-icon" href="/api/pwa/icon?photon=${encodedName}">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; overflow: hidden; background: #1a1a1a; font-family: system-ui, -apple-system, sans-serif; color: #e5e5e5; }
+    #app { width: 100%; height: 100vh; }
+    iframe { width: 100%; height: 100vh; border: none; display: block; }
+
+    .status-page {
+      display: none; width: 100%; height: 100vh;
+      flex-direction: column; align-items: center; justify-content: center;
+      text-align: center; padding: 40px;
+    }
+    .status-page.show { display: flex; }
+    .status-page .icon { font-size: 64px; margin-bottom: 24px; }
+    .status-page h2 { font-size: 20px; font-weight: 600; margin-bottom: 12px; color: #e5e5e5; }
+    .status-page p { font-size: 14px; color: #888; max-width: 400px; line-height: 1.6; margin-bottom: 8px; }
+    .status-page code {
+      display: inline-block; background: #2a2a2a; padding: 8px 16px; border-radius: 6px;
+      font-size: 13px; color: #4ade80; font-family: 'SF Mono', Monaco, monospace; margin-top: 8px;
+    }
+    .status-page .spinner {
+      width: 24px; height: 24px; border: 2px solid #333; border-top-color: #4ade80;
+      border-radius: 50%; animation: spin 0.8s linear infinite; margin-bottom: 16px;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .status-page .retry-btn {
+      margin-top: 16px; padding: 8px 20px; background: #333; border: 1px solid #444;
+      border-radius: 6px; color: #e5e5e5; cursor: pointer; font-size: 13px; font-family: inherit;
+    }
+    .status-page .retry-btn:hover { background: #444; }
+
+  </style>
+</head>
+<body>
+  <!-- Status: Starting (shown while waiting for Beam) -->
+  <div id="status-starting" class="status-page">
+    <div class="spinner"></div>
+    <h2>Starting ${safeLabel}...</h2>
+    <p>Waiting for Beam server</p>
+  </div>
+
+  <!-- Status: Not running (shown when Beam is down) -->
+  <div id="status-offline" class="status-page">
+    <div class="icon">${iconValue}</div>
+    <h2>${safeLabel}</h2>
+    <p>Server is not running. Start Photon to use this app:</p>
+    <code>photon beam</code>
+    <button class="retry-btn" onclick="checkAndLoad()">Retry</button>
+  </div>
+
+  <!-- Status: Port conflict -->
+  <div id="status-conflict" class="status-page">
+    <div class="icon">⚠️</div>
+    <h2>Port Conflict</h2>
+    <p id="conflict-msg">Another process is using the required port.</p>
+    <code id="conflict-cmd"></code>
+    <button class="retry-btn" onclick="checkAndLoad()">Retry</button>
+  </div>
+
+  <!-- App container with iframe -->
+  <div id="app" style="display:none"></div>
+
+  <script>
+    const PHOTON = ${JSON.stringify(photonName)};
+    const appEl = document.getElementById('app');
+    const statusStarting = document.getElementById('status-starting');
+    const statusOffline = document.getElementById('status-offline');
+    const statusConflict = document.getElementById('status-conflict');
+    let retryTimer = null;
+
+    function hideAll() {
+      statusStarting.classList.remove('show');
+      statusOffline.classList.remove('show');
+      statusConflict.classList.remove('show');
+      appEl.style.display = 'none';
+    }
+
+    // Diagnostics-first loading: check server health before loading the app
+    async function checkAndLoad() {
+      if (retryTimer) { clearInterval(retryTimer); retryTimer = null; }
+      hideAll();
+      statusStarting.classList.add('show');
+
+      try {
+        const res = await fetch('/api/diagnostics', { signal: AbortSignal.timeout(5000) });
+        if (!res.ok) throw new Error('Server error');
+        const diag = await res.json();
+
+        // Check for port conflicts
+        if (diag.portConflict) {
+          hideAll();
+          statusConflict.classList.add('show');
+          const conflictMsg = document.getElementById('conflict-msg');
+          const conflictCmd = document.getElementById('conflict-cmd');
+          if (diag.portConflict.port) {
+            conflictMsg.textContent = 'Port ' + diag.portConflict.port + ' is in use by another process.';
+          }
+          if (diag.portConflict.pid) {
+            conflictCmd.textContent = 'kill ' + diag.portConflict.pid;
+          }
+          return;
+        }
+
+        // Server is healthy — establish MCP session then load the app
+        hideAll();
+        appEl.style.display = 'block';
+        await connectSSE();
+        await loadApp();
+      } catch (err) {
+        // Server unreachable — show offline state with auto-retry
+        hideAll();
+        statusOffline.classList.add('show');
+        retryTimer = setInterval(async () => {
+          try {
+            const res = await fetch('/api/diagnostics', { signal: AbortSignal.timeout(3000) });
+            if (res.ok) {
+              clearInterval(retryTimer);
+              retryTimer = null;
+              checkAndLoad();
+            }
+          } catch { /* still offline */ }
+        }, 3000);
+      }
+    }
+
+    // Load the @ui template into a full-viewport iframe with platform bridge.
+    // Discovers template URL client-side: tries class-level @ui first (/api/template),
+    // then falls back to method-level @ui by querying diagnostics for the app entry's linkedUi.
+    async function loadApp() {
+      try {
+        // Step 1: Discover the template URL
+        let templateUrl = '/api/template?photon=' + encodeURIComponent(PHOTON);
+        let bridgeMethod = 'main';
+
+        // Try class-level @ui first
+        let templateRes = await fetch(templateUrl, { signal: AbortSignal.timeout(10000) });
+        if (!templateRes.ok) {
+          // Fall back: query diagnostics for this photon's appEntry linkedUi
+          const diagRes = await fetch('/api/diagnostics', { signal: AbortSignal.timeout(10000) });
+          if (diagRes.ok) {
+            const diag = await diagRes.json();
+            const photonInfo = (diag.photons || []).find(function(p) { return p.name === PHOTON; });
+            if (photonInfo && photonInfo.appEntry && photonInfo.appEntry.linkedUi) {
+              templateUrl = '/api/ui?photon=' + encodeURIComponent(PHOTON) + '&id=' + encodeURIComponent(photonInfo.appEntry.linkedUi);
+              bridgeMethod = photonInfo.appEntry.name || 'main';
+              templateRes = await fetch(templateUrl, { signal: AbortSignal.timeout(10000) });
+            }
+          }
+          if (!templateRes.ok) throw new Error('Template not available');
+        }
+
+        // Step 2: Fetch platform bridge script
+        const bridgeRes = await fetch('/api/platform-bridge?photon=' + encodeURIComponent(PHOTON) + '&method=' + encodeURIComponent(bridgeMethod) + '&theme=dark', { signal: AbortSignal.timeout(10000) });
+
+        let templateHtml = await templateRes.text();
+        const bridgeScript = bridgeRes.ok ? await bridgeRes.text() : '';
+
+        // Inject platform bridge before </head>
+        if (templateHtml.includes('</head>')) {
+          templateHtml = templateHtml.replace('</head>', bridgeScript + '</head>');
+        } else {
+          templateHtml = '<html><head>' + bridgeScript + '</head><body>' + templateHtml + '</body></html>';
+        }
+
+        const iframe = document.createElement('iframe');
+        iframe.setAttribute('sandbox', 'allow-scripts allow-forms allow-same-origin allow-popups allow-modals');
+
+        const blob = new Blob([templateHtml], { type: 'text/html' });
+        iframe.src = URL.createObjectURL(blob);
+
+        appEl.innerHTML = '';
+        appEl.appendChild(iframe);
+        initBridge(iframe, bridgeMethod);
+      } catch (err) {
+        appEl.innerHTML = '<div class="status-page show"><div class="icon">⚠️</div>'
+          + '<h2>Failed to load</h2><p>' + err.message + '</p>'
+          + '<button class="retry-btn" onclick="checkAndLoad()">Retry</button></div>';
+      }
+    }
+
+    // postMessage bridge: relays JSON-RPC from iframe through MCP for full event pipeline
+    var mcpSessionId = null;
+    var mcpCallId = 100;
+
+    function initBridge(iframe, bridgeMethod) {
+      window.addEventListener('message', async (e) => {
+        const msg = e.data;
+        if (!msg || typeof msg !== 'object') return;
+
+        // Handle MCP Apps ui/initialize request — respond so bridge sends initialized
+        if (msg.jsonrpc === '2.0' && msg.method === 'ui/initialize' && msg.id != null) {
+          iframe.contentWindow.postMessage({
+            jsonrpc: '2.0',
+            id: msg.id,
+            result: {
+              protocolVersion: '2026-01-26',
+              hostInfo: { name: 'photon-pwa', version: '1.0.0' },
+              hostCapabilities: {},
+              hostContext: { theme: 'dark' },
+            },
+          }, '*');
+          return;
+        }
+
+        // Handle JSON-RPC tools/call from iframe — route through MCP for event broadcasting
+        if (msg.jsonrpc === '2.0' && msg.method === 'tools/call' && msg.id != null) {
+          const { name: toolName, arguments: toolArgs } = msg.params || {};
+          // Prefix with photon name if not already prefixed (bridge sends bare method names)
+          var fullToolName = toolName.includes('/') ? toolName : PHOTON + '/' + toolName;
+          try {
+            var headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
+            if (mcpSessionId) headers['Mcp-Session-Id'] = mcpSessionId;
+            var mcpRes = await fetch('/mcp', {
+              method: 'POST',
+              headers: headers,
+              body: JSON.stringify({
+                jsonrpc: '2.0', id: mcpCallId++,
+                method: 'tools/call',
+                params: { name: fullToolName, arguments: toolArgs || {} },
+              }),
+              signal: AbortSignal.timeout(60000),
+            });
+            var mcpData = await mcpRes.json();
+            // Extract result from MCP response (content array → structured or text)
+            var result = undefined;
+            var error = undefined;
+            if (mcpData.error) {
+              error = { code: mcpData.error.code || -32000, message: mcpData.error.message || 'Unknown error' };
+            } else if (mcpData.result) {
+              var content = mcpData.result.content || [];
+              var textParts = content.filter(function(c) { return c.type === 'text'; });
+              if (textParts.length > 0) {
+                try { result = JSON.parse(textParts[0].text); } catch(e) { result = textParts[0].text; }
+              }
+              if (mcpData.result.structuredContent) result = mcpData.result.structuredContent;
+            }
+            iframe.contentWindow.postMessage({
+              jsonrpc: '2.0', id: msg.id, result: result, error: error,
+            }, '*');
+          } catch (err) {
+            iframe.contentWindow.postMessage({
+              jsonrpc: '2.0', id: msg.id,
+              error: { code: -32000, message: err.message },
+            }, '*');
+          }
+        }
+      });
+
+      // Send photon:init context to iframe once loaded
+      iframe.onload = () => {
+        iframe.contentWindow.postMessage({
+          type: 'photon:init',
+          context: { photon: PHOTON, theme: 'dark', displayMode: 'standalone' }
+        }, '*');
+      };
+
+      // Wait for bridge ready signal, then auto-invoke main() and deliver result
+      var bridgeReady = false;
+      window.addEventListener('message', async function onReady(e) {
+        if (bridgeReady) return;
+        var msg = e.data;
+        if (!msg || typeof msg !== 'object') return;
+        // Bridge sends both legacy photon:ready and MCP Apps ui/notifications/initialized
+        var isReady = msg.type === 'photon:ready' ||
+          (msg.jsonrpc === '2.0' && msg.method === 'ui/notifications/initialized');
+        if (!isReady) return;
+        bridgeReady = true;
+        window.removeEventListener('message', onReady);
+
+        try {
+          var headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
+          if (mcpSessionId) headers['Mcp-Session-Id'] = mcpSessionId;
+          var invokeRes = await fetch('/mcp', {
+            method: 'POST',
+            headers: headers,
+            body: JSON.stringify({
+              jsonrpc: '2.0', id: mcpCallId++,
+              method: 'tools/call',
+              params: { name: PHOTON + '/' + bridgeMethod, arguments: {} },
+            }),
+            signal: AbortSignal.timeout(30000),
+          });
+          var mcpData = await invokeRes.json();
+          if (!mcpData.error && mcpData.result) {
+            var content = mcpData.result.content || [];
+            var textParts = content.filter(function(c) { return c.type === 'text'; });
+            var result = undefined;
+            if (textParts.length > 0) {
+              try { result = JSON.parse(textParts[0].text); } catch(e) { result = textParts[0].text; }
+            }
+            if (mcpData.result.structuredContent) result = mcpData.result.structuredContent;
+            if (result !== undefined) {
+              iframe.contentWindow.postMessage({
+                jsonrpc: '2.0',
+                method: 'ui/notifications/tool-result',
+                params: { result: result },
+              }, '*');
+            }
+          }
+        } catch (err) {
+          console.warn('[PWA] Auto-invoke failed:', err.message);
+        }
+      });
+    }
+
+    // --- Service Worker Registration ---
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.register('/sw.js', { scope: '/' })
+        .then(reg => console.log('[PWA] SW registered:', reg.scope))
+        .catch(err => console.warn('[PWA] SW registration failed:', err));
+    }
+
+    // --- Real-time SSE subscription for cross-client sync ---
+    async function connectSSE() {
+      try {
+        // Step 1: Initialize MCP session as beam client to get session ID
+        var initRes = await fetch('/mcp', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+          signal: AbortSignal.timeout(10000),
+          body: JSON.stringify({
+            jsonrpc: '2.0', id: 1, method: 'initialize',
+            params: {
+              protocolVersion: '2025-03-26',
+              clientInfo: { name: 'beam', version: '1.0.0' },
+              capabilities: {}
+            }
+          })
+        });
+        var sessionId = initRes.headers.get('mcp-session-id');
+        if (!sessionId) return;
+        mcpSessionId = sessionId;
+
+        // Step 2: Open SSE on the same session
+        var sseUrl = '/mcp?sessionId=' + encodeURIComponent(sessionId);
+        var es = new EventSource(sseUrl);
+        es.onmessage = function(event) {
+          try {
+            var msg = JSON.parse(event.data);
+            if (msg.type === 'keepalive') return;
+            var iframe = document.querySelector('iframe');
+            if (!iframe || !iframe.contentWindow) return;
+
+            // Handle @stateful state-changed events — re-invoke main() to refresh UI
+            if (msg.method === 'state-changed' && msg.params?.photon === PHOTON) {
+              // Re-fetch data by calling main() and delivering result to iframe
+              var refreshHeaders = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
+              if (mcpSessionId) refreshHeaders['Mcp-Session-Id'] = mcpSessionId;
+              fetch('/mcp', {
+                method: 'POST',
+                headers: refreshHeaders,
+                body: JSON.stringify({
+                  jsonrpc: '2.0', id: mcpCallId++,
+                  method: 'tools/call',
+                  params: { name: PHOTON + '/' + bridgeMethod, arguments: {} },
+                }),
+                signal: AbortSignal.timeout(15000),
+              }).then(function(r) { return r.json(); }).then(function(mcpData) {
+                if (!mcpData.error && mcpData.result) {
+                  var content = mcpData.result.content || [];
+                  var textParts = content.filter(function(c) { return c.type === 'text'; });
+                  var result = undefined;
+                  if (textParts.length > 0) {
+                    try { result = JSON.parse(textParts[0].text); } catch(e) { result = textParts[0].text; }
+                  }
+                  if (mcpData.result.structuredContent) result = mcpData.result.structuredContent;
+                  if (result !== undefined) {
+                    iframe.contentWindow.postMessage({
+                      jsonrpc: '2.0',
+                      method: 'ui/notifications/tool-result',
+                      params: { result: result },
+                    }, '*');
+                  }
+                }
+              }).catch(function() {});
+              return;
+            }
+
+            // Forward other events to iframe
+            if (msg.method === 'photon/board-update') {
+              iframe.contentWindow.postMessage({
+                jsonrpc: '2.0',
+                method: 'photon/notifications/emit',
+                params: { emit: 'board-update', ...msg.params },
+              }, '*');
+            } else if (msg.method === 'photon/channel-event') {
+              iframe.contentWindow.postMessage({
+                jsonrpc: '2.0',
+                method: 'photon/notifications/emit',
+                params: msg.params,
+              }, '*');
+            }
+          } catch (e) {}
+        };
+        es.onerror = function() {
+          es.close();
+          setTimeout(connectSSE, 5000);
+        };
+      } catch (e) {
+        setTimeout(connectSSE, 5000);
+      }
+    }
+
+    // Start the diagnostics-first loading flow
+    checkAndLoad();
+  </script>
+</body>
+</html>`;
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(html);
+                return;
+            }
             // Default route: Serve Lit App
             if (url.pathname === '/' || !url.pathname.startsWith('/api')) {
                 try {
                     const indexPath = path.join(__dirname, 'frontend/index.html');
-                    const content = await fs.readFile(indexPath, 'utf-8');
+                    let content = await fs.readFile(indexPath, 'utf-8');
+                    // Inject shell integration flag so frontend can strip CLI prefix
+                    if (_shellIntegrationInstalled) {
+                        content = content.replace('</head>', '<script>window.__PHOTON_SHELL_INIT=true</script></head>');
+                    }
                     res.writeHead(200, { 'Content-Type': 'text/html' });
                     res.end(content);
                 }
@@ -644,20 +1511,13 @@ export async function startBeam(rawWorkingDir, port) {
     // Determine which photon a file change belongs to
     const getPhotonForPath = (changedPath) => {
         const relativePath = path.relative(workingDir, changedPath);
-        const parts = relativePath.split(path.sep);
-        // Direct .photon.ts file change
-        if (relativePath.endsWith('.photon.ts')) {
+        // Only react to top-level .photon.ts file changes.
+        // Subfolders under workingDir (~/.photon/) are runtime data (auth, media, state),
+        // NOT source assets. Asset folders live at the symlink target and are watched
+        // separately by setupSymlinkWatcher.
+        if (relativePath.endsWith('.photon.ts') && !relativePath.includes(path.sep)) {
             return path.basename(relativePath, '.photon.ts');
         }
-        // Asset folder change - first segment is the photon name
-        if (parts.length > 1) {
-            const folderName = parts[0];
-            // Check if corresponding .photon.ts exists
-            const photon = photons.find((p) => p.name === folderName);
-            if (photon) {
-                return folderName;
-            }
-        }
         return null;
     };
     // Handle file change with debounce
@@ -802,8 +1662,17 @@ export async function startBeam(rawWorkingDir, port) {
                         // Re-extract schema - use extractAllFromSource to get both tools and templates
                         const extractor = new SchemaExtractor();
                         const reloadSource = await fs.readFile(photonPath, 'utf-8');
-                        const { tools: schemas, templates } = extractor.extractAllFromSource(reloadSource);
+                        const reloadMetadata = extractor.extractAllFromSource(reloadSource);
+                        const schemas = reloadMetadata.tools;
+                        const templates = reloadMetadata.templates;
                         mcp.schemas = schemas; // Store schemas for result rendering
+                        // Update notification subscriptions for reloaded photon
+                        if (reloadMetadata.notificationSubscriptions?.watchFor) {
+                            photonNotificationSubscriptions.set(photonName, reloadMetadata.notificationSubscriptions.watchFor);
+                        }
+                        else {
+                            photonNotificationSubscriptions.delete(photonName);
+                        }
                         const lifecycleMethods = ['onInitialize', 'onShutdown', 'constructor'];
                         const uiAssets = mcp.assets?.ui || [];
                         const methods = schemas
@@ -821,8 +1690,32 @@ export async function startBeam(rawWorkingDir, port) {
                                 buttonLabel: schema.buttonLabel,
                                 icon: schema.icon,
                                 linkedUi: linkedAsset?.id,
+                                // MCP standard annotations
+                                ...(schema.title ? { title: schema.title } : {}),
+                                ...(schema.readOnlyHint ? { readOnlyHint: true } : {}),
+                                ...(schema.destructiveHint ? { destructiveHint: true } : {}),
+                                ...(schema.idempotentHint ? { idempotentHint: true } : {}),
+                                ...(schema.openWorldHint !== undefined
+                                    ? { openWorldHint: schema.openWorldHint }
+                                    : {}),
+                                ...(schema.audience ? { audience: schema.audience } : {}),
+                                ...(schema.contentPriority !== undefined
+                                    ? { contentPriority: schema.contentPriority }
+                                    : {}),
+                                ...(schema.outputSchema ? { outputSchema: schema.outputSchema } : {}),
                             };
                         });
+                        // Resolve icon images for hot-reloaded methods
+                        for (const schema of schemas) {
+                            if (!schema.iconImages)
+                                continue;
+                            const method = methods.find((m) => m.name === schema.name);
+                            if (!method)
+                                continue;
+                            const resolved = await resolveIconImages(schema.iconImages, photonPath);
+                            if (resolved)
+                                method.icons = resolved;
+                        }
                         // Add templates as methods
                         templates.forEach((template) => {
                             if (!lifecycleMethods.includes(template.name)) {
@@ -1141,36 +2034,103 @@ export async function startBeam(rawWorkingDir, port) {
             await ensureDaemon();
             for (const photon of statefulPhotons) {
                 const photonName = photon.name;
-                const channel = `${photonName}:state-changed`;
-                subscribeChannel(photonName, channel, (message) => {
-                    broadcastToBeam('photon/state-changed', {
+                // Subscribe to 'default' instance + any other instances that appear
+                const instanceNames = ['default'];
+                for (const instanceName of instanceNames) {
+                    // Channel is now instance-specific: photon:instance:state-changed
+                    const channel = `${photonName}:${instanceName}:state-changed`;
+                    subscribeChannel(photonName, channel, (message) => {
+                        // Only broadcast if instance matches (prevents cross-instance leakage)
+                        if (message?.instance === instanceName || !message?.instance) {
+                            // Minimal transmission: include instance and patches for global sync
+                            broadcastNotification('state-changed', {
+                                photon: photonName,
+                                instance: instanceName,
+                                // JSON Patch array for client-side state sync
+                                patches: message?.patches,
+                                // Keep legacy fields for backward compatibility
+                                method: message?.method,
+                                params: message?.params,
+                                data: message?.data,
+                                // Optional fields for undo/redo support
+                                ...(message?.patch && { patch: message.patch }),
+                                ...(message?.inversePatch && { inversePatch: message.inversePatch }),
+                            });
+                        }
+                    }, {
+                        reconnect: true,
+                        workingDir,
+                        onReconnect: () => logger.debug(`📡 Reconnected ${channel} subscription`),
+                        onRefreshNeeded: () => {
+                            logger.info(`📡 Refresh needed for ${channel} (events lost during daemon restart)`);
+                            // Broadcast minimal refresh signal to all clients
+                            broadcastNotification('state-changed', {
+                                photon: photonName,
+                                instance: instanceName,
+                                method: '_refresh',
+                                patches: undefined, // No patches, signal full refresh needed
+                            });
+                        },
+                    })
+                        .then(() => {
+                        logger.info(`📡 Subscribed to ${channel} for cross-client sync`);
+                    })
+                        .catch((err) => {
+                        logger.warn(`Failed to subscribe to ${channel}: ${getErrorMessage(err)}`);
+                    });
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to start daemon for stateful photons: ${getErrorMessage(err)}`);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // NOTIFICATION SUBSCRIPTIONS - Subscribe to all photon notification channels
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // Unlike state-changed (active photon only), notifications are always subscribed
+    // but filtered server-side based on each photon's @notify-on declarations
+    if (statefulPhotons.length > 0) {
+        try {
+            for (const photon of statefulPhotons) {
+                const photonName = photon.name;
+                const instanceName = 'default'; // TODO: support multi-instance notifications
+                // Subscribe to notifications channel (always-on, not just active)
+                const notificationChannel = `${photonName}:${instanceName}:notifications`;
+                // Get this photon's notification subscriptions from @notify-on tags
+                const watchFor = photonNotificationSubscriptions.get(photonName);
+                subscribeChannel(photonName, notificationChannel, (message) => {
+                    // Check if this photon cares about this notification type
+                    if (!watchFor || !watchFor.includes(message?.type)) {
+                        logger.debug(`📡 Notification filtered: ${photonName} doesn't care about "${message?.type}"`);
+                        return; // Don't broadcast notifications this photon doesn't care about
+                    }
+                    // Only broadcast relevant notifications
+                    logger.debug(`📡 Broadcasting notification: ${photonName} [${message?.type}]`);
+                    broadcastNotification('photon/notification', {
                         photon: photonName,
-                        method: message?.method,
-                        data: message?.data,
+                        type: message?.type,
+                        priority: message?.priority || 'info',
+                        message: message?.message,
+                        ...(message?.action && { action: message.action }),
+                        ...(message?.sound && { sound: message.sound }),
+                        ...(message?.data && { data: message.data }),
                     });
                 }, {
                     reconnect: true,
                     workingDir,
-                    onReconnect: () => logger.debug(`📡 Reconnected ${channel} subscription`),
-                    onRefreshNeeded: () => {
-                        logger.info(`📡 Refresh needed for ${channel} (events lost during daemon restart)`);
-                        broadcastToBeam('photon/state-changed', {
-                            photon: photonName,
-                            method: '_refresh',
-                            data: {},
-                        });
-                    },
+                    onReconnect: () => logger.debug(`📡 Reconnected ${notificationChannel} subscription`),
                 })
                     .then(() => {
-                    logger.info(`📡 Subscribed to ${channel} for cross-client sync`);
+                    logger.info(`📡 Subscribed to ${notificationChannel} for notifications${watchFor ? ` (watching: ${watchFor.join(', ')})` : ''}`);
                 })
                     .catch((err) => {
-                    logger.warn(`Failed to subscribe to ${channel}: ${getErrorMessage(err)}`);
+                    logger.warn(`Failed to subscribe to ${notificationChannel}: ${getErrorMessage(err)}`);
                 });
             }
         }
         catch (err) {
-            logger.warn(`Failed to start daemon for stateful photons: ${getErrorMessage(err)}`);
+            logger.warn(`Failed to set up notification subscriptions: ${getErrorMessage(err)}`);
         }
     }
     // Set up file watchers for symlinked and bundled photon assets (now that photons are loaded)