sygnal 5.2.0 → 5.3.0

package/README.md

@@ -26,7 +26,7 @@ cd my-app
 npm run dev
 ```
 
-Choose from Vite (SPA), Vike (SSR), or Astro templates in JavaScript or TypeScript.
+Choose from Vite (SPA), Vite + PWA, Vike (SSR), or Astro templates in JavaScript or TypeScript.
 
 **Or add to an existing project:**
 
@@ -325,6 +325,25 @@ MyComponent.model = {
 
 For advanced cases needing stream composition, the `dispose$` source is also available in intent.
 
+### PWA Helpers
+
+Built-in service worker driver, online/offline detection, and install prompt handling:
+
+```jsx
+import { run, makeServiceWorkerDriver, onlineStatus$, createInstallPrompt } from 'sygnal'
+
+const installPrompt = createInstallPrompt()
+
+run(App, { SW: makeServiceWorkerDriver('/sw.js') })
+
+App.intent = ({ DOM, SW }) => ({
+  ONLINE_CHANGED: onlineStatus$(),
+  UPDATE_READY:   SW.select('waiting'),
+  APPLY_UPDATE:   DOM.click('.update-btn'),
+  INSTALL:        DOM.click('.install-btn'),
+})
+```
+
 ### Testing
 
 Test components in isolation with `renderComponent`:
@@ -404,7 +423,7 @@ import vikeSygnal from 'sygnal/config'
 export default { extends: [vikeSygnal] }
 ```
 
-Pages are standard Sygnal components in `pages/*/+Page.jsx`. Supports layouts, data fetching, and SPA mode.
+Pages are standard Sygnal components in `pages/*/+Page.jsx`. Supports layouts, data fetching, SPA mode, and `ClientOnly` for browser-only components.
 
 ### TypeScript
 

package/dist/astro/client.cjs.js

@@ -5029,7 +5029,12 @@ function makeDOMDriver(container, options = {}) {
 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 {
@@ -5532,7 +5537,7 @@ function component(opts) {
     return returnFunction;
 }
 class Component {
-    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', onError, debug = false }) {
+    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', isolatedState = false, onError, debug = false }) {
         if (!sources || !isObj(sources))
             throw new Error(`[${name}] Missing or invalid sources`);
         this._componentNumber = COMPONENT_COUNT++;
@@ -5554,6 +5559,7 @@ class Component {
         this.requestSourceName = requestSourceName;
         this.sourceNames = Object.keys(sources);
         this.onError = onError;
+        this.isolatedState = isolatedState;
         this._debug = debug;
         // Warn if calculated fields shadow base state keys
         if (this.calculated && this.initialState
@@ -5682,6 +5688,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;
             });
         }
@@ -5753,6 +5762,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') {
@@ -5953,7 +5965,7 @@ class Component {
         const hmrState = ENVIRONMENT?.__SYGNAL_HMR_STATE;
         const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
         const initial = { type: INITIALIZE_ACTION, data: effectiveInitialState };
-        if (this.isSubComponent && this.initialState) {
+        if (this.isSubComponent && this.initialState && !this.isolatedState) {
             console.warn(`[${this.name}] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
         }
         const hasInitialState = (typeof effectiveInitialState !== 'undefined');
@@ -6134,6 +6146,7 @@ class Component {
             .map((vdom) => processLazy(vdom, this))
             .map(processPortals)
             .map(processTransitions)
+            .map(processClientOnly)
             .compose(this.instantiateSubComponents.bind(this))
             .filter((val) => val !== undefined)
             .compose(this.renderVdom.bind(this));
@@ -6149,6 +6162,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$;
@@ -6671,6 +6690,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$) {
@@ -6809,6 +6835,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;
             }
@@ -6851,10 +6878,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: () => { },
@@ -7111,6 +7143,31 @@ function processTransitions(vnode) {
     }
     return vnode;
 }
+function processClientOnly(vnode) {
+    if (!vnode || !vnode.sel)
+        return vnode;
+    if (vnode.sel === 'clientonly') {
+        // On the client, unwrap to children (render them normally)
+        const children = vnode.children || [];
+        if (children.length === 0)
+            return { sel: 'div', data: {}, children: [] };
+        if (children.length === 1)
+            return processClientOnly(children[0]);
+        // Multiple children: wrap in a div
+        return {
+            sel: 'div',
+            data: {},
+            children: children.map(processClientOnly),
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
+    if (vnode.children && vnode.children.length > 0) {
+        vnode.children = vnode.children.map(processClientOnly);
+    }
+    return vnode;
+}
 function applyTransitionHooks(vnode, name, duration) {
     const existingInsert = vnode.data?.hook?.insert;
     const existingRemove = vnode.data?.hook?.remove;
@@ -7465,6 +7522,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;
@@ -7484,6 +7547,7 @@ class SygnalDevTools {
             children: [],
             debug: instance._debug,
             createdAt: Date.now(),
+            mviGraph: this._extractMviGraph(instance),
             _instanceRef: new WeakRef(instance),
         };
         this._components.set(componentNumber, meta);
@@ -7508,7 +7572,6 @@ class SygnalDevTools {
             componentId: componentNumber,
             componentName: name,
             state: entry.state,
-            historyIndex: this._stateHistory.length - 1,
         });
     }
     onActionDispatched(componentNumber, name, actionType, data) {
@@ -7545,6 +7608,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) {
@@ -7573,20 +7706,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);
@@ -7597,11 +7789,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) {
@@ -7636,6 +7855,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;