sygnal 5.2.1 → 5.3.1

package/dist/index.cjs.js

@@ -2163,11 +2163,17 @@ function createCommand() {
         start(l) { listener.next = (val) => l.next(val); },
         stop() { listener.next = () => { }; },
     });
-    return {
-        send: (type, data) => listener.next({ type, data }),
+    const cmd = {
+        send: (type, data) => {
+            listener.next({ type, data });
+            if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+                window.__SYGNAL_DEVTOOLS__.onCommandSent(type, data, cmd._targetComponentId, cmd._targetComponentName);
+            }
+        },
         _stream,
         __sygnalCommand: true,
     };
+    return cmd;
 }
 function makeCommandSource(cmd) {
     return {
@@ -2421,6 +2427,9 @@ class Component {
             this.sources.props$ = props$.map((val) => {
                 const { sygnalFactory, sygnalOptions, ...sanitizedProps } = val;
                 this.currentProps = sanitizedProps;
+                if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+                    window.__SYGNAL_DEVTOOLS__.onPropsChanged(this._componentNumber, this.name, sanitizedProps);
+                }
                 return val;
             });
         }
@@ -2492,6 +2501,9 @@ class Component {
         }
     }
     dispose() {
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+            window.__SYGNAL_DEVTOOLS__.onComponentDisposed(this._componentNumber, this.name);
+        }
         // Fire the DISPOSE built-in action so model handlers can run cleanup logic
         const hasDispose = this.model && (this.model[DISPOSE_ACTION] || Object.keys(this.model).some(k => k.includes('|') && k.split('|')[0].trim() === DISPOSE_ACTION));
         if (hasDispose && this.action$ && typeof this.action$.shamefullySendNext === 'function') {
@@ -2889,6 +2901,12 @@ class Component {
             else {
                 acc[name] = xs.merge((this.model$[name] || xs.never()), subComponentSink$, ...(this.peers$[name] || []));
             }
+            // Stamp EVENTS sink emissions with emitter component info for devtools
+            if (name === 'EVENTS' && acc[name]) {
+                const _componentNumber = this._componentNumber;
+                const _name = this.name;
+                acc[name] = acc[name].map((ev) => ({ ...ev, __emitterId: _componentNumber, __emitterName: _name }));
+            }
             return acc;
         }, {});
         this.sinks[this.DOMSourceName] = this.vdom$;
@@ -3411,6 +3429,13 @@ class Component {
         if (!isObj(sink$)) {
             throw new Error(`[${this.name}] Invalid sinks returned from component factory of collection element`);
         }
+        // Notify devtools of collection mount
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+            const itemName = typeof collectionOf === 'function'
+                ? (collectionOf.componentName || collectionOf.label || collectionOf.name || 'anonymous')
+                : String(collectionOf);
+            window.__SYGNAL_DEVTOOLS__.onCollectionMounted(this._componentNumber, this.name, itemName, typeof stateField === 'string' ? stateField : null);
+        }
         return sink$;
     }
     instantiateSwitchable(el, props$, children$) {
@@ -3549,6 +3574,7 @@ class Component {
         for (const key of Object.keys(props)) {
             const val = props[key];
             if (val && val.__sygnalCommand) {
+                val._targetComponentName = componentName;
                 sources.commands$ = makeCommandSource(val);
                 break;
             }
@@ -3591,10 +3617,15 @@ class Component {
                             const wasReady = this._childReadyState[id];
                             this._childReadyState[id] = !!ready;
                             // When READY state changes, trigger a re-render
-                            if (wasReady !== !!ready && this._readyChangedListener) {
-                                setTimeout(() => {
-                                    this._readyChangedListener?.next(null);
-                                }, 0);
+                            if (wasReady !== !!ready) {
+                                if (this._readyChangedListener) {
+                                    setTimeout(() => {
+                                        this._readyChangedListener?.next(null);
+                                    }, 0);
+                                }
+                                if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+                                    window.__SYGNAL_DEVTOOLS__.onReadyChanged(this._componentNumber, this.name, id, !!ready);
+                                }
                             }
                         },
                         error: () => { },
@@ -4435,6 +4466,40 @@ function processDrag({ draggable, dropZone } = {}, options = {}) {
     return { dragStart$, dragEnd$, dragOver$, drop$ };
 }
 
+/**
+ * Adds chainable convenience methods to a DND event stream,
+ * mirroring the DOM driver's `enrichEventStream` pattern.
+ *
+ *   DND.dragstart('task').data('taskId')
+ *   DND.dragstart('task').data('taskId', Number)
+ *   DND.drop('lane').data('laneId')
+ *   DND.dragstart('task').element()
+ */
+function enrichDragStream(stream$) {
+    // .data(name, fn?) — extract dataset[name] from dragstart payload,
+    // or dropZone.dataset[name] from drop payload
+    stream$.data = function data(name, fn) {
+        const mapped = stream$.map((e) => {
+            // dragstart payload: { element, dataset }
+            // drop payload: { dropZone, insertBefore }
+            const val = e?.dataset?.[name]
+                ?? e?.dropZone?.dataset?.[name]
+                ?? e?.element?.dataset?.[name];
+            return fn ? fn(val) : val;
+        });
+        return enrichDragStream(mapped);
+    };
+    // .element(fn?) — extract the primary element from the payload
+    stream$.element = function element(fn) {
+        const mapped = stream$.map((e) => {
+            const el = e?.element ?? e?.dropZone ?? null;
+            return fn ? fn(el) : el;
+        });
+        return enrichDragStream(mapped);
+    };
+    return stream$;
+}
+// ─── Driver Factory ──────────────────────────────────────────────────────────
 function makeDragDriver() {
     return function dragDriver(sink$) {
         const categories = new Map();
@@ -4526,7 +4591,7 @@ function makeDragDriver() {
                     events(eventType) {
                         const busEventName = `${category}:${eventType}`;
                         let handler;
-                        return xs$1.create({
+                        const stream$ = xs$1.create({
                             start(listener) {
                                 handler = ({ detail }) => listener.next(detail);
                                 bus.addEventListener(busEventName, handler);
@@ -4536,6 +4601,7 @@ function makeDragDriver() {
                                     bus.removeEventListener(busEventName, handler);
                             },
                         });
+                        return enrichDragStream(stream$);
                     },
                 };
             },
@@ -4715,7 +4781,12 @@ function setupReusable(drivers) {
 function eventBusDriver(out$) {
     const events = new EventTarget();
     out$.subscribe({
-        next: (event) => events.dispatchEvent(new CustomEvent('data', { detail: event })),
+        next: (event) => {
+            events.dispatchEvent(new CustomEvent('data', { detail: event }));
+            if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+                window.__SYGNAL_DEVTOOLS__.onBusEvent(event);
+            }
+        },
         error: (err) => console.error('[EVENTS driver] Error in sink stream:', err),
     });
     return {
@@ -4795,6 +4866,12 @@ class SygnalDevTools {
             case 'TIME_TRAVEL':
                 this._timeTravel(msg.payload);
                 break;
+            case 'SNAPSHOT':
+                this._takeSnapshot();
+                break;
+            case 'RESTORE_SNAPSHOT':
+                this._restoreSnapshot(msg.payload);
+                break;
             case 'GET_STATE':
                 this._sendComponentState(msg.payload.componentId);
                 break;
@@ -4814,6 +4891,7 @@ class SygnalDevTools {
             children: [],
             debug: instance._debug,
             createdAt: Date.now(),
+            mviGraph: this._extractMviGraph(instance),
             _instanceRef: new WeakRef(instance),
         };
         this._components.set(componentNumber, meta);
@@ -4838,7 +4916,6 @@ class SygnalDevTools {
             componentId: componentNumber,
             componentName: name,
             state: entry.state,
-            historyIndex: this._stateHistory.length - 1,
         });
     }
     onActionDispatched(componentNumber, name, actionType, data) {
@@ -4875,6 +4952,76 @@ class SygnalDevTools {
             componentId: componentNumber,
             componentName: name,
             context: this._safeClone(context),
+            contextTrace: this._buildContextTrace(componentNumber, context),
+        });
+    }
+    onPropsChanged(componentNumber, name, props) {
+        if (!this.connected)
+            return;
+        this._post('PROPS_CHANGED', {
+            componentId: componentNumber,
+            componentName: name,
+            props: this._safeClone(props),
+        });
+    }
+    onBusEvent(event) {
+        if (!this.connected)
+            return;
+        this._post('BUS_EVENT', {
+            type: event.type,
+            data: this._safeClone(event.data),
+            componentId: event.__emitterId ?? null,
+            componentName: event.__emitterName ?? null,
+            timestamp: Date.now(),
+        });
+    }
+    onCommandSent(type, data, targetComponentId, targetComponentName) {
+        if (!this.connected)
+            return;
+        this._post('COMMAND_SENT', {
+            type,
+            data: this._safeClone(data),
+            targetComponentName: targetComponentName ?? null,
+            timestamp: Date.now(),
+        });
+    }
+    onReadyChanged(parentId, parentName, childKey, ready) {
+        if (!this.connected)
+            return;
+        this._post('READY_CHANGED', {
+            parentId,
+            parentName,
+            childKey,
+            ready,
+            timestamp: Date.now(),
+        });
+    }
+    onCollectionMounted(parentId, parentName, itemComponentName, stateField) {
+        const meta = this._components.get(parentId);
+        if (meta) {
+            meta.collection = { itemComponent: itemComponentName, stateField };
+        }
+        if (!this.connected)
+            return;
+        this._post('COLLECTION_MOUNTED', {
+            parentId,
+            parentName,
+            itemComponent: itemComponentName,
+            stateField,
+        });
+    }
+    onComponentDisposed(componentNumber, name) {
+        const meta = this._components.get(componentNumber);
+        if (meta) {
+            meta.disposed = true;
+            meta.disposedAt = Date.now();
+        }
+        if (!this.connected)
+            return;
+        this._post('COMPONENT_DISPOSED', {
+            componentId: componentNumber,
+            componentName: name,
+            timestamp: Date.now(),
         });
     }
     onDebugLog(componentNumber, message) {
@@ -4903,20 +5050,79 @@ class SygnalDevTools {
             }
         }
     }
-    _timeTravel({ historyIndex }) {
-        const entry = this._stateHistory[historyIndex];
-        if (!entry)
+    _timeTravel({ componentId, componentName, state }) {
+        if (componentId == null || !state) {
+            console.warn('[Sygnal DevTools] _timeTravel: missing componentId or state', { componentId, hasState: !!state });
             return;
+        }
         if (typeof window === 'undefined')
             return;
+        const newState = this._safeClone(state);
+        // Try per-component time-travel via the component's STATE sink (reducer stream)
+        const meta = this._components.get(componentId);
+        if (meta) {
+            const instance = meta._instanceRef?.deref();
+            if (!instance) {
+                console.warn(`[Sygnal DevTools] _timeTravel: WeakRef for component #${componentId} (${componentName}) has been GC'd`);
+            }
+            else {
+                // sinks[stateSourceName] is the reducer stream — push a reducer that replaces state
+                const stateSinkName = instance.stateSourceName || 'STATE';
+                const stateSink = instance.sinks?.[stateSinkName];
+                if (stateSink?.shamefullySendNext) {
+                    stateSink.shamefullySendNext(() => ({ ...newState }));
+                    this._post('TIME_TRAVEL_APPLIED', {
+                        componentId,
+                        componentName,
+                        state: newState,
+                    });
+                    return;
+                }
+                console.warn(`[Sygnal DevTools] _timeTravel: component #${componentId} (${componentName}) has no STATE sink with shamefullySendNext. sinkName=${stateSinkName}, hasSinks=${!!instance.sinks}, sinkKeys=${instance.sinks ? Object.keys(instance.sinks).join(',') : 'none'}`);
+            }
+        }
+        else {
+            console.warn(`[Sygnal DevTools] _timeTravel: no meta for componentId ${componentId}`);
+        }
+        // Fall back to root STATE sink for root-level components
         const app = window.__SYGNAL_DEVTOOLS_APP__;
         if (app?.sinks?.STATE?.shamefullySendNext) {
-            app.sinks.STATE.shamefullySendNext(() => ({ ...entry.state }));
+            app.sinks.STATE.shamefullySendNext(() => ({ ...newState }));
             this._post('TIME_TRAVEL_APPLIED', {
-                historyIndex,
-                state: entry.state,
+                componentId,
+                componentName,
+                state: newState,
             });
         }
+        else {
+            console.warn(`[Sygnal DevTools] _timeTravel: no fallback root STATE sink available`);
+        }
+    }
+    _takeSnapshot() {
+        const entries = [];
+        for (const [id, meta] of this._components) {
+            if (meta.disposed)
+                continue;
+            const instance = meta._instanceRef?.deref();
+            if (instance?.currentState != null) {
+                entries.push({
+                    componentId: id,
+                    componentName: meta.name,
+                    state: this._safeClone(instance.currentState),
+                });
+            }
+        }
+        this._post('SNAPSHOT_TAKEN', {
+            entries,
+            timestamp: Date.now(),
+        });
+    }
+    _restoreSnapshot(snapshot) {
+        if (!snapshot?.entries)
+            return;
+        for (const entry of snapshot.entries) {
+            this._timeTravel(entry);
+        }
     }
     _sendComponentState(componentId) {
         const meta = this._components.get(componentId);
@@ -4927,11 +5133,38 @@ class SygnalDevTools {
                     componentId,
                     state: this._safeClone(instance.currentState),
                     context: this._safeClone(instance.currentContext),
+                    contextTrace: this._buildContextTrace(componentId, instance.currentContext),
                     props: this._safeClone(instance.currentProps),
                 });
             }
         }
     }
+    _buildContextTrace(componentId, context) {
+        if (!context || typeof context !== 'object')
+            return [];
+        const trace = [];
+        const fields = Object.keys(context);
+        for (const field of fields) {
+            // Walk up parent chain to find which component provides this field
+            let currentId = componentId;
+            let found = false;
+            while (currentId != null) {
+                const meta = this._components.get(currentId);
+                if (!meta)
+                    break;
+                if (meta.mviGraph?.contextProvides?.includes(field)) {
+                    trace.push({ field, providerId: meta.id, providerName: meta.name });
+                    found = true;
+                    break;
+                }
+                currentId = meta.parentId;
+            }
+            if (!found) {
+                trace.push({ field, providerId: -1, providerName: 'unknown' });
+            }
+        }
+        return trace;
+    }
     _sendFullTree() {
         const tree = [];
         for (const [, meta] of this._components) {
@@ -4966,6 +5199,44 @@ class SygnalDevTools {
             return '[unserializable]';
         }
     }
+    _extractMviGraph(instance) {
+        if (!instance.model)
+            return null;
+        try {
+            const sources = instance.sourceNames ? [...instance.sourceNames] : [];
+            const actions = [];
+            const model = instance.model;
+            for (const key of Object.keys(model)) {
+                let actionName = key;
+                let entry = model[key];
+                // Handle shorthand 'ACTION | SINK'
+                if (key.includes('|')) {
+                    const parts = key.split('|').map((s) => s.trim());
+                    if (parts.length === 2 && parts[0] && parts[1]) {
+                        actionName = parts[0];
+                        actions.push({ name: actionName, sinks: [parts[1]] });
+                        continue;
+                    }
+                }
+                // Function → targets STATE
+                if (typeof entry === 'function') {
+                    actions.push({ name: actionName, sinks: [instance.stateSourceName || 'STATE'] });
+                    continue;
+                }
+                // Object → keys are sink names
+                if (entry && typeof entry === 'object') {
+                    actions.push({ name: actionName, sinks: Object.keys(entry) });
+                    continue;
+                }
+            }
+            const contextProvides = instance.context && typeof instance.context === 'object'
+                ? Object.keys(instance.context) : [];
+            return { sources, actions, contextProvides };
+        }
+        catch (e) {
+            return null;
+        }
+    }
     _serializeMeta(meta) {
         const { _instanceRef, ...rest } = meta;
         return rest;
@@ -5926,6 +6197,154 @@ function emit(type, data) {
     };
 }
 
+// ── makeServiceWorkerDriver ──────────────────────────────────
+function trackWorker(worker, events) {
+    const emit = (type, data) => events.dispatchEvent(new CustomEvent('data', { detail: { type, data } }));
+    worker.addEventListener('statechange', () => {
+        if (worker.state === 'installed')
+            emit('installed', true);
+        if (worker.state === 'activated')
+            emit('activated', true);
+    });
+    if (worker.state === 'installed')
+        emit('waiting', worker);
+    if (worker.state === 'activated')
+        emit('activated', true);
+}
+function makeServiceWorkerDriver(scriptUrl, options = {}) {
+    return function serviceWorkerDriver(sink$) {
+        const events = new EventTarget();
+        if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+            navigator.serviceWorker
+                .register(scriptUrl, { scope: options.scope })
+                .then((reg) => {
+                const emit = (type, data) => events.dispatchEvent(new CustomEvent('data', { detail: { type, data } }));
+                if (reg.installing)
+                    trackWorker(reg.installing, events);
+                if (reg.waiting)
+                    emit('waiting', reg.waiting);
+                if (reg.active)
+                    emit('activated', true);
+                reg.addEventListener('updatefound', () => {
+                    if (reg.installing)
+                        trackWorker(reg.installing, events);
+                });
+                navigator.serviceWorker.addEventListener('controllerchange', () => {
+                    emit('controlling', true);
+                });
+                navigator.serviceWorker.addEventListener('message', (e) => {
+                    emit('message', e.data);
+                });
+            })
+                .catch((err) => {
+                events.dispatchEvent(new CustomEvent('data', { detail: { type: 'error', data: err } }));
+            });
+            sink$.addListener({
+                next: (cmd) => {
+                    if (cmd.action === 'skipWaiting') {
+                        navigator.serviceWorker.ready.then((r) => {
+                            if (r.waiting)
+                                r.waiting.postMessage({ type: 'SKIP_WAITING' });
+                        });
+                    }
+                    else if (cmd.action === 'postMessage') {
+                        navigator.serviceWorker.ready.then((r) => {
+                            if (r.active)
+                                r.active.postMessage(cmd.data);
+                        });
+                    }
+                    else if (cmd.action === 'unregister') {
+                        navigator.serviceWorker.ready.then((r) => r.unregister());
+                    }
+                },
+                error: (err) => console.error('[SW driver] Error in sink stream:', err),
+            });
+        }
+        return {
+            select(type) {
+                let cb;
+                const in$ = xs$1.create({
+                    start: (listener) => {
+                        cb = ({ detail }) => {
+                            if (!type || detail.type === type)
+                                listener.next(detail.data);
+                        };
+                        events.addEventListener('data', cb);
+                    },
+                    stop: () => {
+                        if (cb)
+                            events.removeEventListener('data', cb);
+                    },
+                });
+                return adapt(in$);
+            },
+        };
+    };
+}
+// ── onlineStatus$ ────────────────────────────────────────────
+function _createOnlineStatus() {
+    if (typeof window === 'undefined') {
+        return xs$1.of(true);
+    }
+    let cleanup;
+    return xs$1.create({
+        start(listener) {
+            listener.next(navigator.onLine);
+            const on = () => listener.next(true);
+            const off = () => listener.next(false);
+            window.addEventListener('online', on);
+            window.addEventListener('offline', off);
+            cleanup = () => {
+                window.removeEventListener('online', on);
+                window.removeEventListener('offline', off);
+            };
+        },
+        stop() {
+            cleanup?.();
+            cleanup = undefined;
+        },
+    });
+}
+const onlineStatus$ = _createOnlineStatus();
+// ── createInstallPrompt ──────────────────────────────────────
+function createInstallPrompt() {
+    let deferredPrompt = null;
+    const events = new EventTarget();
+    if (typeof window !== 'undefined') {
+        window.addEventListener('beforeinstallprompt', (e) => {
+            e.preventDefault();
+            deferredPrompt = e;
+            events.dispatchEvent(new CustomEvent('data', { detail: { type: 'beforeinstallprompt', data: true } }));
+        });
+        window.addEventListener('appinstalled', () => {
+            deferredPrompt = null;
+            events.dispatchEvent(new CustomEvent('data', { detail: { type: 'appinstalled', data: true } }));
+        });
+    }
+    return {
+        select(type) {
+            let cb;
+            const in$ = xs$1.create({
+                start: (listener) => {
+                    cb = ({ detail }) => {
+                        if (detail.type === type)
+                            listener.next(detail.data);
+                    };
+                    events.addEventListener('data', cb);
+                },
+                stop: () => {
+                    if (cb)
+                        events.removeEventListener('data', cb);
+                },
+            });
+            return adapt(in$);
+        },
+        prompt() {
+            return deferredPrompt?.prompt();
+        },
+    };
+}
+
 /**
  * Server-Side Rendering utilities for Sygnal components.
  *
@@ -6616,6 +7035,7 @@ exports.collection = collection;
 exports.component = component;
 exports.createCommand = createCommand;
 exports.createElement = createElement;
+exports.createInstallPrompt = createInstallPrompt;
 exports.createRef = createRef;
 exports.createRef$ = createRef$;
 exports.driverFromAsync = driverFromAsync;
@@ -6626,7 +7046,9 @@ exports.getDevTools = getDevTools;
 exports.lazy = lazy;
 exports.makeDOMDriver = makeDOMDriver;
 exports.makeDragDriver = makeDragDriver;
+exports.makeServiceWorkerDriver = makeServiceWorkerDriver;
 exports.mockDOMSource = mockDOMSource;
+exports.onlineStatus$ = onlineStatus$;
 exports.portal = Portal;
 exports.processDrag = processDrag;
 exports.processForm = processForm;

package/dist/index.d.ts

@@ -595,6 +595,35 @@ export interface CommandSource {
 
 export function createCommand(): Command
 
+// ── PWA Helpers ──────────────────────────────────────────────
+
+export interface ServiceWorkerSource {
+  select(type?: 'installed' | 'activated' | 'waiting' | 'controlling' | 'error' | 'message' | string): Stream<any>;
+}
+
+export interface ServiceWorkerCommand {
+  action: 'skipWaiting' | 'postMessage' | 'unregister';
+  data?: any;
+}
+
+export interface ServiceWorkerOptions {
+  scope?: string;
+}
+
+export function makeServiceWorkerDriver(
+  scriptUrl: string,
+  options?: ServiceWorkerOptions
+): (sink$: Stream<ServiceWorkerCommand>) => ServiceWorkerSource
+
+export const onlineStatus$: Stream<boolean>
+
+export interface InstallPrompt {
+  select(type: 'beforeinstallprompt' | 'appinstalled'): Stream<any>;
+  prompt(): Promise<any> | undefined;
+}
+
+export function createInstallPrompt(): InstallPrompt
+
 export interface RenderOptions {
   /** Override initial state (defaults to component's .initialState) */
   initialState?: any;