@shepai/cli 1.53.2 → 1.55.0

package/dist/src/presentation/web/hooks/use-agent-events.js

@@ -1,53 +1,143 @@
 'use client';
 import { useCallback, useEffect, useRef, useState } from 'react';
-const BASE_BACKOFF_MS = 1000;
-const MAX_BACKOFF_MS = 30_000;
-/** Only reset backoff after connection is stable for this long */
-const STABLE_CONNECTION_MS = 5_000;
+const SW_PATH = '/agent-events-sw.js';
+/**
+ * Hook that receives real-time agent notification events via a Service Worker.
+ *
+ * The SW maintains a single SSE connection to /api/agent-events and
+ * broadcasts events to all open tabs. Falls back to direct EventSource
+ * when Service Workers are unavailable.
+ */
 export function useAgentEvents(options) {
     const [events, setEvents] = useState([]);
     const [lastEvent, setLastEvent] = useState(null);
     const [connectionStatus, setConnectionStatus] = useState('disconnected');
-    const backoffRef = useRef(BASE_BACKOFF_MS);
-    const reconnectTimerRef = useRef(null);
-    const stableTimerRef = useRef(null);
-    const esRef = useRef(null);
     const runId = options?.runId;
-    const connect = useCallback(() => {
-        if (typeof window === 'undefined' || typeof EventSource === 'undefined') {
+    const swRef = useRef(null);
+    const onMessage = useCallback((event) => {
+        const msg = event.data;
+        if (!msg || typeof msg !== 'object')
             return;
+        if (msg.type === 'notification') {
+            const parsed = msg.data;
+            setEvents((prev) => [...prev, parsed]);
+            setLastEvent(parsed);
         }
-        // Prevent duplicate connections
-        if (esRef.current) {
+        else if (msg.type === 'status') {
+            setConnectionStatus(msg.status);
+        }
+    }, []);
+    useEffect(() => {
+        if (typeof window === 'undefined')
             return;
+        // ?sse=direct bypasses the Service Worker for debugging
+        const bypassSW = typeof location !== 'undefined' && new URLSearchParams(location.search).has('sse');
+        // Fallback: direct EventSource when SW not supported or bypassed
+        if (!navigator.serviceWorker || bypassSW) {
+            return connectDirectEventSource(runId, setEvents, setLastEvent, setConnectionStatus);
         }
+        let cancelled = false;
+        const fallbackCleanupRef = { current: undefined };
+        function subscribeToWorker(worker) {
+            if (cancelled)
+                return;
+            swRef.current = worker;
+            worker.postMessage({ type: 'subscribe', runId });
+            setConnectionStatus('connecting');
+        }
+        // Listen for messages from whatever SW controls this page
+        navigator.serviceWorker.addEventListener('message', onMessage);
+        // Re-subscribe when SW controller changes (e.g., after SW update via skipWaiting)
+        function handleControllerChange() {
+            if (cancelled)
+                return;
+            const newController = navigator.serviceWorker.controller;
+            if (newController) {
+                swRef.current = newController;
+                newController.postMessage({ type: 'subscribe', runId });
+                setConnectionStatus('connecting');
+            }
+        }
+        navigator.serviceWorker.addEventListener('controllerchange', handleControllerChange);
+        navigator.serviceWorker
+            .register(SW_PATH, { scope: '/' })
+            .then((registration) => {
+            if (cancelled)
+                return;
+            // Use the active worker, or wait for it to activate
+            const sw = registration.active ?? registration.installing ?? registration.waiting;
+            if (!sw) {
+                // No worker at all — fall back to direct EventSource
+                fallbackCleanupRef.current = connectDirectEventSource(runId, setEvents, setLastEvent, setConnectionStatus);
+                return;
+            }
+            if (sw.state === 'activated') {
+                subscribeToWorker(sw);
+            }
+            else {
+                sw.addEventListener('statechange', () => {
+                    if (sw.state === 'activated')
+                        subscribeToWorker(sw);
+                });
+            }
+        })
+            .catch(() => {
+            // SW registration failed — fall back to direct EventSource
+            if (!cancelled) {
+                fallbackCleanupRef.current = connectDirectEventSource(runId, setEvents, setLastEvent, setConnectionStatus);
+            }
+        });
+        return () => {
+            cancelled = true;
+            navigator.serviceWorker.removeEventListener('message', onMessage);
+            navigator.serviceWorker.removeEventListener('controllerchange', handleControllerChange);
+            swRef.current?.postMessage({ type: 'unsubscribe' });
+            swRef.current = null;
+            fallbackCleanupRef.current?.();
+        };
+    }, [runId, onMessage]);
+    return { events, lastEvent, connectionStatus };
+}
+// --- EventSource fallback (identical to the previous implementation) ---
+const BASE_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+const STABLE_CONNECTION_MS = 5_000;
+function connectDirectEventSource(runId, setEvents, setLastEvent, setConnectionStatus) {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    if (typeof EventSource === 'undefined')
+        return () => { };
+    let es = null;
+    let stopped = false;
+    let backoff = BASE_BACKOFF_MS;
+    let reconnectTimer = null;
+    let stableTimer = null;
+    function connect() {
+        if (stopped)
+            return;
         const url = runId
             ? `/api/agent-events?runId=${encodeURIComponent(runId)}`
             : '/api/agent-events';
-        const es = new EventSource(url);
-        esRef.current = es;
+        es = new EventSource(url);
         setConnectionStatus('connecting');
         es.onopen = () => {
             setConnectionStatus('connected');
-            // Only reset backoff after connection stays open for a while
-            stableTimerRef.current = setTimeout(() => {
-                stableTimerRef.current = null;
-                backoffRef.current = BASE_BACKOFF_MS;
+            stableTimer = setTimeout(() => {
+                stableTimer = null;
+                backoff = BASE_BACKOFF_MS;
             }, STABLE_CONNECTION_MS);
         };
         es.onerror = () => {
-            es.close();
-            esRef.current = null;
+            es?.close();
+            es = null;
             setConnectionStatus('disconnected');
-            // Cancel stable timer — connection wasn't stable
-            if (stableTimerRef.current !== null) {
-                clearTimeout(stableTimerRef.current);
-                stableTimerRef.current = null;
+            if (stableTimer !== null) {
+                clearTimeout(stableTimer);
+                stableTimer = null;
             }
-            const delay = backoffRef.current;
-            backoffRef.current = Math.min(delay * 2, MAX_BACKOFF_MS);
-            reconnectTimerRef.current = setTimeout(() => {
-                reconnectTimerRef.current = null;
+            const delay = backoff;
+            backoff = Math.min(delay * 2, MAX_BACKOFF_MS);
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
                 connect();
             }, delay);
         };
@@ -56,23 +146,21 @@ export function useAgentEvents(options) {
             setEvents((prev) => [...prev, parsed]);
             setLastEvent(parsed);
         }));
-    }, [runId]);
-    useEffect(() => {
-        connect();
-        return () => {
-            if (reconnectTimerRef.current !== null) {
-                clearTimeout(reconnectTimerRef.current);
-                reconnectTimerRef.current = null;
-            }
-            if (stableTimerRef.current !== null) {
-                clearTimeout(stableTimerRef.current);
-                stableTimerRef.current = null;
-            }
-            if (esRef.current) {
-                esRef.current.close();
-                esRef.current = null;
-            }
-        };
-    }, [connect]);
-    return { events, lastEvent, connectionStatus };
+    }
+    connect();
+    return () => {
+        stopped = true;
+        if (reconnectTimer !== null) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        if (stableTimer !== null) {
+            clearTimeout(stableTimer);
+            stableTimer = null;
+        }
+        if (es) {
+            es.close();
+            es = null;
+        }
+    };
 }

package/dist/src/presentation/web/hooks/use-notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-notifications.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,sBAAsB;IACrC,wBAAwB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AAqBD,wBAAgB,gBAAgB,IAAI,sBAAsB,CAmCzD"}
+{"version":3,"file":"use-notifications.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,sBAAsB;IACrC,wBAAwB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AA4CD,wBAAgB,gBAAgB,IAAI,sBAAsB,CAgEzD"}

package/dist/src/presentation/web/hooks/use-notifications.js

@@ -1,8 +1,9 @@
 'use client';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { toast } from 'sonner';
-import { NotificationSeverity } from '../../../../packages/core/src/domain/generated/output.js';
+import { NotificationEventType, NotificationSeverity } from '../../../../packages/core/src/domain/generated/output.js';
 import { useAgentEventsContext } from './agent-events-provider.js';
+import { useSound } from './use-sound.js';
 const SEVERITY_TO_TOAST = {
     [NotificationSeverity.Success]: 'success',
     [NotificationSeverity.Error]: 'error',
@@ -11,34 +12,73 @@ const SEVERITY_TO_TOAST = {
 };
 function dispatchToast(event) {
     const method = SEVERITY_TO_TOAST[event.severity] ?? 'info';
-    toast[method](event.featureName, { description: event.message });
+    const isActionable = event.eventType === NotificationEventType.WaitingApproval;
+    toast[method](event.featureName, {
+        description: event.message,
+        ...(isActionable && {
+            action: {
+                label: 'Review',
+                onClick: () => {
+                    window.dispatchEvent(new CustomEvent('shep:select-feature', { detail: { featureId: event.featureId } }));
+                },
+            },
+        }),
+    });
 }
 function dispatchBrowserNotification(event) {
     if (globalThis.Notification?.permission !== 'granted') {
         return;
     }
-    new Notification(event.featureName, { body: event.message });
+    new Notification(`Shep: ${event.featureName}`, {
+        body: event.message,
+        icon: '/favicon-light.svg',
+    });
 }
+const SEVERITY_TO_SOUND = {
+    [NotificationSeverity.Success]: 'celebration',
+    [NotificationSeverity.Error]: 'caution',
+    [NotificationSeverity.Warning]: 'notification',
+    [NotificationSeverity.Info]: 'button',
+};
 export function useNotifications() {
-    const { lastEvent } = useAgentEventsContext();
+    const { events } = useAgentEventsContext();
+    const successSound = useSound('celebration', { volume: 0.5 });
+    const errorSound = useSound('caution', { volume: 0.5 });
+    const warningSound = useSound('notification', { volume: 0.5 });
+    const infoSound = useSound('button', { volume: 0.5 });
+    const soundsByName = useMemo(() => ({
+        celebration: successSound,
+        caution: errorSound,
+        notification: warningSound,
+        button: infoSound,
+    }), [successSound, errorSound, warningSound, infoSound]);
     const [browserPermissionState, setBrowserPermissionState] = useState(() => {
         if (typeof globalThis.Notification === 'undefined')
             return 'default';
         return globalThis.Notification.permission;
     });
-    // Track which events we've already dispatched to avoid re-dispatching on re-render
-    const processedRef = useRef(new Set());
+    // Track how many events from the array we've already processed.
+    // Using the array index (instead of lastEvent) prevents React batching
+    // from silently dropping events when multiple SSE messages arrive together.
+    const processedCountRef = useRef(0);
     useEffect(() => {
-        if (!lastEvent)
-            return;
-        // Create a key for deduplication
-        const key = `${lastEvent.agentRunId}-${lastEvent.eventType}-${lastEvent.timestamp}`;
-        if (processedRef.current.has(key))
+        if (events.length <= processedCountRef.current)
             return;
-        processedRef.current.add(key);
-        dispatchToast(lastEvent);
-        dispatchBrowserNotification(lastEvent);
-    }, [lastEvent]);
+        const newEvents = events.slice(processedCountRef.current);
+        processedCountRef.current = events.length;
+        for (const event of newEvents) {
+            // Only notify for actionable events and completion celebrations
+            if (event.severity !== NotificationSeverity.Error &&
+                event.severity !== NotificationSeverity.Warning &&
+                event.severity !== NotificationSeverity.Success) {
+                continue;
+            }
+            dispatchToast(event);
+            dispatchBrowserNotification(event);
+            const soundName = SEVERITY_TO_SOUND[event.severity];
+            soundsByName[soundName]?.play();
+        }
+    }, [events, soundsByName]);
     const requestBrowserPermission = useCallback(async () => {
         if (typeof globalThis.Notification === 'undefined')
             return;

package/dist/src/presentation/web/hooks/use-notifications.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-notifications.stories.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAwIvD,QAAA,MAAM,IAAI,EAAE,IAcX,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}
+{"version":3,"file":"use-notifications.stories.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAqKvD,QAAA,MAAM,IAAI,EAAE,IAcX,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}

package/dist/src/presentation/web/hooks/use-notifications.stories.js

@@ -1,16 +1,35 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import { toast } from 'sonner';
 import { Toaster } from '../components/ui/sonner.js';
 import { Button } from '../components/ui/button.js';
-function simulateNotification(event) {
-    const method = event.severity ?? 'info';
-    toast[method](event.featureName, { description: event.message });
-    if (globalThis.Notification?.permission === 'granted') {
-        new Notification(event.featureName, { body: event.message });
-    }
-}
+import { useSound } from './use-sound.js';
+const SEVERITY_SOUNDS = {
+    success: 'celebration',
+    error: 'caution',
+    warning: 'notification',
+    info: 'button',
+};
 function NotificationDemo() {
+    const successSound = useSound('celebration', { volume: 0.5 });
+    const errorSound = useSound('caution', { volume: 0.5 });
+    const warningSound = useSound('notification', { volume: 0.5 });
+    const infoSound = useSound('button', { volume: 0.5 });
+    const soundsByName = useMemo(() => ({
+        celebration: successSound,
+        caution: errorSound,
+        notification: warningSound,
+        button: infoSound,
+    }), [successSound, errorSound, warningSound, infoSound]);
+    const simulateNotification = useCallback((event) => {
+        const method = event.severity ?? 'info';
+        toast[method](event.featureName, { description: event.message });
+        if (globalThis.Notification?.permission === 'granted') {
+            new Notification(event.featureName, { body: event.message });
+        }
+        const soundName = SEVERITY_SOUNDS[event.severity];
+        soundsByName[soundName]?.play();
+    }, [soundsByName]);
     const [browserPermission, setBrowserPermission] = useState(typeof globalThis.Notification !== 'undefined' ? globalThis.Notification.permission : 'default');
     const requestPermission = async () => {
         if (typeof globalThis.Notification === 'undefined')
@@ -18,7 +37,7 @@ function NotificationDemo() {
         const result = await globalThis.Notification.requestPermission();
         setBrowserPermission(result);
     };
-    return (_jsxs("div", { className: "flex w-[420px] flex-col gap-6", children: [_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-sm font-semibold", children: "Browser Notification Permission" }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsxs("span", { className: "text-muted-foreground text-sm", children: ["Status: ", _jsx("code", { className: "bg-muted rounded px-1.5 py-0.5", children: browserPermission })] }), _jsx(Button, { size: "sm", variant: "outline", onClick: requestPermission, children: "Request Permission" })] })] }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-sm font-semibold", children: "Simulate Notification Events" }), _jsx("p", { className: "text-muted-foreground text-xs", children: "Click a button to fire a toast and browser notification." }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(Button, { size: "sm", variant: "outline", onClick: () => simulateNotification({
+    return (_jsxs("div", { className: "flex w-[420px] flex-col gap-6", children: [_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-sm font-semibold", children: "Browser Notification Permission" }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsxs("span", { className: "text-muted-foreground text-sm", children: ["Status: ", _jsx("code", { className: "bg-muted rounded px-1.5 py-0.5", children: browserPermission })] }), _jsx(Button, { size: "sm", variant: "outline", onClick: requestPermission, children: "Request Permission" })] })] }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-sm font-semibold", children: "Simulate Notification Events" }), _jsx("p", { className: "text-muted-foreground text-xs", children: "Click a button to fire a toast, browser notification, and sound." }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(Button, { size: "sm", variant: "outline", onClick: () => simulateNotification({
                                     eventType: 'agent_started',
                                     severity: 'info',
                                     featureName: 'Auth Module',

package/dist/src/presentation/web/hooks/use-sound-enabled.d.ts

@@ -0,0 +1,6 @@
+export interface UseSoundEnabledResult {
+    enabled: boolean;
+    toggle: () => void;
+}
+export declare function useSoundEnabled(): UseSoundEnabledResult;
+//# sourceMappingURL=use-sound-enabled.d.ts.map

package/dist/src/presentation/web/hooks/use-sound-enabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sound-enabled.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-sound-enabled.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wBAAgB,eAAe,IAAI,qBAAqB,CAyBvD"}

package/dist/src/presentation/web/hooks/use-sound-enabled.js

@@ -0,0 +1,27 @@
+'use client';
+import { useCallback, useEffect, useState } from 'react';
+const STORAGE_KEY = 'shep-sound-enabled';
+const SYNC_EVENT = 'shep:sound-toggle';
+export function useSoundEnabled() {
+    const [enabled, setEnabled] = useState(true);
+    useEffect(() => {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (stored === 'false')
+            setEnabled(false);
+        // Sync across all useSoundEnabled instances in the same tab
+        const onSync = (e) => {
+            setEnabled(e.detail);
+        };
+        window.addEventListener(SYNC_EVENT, onSync);
+        return () => window.removeEventListener(SYNC_EVENT, onSync);
+    }, []);
+    const toggle = useCallback(() => {
+        setEnabled((prev) => {
+            const next = !prev;
+            localStorage.setItem(STORAGE_KEY, String(next));
+            window.dispatchEvent(new CustomEvent(SYNC_EVENT, { detail: next }));
+            return next;
+        });
+    }, []);
+    return { enabled, toggle };
+}

package/dist/src/presentation/web/hooks/use-sound.d.ts

@@ -0,0 +1,15 @@
+declare const SOUND_NAMES: readonly ["button", "caution", "celebration", "disabled", "notification", "progress_loop", "ringtone_loop", "select", "swipe", "swipe_01", "swipe_02", "swipe_03", "swipe_04", "swipe_05", "tap_01", "tap_02", "tap_03", "tap_04", "tap_05", "toggle_off", "toggle_on", "transition_down", "transition_up", "type_01", "type_02", "type_03", "type_04", "type_05"];
+export type SoundName = (typeof SOUND_NAMES)[number];
+export interface UseSoundOptions {
+    volume?: number;
+    loop?: boolean;
+}
+export interface UseSoundResult {
+    play: () => void;
+    stop: () => void;
+    isPlaying: boolean;
+}
+export declare function useSound(name: SoundName, options?: UseSoundOptions): UseSoundResult;
+/** All available sound names for enumeration (e.g. in Storybook). */
+export { SOUND_NAMES };
+//# sourceMappingURL=use-sound.d.ts.map

package/dist/src/presentation/web/hooks/use-sound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sound.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-sound.ts"],"names":[],"mappings":"AAKA,QAAA,MAAM,WAAW,oWA6BP,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAgDvF;AAED,qEAAqE;AACrE,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/src/presentation/web/hooks/use-sound.js

@@ -0,0 +1,83 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+import { useSoundEnabled } from './use-sound-enabled.js';
+const SOUND_NAMES = [
+    'button',
+    'caution',
+    'celebration',
+    'disabled',
+    'notification',
+    'progress_loop',
+    'ringtone_loop',
+    'select',
+    'swipe',
+    'swipe_01',
+    'swipe_02',
+    'swipe_03',
+    'swipe_04',
+    'swipe_05',
+    'tap_01',
+    'tap_02',
+    'tap_03',
+    'tap_04',
+    'tap_05',
+    'toggle_off',
+    'toggle_on',
+    'transition_down',
+    'transition_up',
+    'type_01',
+    'type_02',
+    'type_03',
+    'type_04',
+    'type_05',
+];
+export function useSound(name, options = {}) {
+    const { volume = 1, loop = false } = options;
+    const { enabled } = useSoundEnabled();
+    const audioRef = useRef(null);
+    const isPlayingRef = useRef(false);
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const audio = new Audio(`/sounds/${name}.wav`);
+        audio.preload = 'auto';
+        audio.loop = loop;
+        audio.volume = Math.max(0, Math.min(1, volume));
+        audio.addEventListener('ended', () => {
+            isPlayingRef.current = false;
+        });
+        audioRef.current = audio;
+        return () => {
+            audio.pause();
+            audio.removeAttribute('src');
+            audioRef.current = null;
+            isPlayingRef.current = false;
+        };
+    }, [name, loop, volume]);
+    const play = useCallback(() => {
+        if (!enabled)
+            return;
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        audio.currentTime = 0;
+        audio.play()?.catch((err) => {
+            if (process.env.NODE_ENV === 'development') {
+                // eslint-disable-next-line no-console
+                console.warn(`[useSound] play("${name}") blocked:`, err.message);
+            }
+        });
+        isPlayingRef.current = true;
+    }, [enabled, name]);
+    const stop = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        audio.pause();
+        audio.currentTime = 0;
+        isPlayingRef.current = false;
+    }, []);
+    return { play, stop, isPlaying: isPlayingRef.current };
+}
+/** All available sound names for enumeration (e.g. in Storybook). */
+export { SOUND_NAMES };

package/dist/src/presentation/web/hooks/use-sound.stories.d.ts

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '@storybook/react';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj<{
+    volume: number;
+}>;
+export declare const Catalog: Story;
+//# sourceMappingURL=use-sound.stories.d.ts.map

package/dist/src/presentation/web/hooks/use-sound.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sound.stories.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-sound.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAsFvD,QAAA,MAAM,IAAI,EAAE,IAcX,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE1C,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}

package/dist/src/presentation/web/hooks/use-sound.stories.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Button } from '../components/ui/button.js';
+import { useSound, SOUND_NAMES } from './use-sound.js';
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+const CATEGORIES = {
+    'UI Actions': ['button', 'select', 'disabled'],
+    Toggles: ['toggle_on', 'toggle_off'],
+    Transitions: ['transition_up', 'transition_down'],
+    Alerts: ['notification', 'caution', 'celebration'],
+    Swipes: ['swipe', 'swipe_01', 'swipe_02', 'swipe_03', 'swipe_04', 'swipe_05'],
+    Taps: ['tap_01', 'tap_02', 'tap_03', 'tap_04', 'tap_05'],
+    Typing: ['type_01', 'type_02', 'type_03', 'type_04', 'type_05'],
+    Loops: ['progress_loop', 'ringtone_loop'],
+};
+/* ------------------------------------------------------------------ */
+/*  Single sound player (used per button)                             */
+/* ------------------------------------------------------------------ */
+function SoundButton({ name, volume }) {
+    const isLoop = name.includes('loop');
+    const { play, stop } = useSound(name, { volume, loop: isLoop });
+    const [playing, setPlaying] = useState(false);
+    const handleClick = () => {
+        if (isLoop && playing) {
+            stop();
+            setPlaying(false);
+        }
+        else {
+            play();
+            setPlaying(true);
+            if (!isLoop) {
+                setTimeout(() => setPlaying(false), 2000);
+            }
+        }
+    };
+    return (_jsx(Button, { size: "sm", variant: playing ? 'default' : 'outline', onClick: handleClick, className: "min-w-[120px] font-mono text-xs", children: isLoop && playing ? `Stop ${name}` : name }));
+}
+/* ------------------------------------------------------------------ */
+/*  Full catalog demo                                                 */
+/* ------------------------------------------------------------------ */
+function SoundCatalog({ volume }) {
+    return (_jsxs("div", { className: "flex w-[560px] flex-col gap-6", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("h2", { className: "text-base font-semibold", children: "Sound Library" }), _jsxs("p", { className: "text-muted-foreground text-sm", children: [SOUND_NAMES.length, " sounds available at", ' ', _jsx("code", { className: "bg-muted rounded px-1 py-0.5 text-xs", children: "/sounds/*.wav" })] })] }), Object.entries(CATEGORIES).map(([category, sounds]) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-sm font-semibold", children: category }), _jsx("div", { className: "flex flex-wrap gap-2", children: sounds.map((name) => (_jsx(SoundButton, { name: name, volume: volume }, name))) })] }, category)))] }));
+}
+/* ------------------------------------------------------------------ */
+/*  Storybook meta                                                    */
+/* ------------------------------------------------------------------ */
+const meta = {
+    title: 'Hooks/useSound',
+    parameters: { layout: 'centered' },
+    tags: ['autodocs'],
+    argTypes: {
+        volume: {
+            control: { type: 'range', min: 0, max: 1, step: 0.1 },
+            description: 'Playback volume (0 to 1)',
+            defaultValue: 0.5,
+        },
+    },
+    args: {
+        volume: 0.5,
+    },
+};
+export default meta;
+export const Catalog = {
+    render: ({ volume }) => _jsx(SoundCatalog, { volume: volume }),
+};

package/dist/src/presentation/web/public/agent-events-sw.d.ts

@@ -0,0 +1,35 @@
+declare function connect(): void;
+declare function disconnect(): void;
+declare function cleanup(): void;
+declare function setStatus(status: any): void;
+declare function broadcast(message: any): Promise<void>;
+/**
+ * Service Worker: agent-events-sw.js
+ *
+ * Maintains a single SSE connection to /api/agent-events and broadcasts
+ * NotificationEvent deltas to all connected tabs via postMessage.
+ *
+ * Messages FROM clients:
+ *   { type: 'subscribe', runId?: string }  — register this tab
+ *   { type: 'unsubscribe' }                — unregister this tab
+ *
+ * Messages TO clients:
+ *   { type: 'notification', data: NotificationEvent }
+ *   { type: 'status', status: 'connected' | 'connecting' | 'disconnected' }
+ */
+declare const BASE_BACKOFF_MS: 1000;
+declare const MAX_BACKOFF_MS: 30000;
+declare const STABLE_CONNECTION_MS: 5000;
+/** @type {EventSource | null} */
+declare let eventSource: EventSource | null;
+/** @type {string | undefined} */
+declare let currentRunId: string | undefined;
+declare let backoff: number;
+/** @type {ReturnType<typeof setTimeout> | null} */
+declare let reconnectTimer: ReturnType<typeof setTimeout> | null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+declare let stableTimer: ReturnType<typeof setTimeout> | null;
+/** @type {'connected' | 'connecting' | 'disconnected'} */
+declare let connectionStatus: "connected" | "connecting" | "disconnected";
+declare let subscriberCount: number;
+//# sourceMappingURL=agent-events-sw.d.ts.map

package/dist/src/presentation/web/public/agent-events-sw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-events-sw.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/public/agent-events-sw.js"],"names":[],"mappings":"AAmFA,iCA6CC;AAED,oCAQC;AAED,iCASC;AAID,8CAGC;AAED,wDAKC;AAnKD;;;;;;;;;;;;;GAaG;AAIH,+BAAwB,IAAI,CAAC;AAC7B,8BAAuB,KAAM,CAAC;AAC9B,oCAA6B,IAAK,CAAC;AAEnC,iCAAiC;AACjC,yBADW,WAAW,GAAG,IAAI,CACN;AACvB,iCAAiC;AACjC,0BADW,MAAM,GAAG,SAAS,CACZ;AACjB,4BAA8B;AAC9B,mDAAmD;AACnD,4BADW,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CACrB;AAC1B,mDAAmD;AACnD,yBADW,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CACxB;AACvB,0DAA0D;AAC1D,8BADW,WAAW,GAAG,YAAY,GAAG,cAAc,CAChB;AACtC,oCAAwB"}