sygnal 5.2.1 → 5.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "5.2.1",
+  "version": "5.3.1",
   "description": "An intuitive framework for building fast and small components or applications based on Cycle.js",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",

package/src/component.ts

@@ -369,6 +369,9 @@ class Component {
       this.sources.props$ = props$.map((val: any) => {
         const { sygnalFactory, sygnalOptions, ...sanitizedProps }: any = val
         this.currentProps = sanitizedProps
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+          window.__SYGNAL_DEVTOOLS__.onPropsChanged(this._componentNumber, this.name, sanitizedProps)
+        }
         return val
       })
     }
@@ -450,6 +453,9 @@ class Component {
   }
 
   dispose(): void {
+    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') {
@@ -870,6 +876,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: any) => ({...ev, __emitterId: _componentNumber, __emitterName: _name}))
+      }
       return acc
     }, {} as Record<string, any>)
 
@@ -1420,6 +1432,18 @@ 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 as any).__SYGNAL_DEVTOOLS__?.connected) {
+      const itemName = typeof collectionOf === 'function'
+        ? (collectionOf.componentName || collectionOf.label || collectionOf.name || 'anonymous')
+        : String(collectionOf)
+      ;(window as any).__SYGNAL_DEVTOOLS__.onCollectionMounted(
+        this._componentNumber, this.name, itemName,
+        typeof stateField === 'string' ? stateField : null
+      )
+    }
+
     return sink$
   }
 
@@ -1571,6 +1595,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 as Command)
         break
       }
@@ -1620,10 +1645,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 as any).__SYGNAL_DEVTOOLS__?.connected) {
+                    (window as any).__SYGNAL_DEVTOOLS__.onReadyChanged(this._componentNumber, this.name, id, !!ready)
+                  }
                 }
               },
               error: () => {},

package/src/extra/command.ts

@@ -16,6 +16,10 @@ export interface Command {
   _stream: Stream<CommandMessage>;
   /** @internal — marker for component.ts detection */
   __sygnalCommand: true;
+  /** @internal — stamped by component.ts when wired to a child */
+  _targetComponentId?: number;
+  /** @internal — stamped by component.ts when wired to a child */
+  _targetComponentName?: string;
 }
 
 export function createCommand(): Command {
@@ -26,11 +30,18 @@ export function createCommand(): Command {
     stop() { listener.next = () => {}; },
   });
 
-  return {
-    send: (type: string, data?: any) => listener.next({ type, data }),
+  const cmd: Command = {
+    send: (type: string, data?: any) => {
+      listener.next({ type, data });
+      if (typeof window !== 'undefined' && (window as any).__SYGNAL_DEVTOOLS__?.connected) {
+        (window as any).__SYGNAL_DEVTOOLS__.onCommandSent(type, data, cmd._targetComponentId, cmd._targetComponentName);
+      }
+    },
     _stream,
     __sygnalCommand: true as const,
   };
+
+  return cmd;
 }
 
 export function makeCommandSource(cmd: Command): CommandSource {

package/src/extra/devtools.ts

@@ -26,6 +26,12 @@ interface StateHistoryEntry {
   state: any;
 }
 
+interface MviGraphData {
+  sources: string[];
+  actions: {name: string; sinks: string[]}[];
+  contextProvides: string[];
+}
+
 interface ComponentMeta {
   id: number;
   name: string;
@@ -39,6 +45,7 @@ interface ComponentMeta {
   children: number[];
   debug: boolean;
   createdAt: number;
+  mviGraph: MviGraphData | null;
   _instanceRef: WeakRef<any>;
 }
 
@@ -94,6 +101,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;
@@ -114,6 +127,7 @@ class SygnalDevTools {
       children: [],
       debug: instance._debug,
       createdAt: Date.now(),
+      mviGraph: this._extractMviGraph(instance),
       _instanceRef: new WeakRef(instance),
     };
     this._components.set(componentNumber, meta);
@@ -141,7 +155,6 @@ class SygnalDevTools {
       componentId: componentNumber,
       componentName: name,
       state: entry.state,
-      historyIndex: this._stateHistory.length - 1,
     });
   }
 
@@ -179,6 +192,77 @@ class SygnalDevTools {
       componentId: componentNumber,
       componentName: name,
       context: this._safeClone(context),
+      contextTrace: this._buildContextTrace(componentNumber, context),
+    });
+  }
+
+  onPropsChanged(componentNumber: number, name: string, props: any): void {
+    if (!this.connected) return;
+    this._post('PROPS_CHANGED', {
+      componentId: componentNumber,
+      componentName: name,
+      props: this._safeClone(props),
+    });
+  }
+
+  onBusEvent(event: {type: string; data?: any; __emitterId?: number; __emitterName?: string}): void {
+    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: string, data: any, targetComponentId?: number, targetComponentName?: string): void {
+    if (!this.connected) return;
+    this._post('COMMAND_SENT', {
+      type,
+      data: this._safeClone(data),
+      targetComponentName: targetComponentName ?? null,
+      timestamp: Date.now(),
+    });
+  }
+
+  onReadyChanged(parentId: number, parentName: string, childKey: string, ready: boolean): void {
+    if (!this.connected) return;
+    this._post('READY_CHANGED', {
+      parentId,
+      parentName,
+      childKey,
+      ready,
+      timestamp: Date.now(),
+    });
+  }
+
+  onCollectionMounted(parentId: number, parentName: string, itemComponentName: string, stateField: string | null): void {
+    const meta = this._components.get(parentId);
+    if (meta) {
+      (meta as any).collection = {itemComponent: itemComponentName, stateField};
+    }
+    if (!this.connected) return;
+    this._post('COLLECTION_MOUNTED', {
+      parentId,
+      parentName,
+      itemComponent: itemComponentName,
+      stateField,
+    });
+  }
+
+  onComponentDisposed(componentNumber: number, name: string): void {
+    const meta = this._components.get(componentNumber);
+    if (meta) {
+      (meta as any).disposed = true;
+      (meta as any).disposedAt = Date.now();
+    }
+
+    if (!this.connected) return;
+    this._post('COMPONENT_DISPOSED', {
+      componentId: componentNumber,
+      componentName: name,
+      timestamp: Date.now(),
     });
   }
 
@@ -209,18 +293,78 @@ class SygnalDevTools {
     }
   }
 
-  _timeTravel({historyIndex}: {historyIndex: number}): void {
-    const entry = this._stateHistory[historyIndex];
-    if (!entry) return;
+  _timeTravel({componentId, componentName, state}: {componentId: number; componentName: string; state: any}): void {
+    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(): void {
+    const entries: {componentId: number; componentName: string; state: any}[] = [];
+    for (const [id, meta] of this._components) {
+      if ((meta as any).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: {entries: {componentId: number; componentName: string; state: any}[]}): void {
+    if (!snapshot?.entries) return;
+    for (const entry of snapshot.entries) {
+      this._timeTravel(entry);
     }
   }
 
@@ -233,12 +377,39 @@ 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: number, context: any): {field: string; providerId: number; providerName: string}[] {
+    if (!context || typeof context !== 'object') return [];
+    const trace: {field: string; providerId: number; providerName: string}[] = [];
+    const fields = Object.keys(context);
+
+    for (const field of fields) {
+      // Walk up parent chain to find which component provides this field
+      let currentId: number | null = 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(): void {
     const tree: any[] = [];
     for (const [, meta] of this._components) {
@@ -276,6 +447,49 @@ class SygnalDevTools {
     }
   }
 
+  _extractMviGraph(instance: any): MviGraphData | null {
+    if (!instance.model) return null;
+    try {
+      const sources = instance.sourceNames ? [...instance.sourceNames] : [];
+      const actions: {name: string; sinks: string[]}[] = [];
+      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: string) => 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: ComponentMeta): Omit<ComponentMeta, '_instanceRef'> {
     const {_instanceRef, ...rest} = meta;
     return rest;

package/src/extra/dragDriver.ts

@@ -8,19 +8,72 @@ export interface DragConfig {
   dragImage?: string;
 }
 
+// ─── Enriched DND Event Streams ──────────────────────────────────────────────
+
+export interface EnrichedDragStream<T = any> extends Stream<T> {
+  /** Extract a `data-*` attribute value from the payload's element/dataset.
+   *  Optional transform fn: `.data('id', Number)` */
+  data(name: string): EnrichedDragStream<string | undefined>;
+  data<R>(name: string, fn: (val: string | undefined) => R): EnrichedDragStream<R>;
+
+  /** Extract the dragged element (dragstart) or dropZone element (drop) */
+  element(): EnrichedDragStream<Element | null>;
+  element<R>(fn: (el: Element | null) => R): EnrichedDragStream<R>;
+}
+
+/**
+ * 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$: any): any {
+  // .data(name, fn?) — extract dataset[name] from dragstart payload,
+  // or dropZone.dataset[name] from drop payload
+  stream$.data = function data(name: string, fn?: (val: any) => any): any {
+    const mapped = stream$.map((e: any) => {
+      // dragstart payload: { element, dataset }
+      // drop payload: { dropZone, insertBefore }
+      const val = e?.dataset?.[name]
+        ?? (e?.dropZone as HTMLElement)?.dataset?.[name]
+        ?? (e?.element as HTMLElement)?.dataset?.[name]
+      return fn ? fn(val) : val
+    });
+    return enrichDragStream(mapped);
+  }
+
+  // .element(fn?) — extract the primary element from the payload
+  stream$.element = function element(fn?: (el: any) => any): any {
+    const mapped = stream$.map((e: any) => {
+      const el = e?.element ?? e?.dropZone ?? null
+      return fn ? fn(el) : el
+    });
+    return enrichDragStream(mapped);
+  }
+
+  return stream$
+}
+
+// ─── DND Source Interfaces ───────────────────────────────────────────────────
+
 export interface DragSourceEvents {
-  events(eventType: string): Stream<any>;
+  events(eventType: string): EnrichedDragStream<any>;
 }
 
 export interface DragSource {
   select(category: string): DragSourceEvents;
-  dragstart(category: string): Stream<any>;
+  dragstart(category: string): EnrichedDragStream<any>;
   dragend(category: string): Stream<any>;
-  drop(category: string): Stream<any>;
+  drop(category: string): EnrichedDragStream<any>;
   dragover(category: string): Stream<any>;
   dispose(): void;
 }
 
+// ─── Driver Factory ──────────────────────────────────────────────────────────
+
 export function makeDragDriver(): (sink$: Stream<any>) => DragSource {
   return function dragDriver(sink$: Stream<any>): DragSource {
     const categories = new Map<string, DragConfig>();
@@ -114,10 +167,10 @@ export function makeDragDriver(): (sink$: Stream<any>) => DragSource {
     const source: DragSource = {
       select(category: string): DragSourceEvents {
         return {
-          events(eventType: string): Stream<any> {
+          events(eventType: string): EnrichedDragStream<any> {
             const busEventName = `${category}:${eventType}`;
             let handler: ((e: Event) => void) | undefined;
-            return xs.create({
+            const stream$ = xs.create({
               start(listener) {
                 handler = ({detail}: any) => listener.next(detail);
                 bus.addEventListener(busEventName, handler);
@@ -126,6 +179,7 @@ export function makeDragDriver(): (sink$: Stream<any>) => DragSource {
                 if (handler) bus.removeEventListener(busEventName, handler);
               },
             });
+            return enrichDragStream(stream$);
           },
         };
       },

package/src/extra/eventDriver.ts

@@ -14,8 +14,12 @@ export default function eventBusDriver(out$: Stream<BusEvent>): EventBusSource {
   const events = new EventTarget();
 
   out$.subscribe({
-    next: (event: BusEvent) =>
-      events.dispatchEvent(new CustomEvent('data', {detail: event})),
+    next: (event: BusEvent) => {
+      events.dispatchEvent(new CustomEvent('data', {detail: event}));
+      if (typeof window !== 'undefined' && (window as any).__SYGNAL_DEVTOOLS__?.connected) {
+        (window as any).__SYGNAL_DEVTOOLS__.onBusEvent(event);
+      }
+    },
     error: (err: any) =>
       console.error('[EVENTS driver] Error in sink stream:', err),
   });