sygnal 5.2.0 → 5.3.0

package/dist/index.esm.js

@@ -2146,11 +2146,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 {
@@ -2253,7 +2259,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++;
@@ -2275,6 +2281,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
@@ -2403,6 +2410,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;
             });
         }
@@ -2474,6 +2484,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') {
@@ -2674,7 +2687,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');
@@ -2855,6 +2868,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));
@@ -2870,6 +2884,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$;
@@ -3392,6 +3412,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$) {
@@ -3530,6 +3557,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;
             }
@@ -3572,10 +3600,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: () => { },
@@ -3832,6 +3865,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;
@@ -4391,6 +4449,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();
@@ -4482,7 +4574,7 @@ function makeDragDriver() {
                     events(eventType) {
                         const busEventName = `${category}:${eventType}`;
                         let handler;
-                        return xs__default.create({
+                        const stream$ = xs__default.create({
                             start(listener) {
                                 handler = ({ detail }) => listener.next(detail);
                                 bus.addEventListener(busEventName, handler);
@@ -4492,6 +4584,7 @@ function makeDragDriver() {
                                     bus.removeEventListener(busEventName, handler);
                             },
                         });
+                        return enrichDragStream(stream$);
                     },
                 };
             },
@@ -4671,7 +4764,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 {
@@ -4751,6 +4849,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;
@@ -4770,6 +4874,7 @@ class SygnalDevTools {
             children: [],
             debug: instance._debug,
             createdAt: Date.now(),
+            mviGraph: this._extractMviGraph(instance),
             _instanceRef: new WeakRef(instance),
         };
         this._components.set(componentNumber, meta);
@@ -4794,7 +4899,6 @@ class SygnalDevTools {
             componentId: componentNumber,
             componentName: name,
             state: entry.state,
-            historyIndex: this._stateHistory.length - 1,
         });
     }
     onActionDispatched(componentNumber, name, actionType, data) {
@@ -4831,6 +4935,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) {
@@ -4859,20 +5033,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);
@@ -4883,11 +5116,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) {
@@ -4922,6 +5182,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;
@@ -5825,6 +6123,210 @@ function renderComponent(componentDef, options = {}) {
     };
 }
 
+/**
+ * Reducer helpers for common state update patterns.
+ *
+ * These reduce boilerplate in model definitions by providing
+ * shorthand factories for the most frequent reducer shapes.
+ */
+// ── set() ──────────────────────────────────────────────────────────
+/**
+ * Create a reducer that merges a partial update into state.
+ *
+ * Static form — merge a fixed object:
+ *   set({ isEditing: true })
+ *
+ * Dynamic form — function receives (state, data, next, props) and
+ * returns the partial update to merge:
+ *   set((state, title) => ({ title }))
+ */
+function set(partial) {
+    if (typeof partial === 'function') {
+        return (state, data, next, props) => ({
+            ...state,
+            ...partial(state, data, next, props),
+        });
+    }
+    return (state) => ({ ...state, ...partial });
+}
+// ── toggle() ───────────────────────────────────────────────────────
+/**
+ * Create a reducer that toggles a boolean field on state.
+ *
+ *   toggle('showModal')
+ *   // equivalent to: (state) => ({ ...state, showModal: !state.showModal })
+ */
+function toggle(field) {
+    return (state) => ({ ...state, [field]: !state[field] });
+}
+// ── emit() ─────────────────────────────────────────────────────────
+/**
+ * Create a model entry that emits an EVENTS bus event.
+ *
+ * With static data:
+ *   emit('DELETE_LANE', { laneId: 42 })
+ *
+ * With dynamic data derived from state:
+ *   emit('DELETE_LANE', (state) => ({ laneId: state.id }))
+ *
+ * Fire-and-forget (no data):
+ *   emit('REFRESH')
+ */
+function emit(type, data) {
+    return {
+        EVENTS: typeof data === 'function'
+            ? (state, actionData, next, props) => ({ type, data: data(state, actionData, next, props) })
+            : () => ({ 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__default.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 onlineStatus$() {
+    if (typeof window === 'undefined') {
+        return xs__default.of(true);
+    }
+    let cleanup;
+    return xs__default.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;
+        },
+    });
+}
+// ── 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__default.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.
  *
@@ -5995,6 +6497,24 @@ function processSSRTree(vnode, context, parentState) {
             key: undefined,
         };
     }
+    // ClientOnly: render fallback during SSR, skip children (they need a browser)
+    if (sel === 'clientonly') {
+        const props = vnode.data?.props || {};
+        const fallback = props.fallback;
+        if (fallback) {
+            // fallback can be a VNode or a string
+            return processSSRTree(fallback, context, parentState);
+        }
+        // No fallback — render an empty placeholder div
+        return {
+            sel: 'div',
+            data: { attrs: { 'data-sygnal-clientonly': '' } },
+            children: [],
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
     // Slot: unwrap to children
     if (sel === 'slot') {
         const children = vnode.children || [];
@@ -6474,4 +6994,4 @@ function buildAttributes(data, selectorId, selectorClasses) {
     return result;
 }
 
-export { ABORT, Collection, MainDOMSource, MockedDOMSource, Portal, Slot, Suspense, Switchable, Transition, classes, collection, component, createCommand, createElement, createRef, createRef$, driverFromAsync, enableHMR, exactState, getDevTools, lazy, makeDOMDriver, makeDragDriver, mockDOMSource, Portal as portal, processDrag, processForm, renderComponent, renderToString, run, switchable, thunk, xs };
+export { ABORT, Collection, MainDOMSource, MockedDOMSource, Portal, Slot, Suspense, Switchable, Transition, classes, collection, component, createCommand, createElement, createInstallPrompt, createRef, createRef$, driverFromAsync, emit, enableHMR, exactState, getDevTools, lazy, makeDOMDriver, makeDragDriver, makeServiceWorkerDriver, mockDOMSource, onlineStatus$, Portal as portal, processDrag, processForm, renderComponent, renderToString, run, set, switchable, thunk, toggle, xs };