sygnal 4.2.0 → 4.3.0

package/dist/astro/client.mjs

@@ -90,7 +90,8 @@ 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 })),
+    error: err => console.error('[EVENTS driver] Error in sink stream:', err)
   });
 
   return {
@@ -118,11 +119,19 @@ function logDriver(out$) {
   out$.addListener({
     next: (val) => {
       console.log(val);
+    },
+    error: (err) => {
+      console.error('[LOG driver] Error in sink stream:', err);
     }
   });
 }
 
+let COLLECTION_COUNT = 0;
+
 function collection(component, stateLense, opts={}) {
+  if (typeof component !== 'function') {
+    throw new Error('collection: first argument (component) must be a function')
+  }
   const {
     combineList     = ['DOM'],
     globalList      = ['EVENTS'],
@@ -133,7 +142,7 @@ function collection(component, stateLense, opts={}) {
   } = opts;
 
   return (sources) => {
-    const key = Date.now();
+    const key = `sygnal-collection-${COLLECTION_COUNT++}`;
     const collectionOpts = {
       item:         component,
       itemKey:      (state, ind) => typeof state.id !== 'undefined' ? state.id : ind,
@@ -2904,7 +2913,7 @@ function switchable(factories, name$, initial, opts={}) {
     const mapFunction = (nameType === 'function' && name$) || (state => state[name$]);
     return sources => {
       const state$ = sources && ((typeof stateSourceName === 'string' && sources[stateSourceName]) || sources.STATE || sources.state).stream;
-      if (!state$ instanceof Stream$1) throw new Error(`Could not find the state source: ${ stateSourceName }`)
+      if (!(state$ instanceof Stream$1)) throw new Error(`Could not find the state source: ${stateSourceName}`)
       const _name$ = state$
         .map(mapFunction)
         .filter(name => typeof name === 'string')
@@ -3311,13 +3320,27 @@ function wrapDOMSource(domSource) {
 }
 
 
-const ABORT = '~#~#~ABORT~#~#~';
+const ABORT = Symbol('ABORT');
+
+
+function normalizeCalculatedEntry(field, entry) {
+  if (typeof entry === 'function') {
+    return { fn: entry, deps: null }
+  }
+  if (Array.isArray(entry) && entry.length === 2
+      && Array.isArray(entry[0]) && typeof entry[1] === 'function') {
+    return { fn: entry[1], deps: entry[0] }
+  }
+  throw new Error(
+    `Invalid calculated field '${field}': expected a function or [depsArray, function]`
+  )
+}
 
 function component (opts) {
   const { name, sources, isolateOpts, stateSourceName='STATE' } = opts;
 
   if (sources && !isObj(sources)) {
-    throw new Error('Sources must be a Cycle.js sources object:', name)
+    throw new Error(`[${name}] Sources must be a Cycle.js sources object`)
   }
 
   let fixedIsolateOpts;
@@ -3397,7 +3420,9 @@ class Component {
   // sinks
 
   constructor({ name='NO NAME', sources, intent, model, hmrActions, context, response, view, peers={}, components={}, initialState, calculated, storeCalculatedInState=true, DOMSourceName='DOM', stateSourceName='STATE', requestSourceName='HTTP', debug=false }) {
-    if (!sources || !isObj(sources)) throw new Error('Missing or invalid sources')
+    if (!sources || !isObj(sources)) throw new Error(`[${name}] Missing or invalid sources`)
+
+    this._componentNumber = COMPONENT_COUNT++;
 
     this.name       = name;
     this.sources    = sources;
@@ -3418,6 +3443,123 @@ class Component {
     this.sourceNames       = Object.keys(sources);
     this._debug            = debug;
 
+    // Warn if calculated fields shadow base state keys
+    if (this.calculated && this.initialState
+        && isObj(this.calculated) && isObj(this.initialState)) {
+      for (const key of Object.keys(this.calculated)) {
+        if (key in this.initialState) {
+          console.warn(
+            `[${name}] Calculated field '${key}' shadows a key in initialState. ` +
+            `The initialState value will be overwritten on every state update.`
+          );
+        }
+      }
+    }
+
+    // Normalize calculated entries, build dependency graph, topological sort
+    if (this.calculated && isObj(this.calculated)) {
+      const calcEntries = Object.entries(this.calculated);
+
+      // Normalize all entries to { fn, deps } shape
+      this._calculatedNormalized = {};
+      for (const [field, entry] of calcEntries) {
+        this._calculatedNormalized[field] = normalizeCalculatedEntry(field, entry);
+      }
+
+      this._calculatedFieldNames = new Set(Object.keys(this._calculatedNormalized));
+
+      // Warn on deps referencing nonexistent keys
+      for (const [field, { deps }] of Object.entries(this._calculatedNormalized)) {
+        if (deps !== null) {
+          for (const dep of deps) {
+            if (!this._calculatedFieldNames.has(dep)
+                && this.initialState && !(dep in this.initialState)) {
+              console.warn(
+                `[${name}] Calculated field '${field}' declares dependency '${dep}' ` +
+                `which is not in initialState or calculated fields`
+              );
+            }
+          }
+        }
+      }
+
+      // Build adjacency: for each field, which other calculated fields must run first?
+      const calcDeps = {};
+      for (const [field, { deps }] of Object.entries(this._calculatedNormalized)) {
+        if (deps === null) {
+          calcDeps[field] = [];
+        } else {
+          calcDeps[field] = deps.filter(d => this._calculatedFieldNames.has(d));
+        }
+      }
+
+      // Kahn's algorithm for topological sort
+      const inDegree = {};
+      const reverseGraph = {};
+      for (const field of this._calculatedFieldNames) {
+        inDegree[field] = 0;
+        reverseGraph[field] = [];
+      }
+      for (const [field, depList] of Object.entries(calcDeps)) {
+        inDegree[field] = depList.length;
+        for (const dep of depList) {
+          reverseGraph[dep].push(field);
+        }
+      }
+
+      const queue = [];
+      for (const [field, degree] of Object.entries(inDegree)) {
+        if (degree === 0) queue.push(field);
+      }
+
+      const sorted = [];
+      while (queue.length > 0) {
+        const current = queue.shift();
+        sorted.push(current);
+        for (const dependent of reverseGraph[current]) {
+          inDegree[dependent]--;
+          if (inDegree[dependent] === 0) queue.push(dependent);
+        }
+      }
+
+      if (sorted.length !== this._calculatedFieldNames.size) {
+        // Cycle detected — build error message with cycle path
+        const inCycle = [...this._calculatedFieldNames].filter(f => !sorted.includes(f));
+        const visited = new Set();
+        const path = [];
+        const traceCycle = (node) => {
+          if (visited.has(node)) { path.push(node); return true }
+          visited.add(node);
+          path.push(node);
+          for (const dep of calcDeps[node]) {
+            if (inCycle.includes(dep) && traceCycle(dep)) return true
+          }
+          path.pop();
+          visited.delete(node);
+          return false
+        };
+        traceCycle(inCycle[0]);
+        const start = path[path.length - 1];
+        const cycle = path.slice(path.indexOf(start));
+        throw new Error(`Circular calculated dependency: ${cycle.join(' \u2192 ')}`)
+      }
+
+      this._calculatedOrder = sorted.map(f => [f, this._calculatedNormalized[f]]);
+
+      // Initialize per-field memoization caches for fields with declared deps
+      this._calculatedFieldCache = {};
+      for (const [field, { deps }] of this._calculatedOrder) {
+        if (deps !== null) {
+          this._calculatedFieldCache[field] = { lastDepValues: undefined, lastResult: undefined };
+        }
+      }
+    } else {
+      this._calculatedOrder = null;
+      this._calculatedNormalized = null;
+      this._calculatedFieldNames = null;
+      this._calculatedFieldCache = null;
+    }
+
     this.isSubComponent = this.sourceNames.includes('props$');
 
     const state$ = sources[stateSourceName] && sources[stateSourceName].stream;
@@ -3426,6 +3568,9 @@ class Component {
       this.currentState = initialState || {};
       this.sources[stateSourceName] = new StateSource(state$.map(val => {
         this.currentState = val;
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+          window.__SYGNAL_DEVTOOLS__.onStateChanged(this._componentNumber, this.name, val);
+        }
         return val
       }));
     }
@@ -3461,10 +3606,8 @@ class Component {
       };
     }
 
-    const componentNumber = COMPONENT_COUNT++;
-
     this.addCalculated = this.createMemoizedAddCalculated();
-    this.log = makeLog(`${componentNumber} | ${name}`);
+    this.log = makeLog(`${this._componentNumber} | ${name}`);
 
     this.initChildSources$();
     this.initIntent$();
@@ -3479,9 +3622,20 @@ class Component {
     this.initVdom$();
     this.initSinks();
 
-    this.sinks.__index = componentNumber;
+    this.sinks.__index = this._componentNumber;
 
     this.log(`Instantiated`, true);
+
+    // Hook 1: Register with DevTools
+    if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__) {
+      window.__SYGNAL_DEVTOOLS__.onComponentCreated(this._componentNumber, name, this);
+
+      // Hook 1b: Register parent-child relationship
+      const parentNum = sources?.__parentComponentNumber;
+      if (typeof parentNum === 'number') {
+        window.__SYGNAL_DEVTOOLS__.onSubComponentRegistered(parentNum, this._componentNumber);
+      }
+    }
   }
 
   get debug() {
@@ -3493,13 +3647,13 @@ class Component {
       return
     }
     if (typeof this.intent != 'function') {
-      throw new Error('Intent must be a function')
+      throw new Error(`[${this.name}] Intent must be a function`)
     }
 
     this.intent$ = this.intent(this.sources);
 
     if (!(this.intent$ instanceof Stream$1) && (!isObj(this.intent$))) {
-      throw new Error('Intent must return either an action$ stream or map of event streams')
+      throw new Error(`[${this.name}] Intent must return either an action$ stream or map of event streams`)
     }
   }
 
@@ -3512,10 +3666,10 @@ class Component {
       this.hmrActions = [this.hmrActions];
     }
     if (!Array.isArray(this.hmrActions)) {
-      throw new Error(`[${ this.name }] hmrActions must be the name of an action or an array of names of actions to run when a component is hot-reloaded`)
+      throw new Error(`[${this.name}] hmrActions must be the name of an action or an array of names of actions to run when a component is hot-reloaded`)
     }
     if (this.hmrActions.some(action => typeof action !== 'string')) {
-      throw new Error(`[${ this.name }] hmrActions must be the name of an action or an array of names of actions to run when a component is hot-reloaded`)
+      throw new Error(`[${this.name}] hmrActions must be the name of an action or an array of names of actions to run when a component is hot-reloaded`)
     }
     this.hmrAction$ = xs$1.fromArray(this.hmrActions.map(action => ({ type: action })));
   }
@@ -3554,7 +3708,15 @@ class Component {
     const hydrate$ = initialApiData.map(data => ({ type: HYDRATE_ACTION, data }));
 
     this.action$   = xs$1.merge(wrapped$, hydrate$)
-      .compose(this.log(({ type }) => `<${ type }> Action triggered`));
+      .compose(this.log(({ type }) => `<${type}> Action triggered`))
+      .map(action => {
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+          window.__SYGNAL_DEVTOOLS__.onActionDispatched(
+            this._componentNumber, this.name, action.type, action.data
+          );
+        }
+        return action
+      });
   }
 
   initState() {
@@ -3566,7 +3728,7 @@ class Component {
       } else if (isObj(this.model[INITIALIZE_ACTION])) {
         Object.keys(this.model[INITIALIZE_ACTION]).forEach(name => {
           if (name !== this.stateSourceName) {
-            console.warn(`${ INITIALIZE_ACTION } can only be used with the ${ this.stateSourceName } source... disregarding ${ name }`);
+            console.warn(`${INITIALIZE_ACTION} can only be used with the ${this.stateSourceName} source... disregarding ${name}`);
             delete this.model[INITIALIZE_ACTION][name];
           }
         });
@@ -3601,7 +3763,7 @@ class Component {
           } else if (valueType === 'function') {
             _value = value(state);
           } else {
-            console.error(`[${ this.name }] Invalid context entry '${ name }': must be the name of a state property or a function returning a value to use`);
+            console.error(`[${this.name}] Invalid context entry '${name}': must be the name of a state property or a function returning a value to use`);
             return acc
           }
           acc[name] = _value;
@@ -3609,11 +3771,14 @@ class Component {
         }, {});
         const newContext = { ..._parent, ...values };
         this.currentContext = newContext;
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+          window.__SYGNAL_DEVTOOLS__.onContextChanged(this._componentNumber, this.name, newContext);
+        }
         return newContext
       })
       .compose(dropRepeats(objIsEqual))
       .startWith({});
-    this.context$.subscribe({ next: _ => _ });
+    this.context$.subscribe({ next: _ => _, error: err => console.error(`[${this.name}] Error in context stream:`, err) });
   }
 
   initModel$() {
@@ -3629,7 +3794,7 @@ class Component {
     const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
     const initial  = { type: INITIALIZE_ACTION, data: effectiveInitialState };
     if (this.isSubComponent && this.initialState) {
-      console.warn(`[${ this.name }] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
+      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');
     const shouldInjectInitialState = hasInitialState && (ENVIRONMENT?.__SYGNAL_HMR_UPDATING !== true || typeof hmrState !== 'undefined');
@@ -3650,7 +3815,7 @@ class Component {
       }
 
       if (!isObj(sinks)) {
-        throw new Error(`Entry for each action must be an object: ${ this.name } ${ action }`)
+        throw new Error(`[${this.name}] Entry for each action must be an object: ${action}`)
       }
 
       const sinkEntries = Object.entries(sinks);
@@ -3667,12 +3832,12 @@ class Component {
         const wrapped$ = on$
           .compose(this.log(data => {
             if (isStateSink) {
-              return `<${ action }> State reducer added`
+              return `<${action}> State reducer added`
             } else if (isParentSink) {
-              return `<${ action }> Data sent to parent component: ${ JSON.stringify(data.value).replaceAll('"', '') }`
+              return `<${action}> Data sent to parent component: ${JSON.stringify(data.value).replaceAll('"', '')}`
             } else {
               const extra = data && (data.type || data.command || data.name || data.key || (Array.isArray(data) && 'Array') || data);
-              return `<${ action }> Data sent to [${ sink }]: ${ JSON.stringify(extra).replaceAll('"', '') }`
+              return `<${action}> Data sent to [${sink}]: ${JSON.stringify(extra).replaceAll('"', '')}`
             }
           }));
 
@@ -3750,7 +3915,7 @@ class Component {
 
       }
     });
-    subComponentSink$.subscribe({ next: _ => _ });
+    subComponentSink$.subscribe({ next: _ => _, error: err => console.error(`[${this.name}] Error in sub-component sink stream:`, err) });
     this.subComponentSink$ = subComponentSink$.filter(sinks => Object.keys(sinks).length > 0);
   }
 
@@ -3813,13 +3978,13 @@ class Component {
       if (typeof reducer === 'function') {
         returnStream$ = filtered$.map(action => {
           const next = (type, data, delay=10) => {
-            if (typeof delay !== 'number') throw new Error(`[${ this.name } ] Invalid delay value provided to next() function in model action '${ name }'. Must be a number in ms.`)
+            if (typeof delay !== 'number') throw new Error(`[${this.name}] Invalid delay value provided to next() function in model action '${name}'. Must be a number in ms.`)
             // put the "next" action request at the end of the event loop so the "current" action completes first
             setTimeout(() => {
               // push the "next" action request into the action$ stream
               rootAction$.shamefullySendNext({ type, data });
             }, delay);
-            this.log(`<${ name }> Triggered a next() action: <${ type }> ${ delay }ms delay`, true);
+            this.log(`<${name}> Triggered a next() action: <${type}> ${delay}ms delay`, true);
           };
 
           const props = { ...this.currentProps, children: this.currentChildren, context: this.currentContext };
@@ -3831,7 +3996,7 @@ class Component {
               const enhancedState = this.addCalculated(_state);
               props.state = enhancedState;
               const newState = reducer(enhancedState, data, next, props);
-              if (newState == ABORT) return _state
+              if (newState === ABORT) return _state
               return this.cleanupCalculated(newState)
             }
           } else {
@@ -3840,13 +4005,13 @@ class Component {
             const reduced = reducer(enhancedState, data, next, props);
             const type = typeof reduced;
             if (isObj(reduced) || ['string', 'number', 'boolean', 'function'].includes(type)) return reduced
-            if (type == 'undefined') {
-              console.warn(`'undefined' value sent to ${ name }`);
+            if (type === 'undefined') {
+              console.warn(`[${this.name}] 'undefined' value sent to ${name}`);
               return reduced
             }
-            throw new Error(`Invalid reducer type for ${ name } ${ type }`)
+            throw new Error(`[${this.name}] Invalid reducer type for action '${name}': ${type}`)
           }
-        }).filter(result => result != ABORT);
+        }).filter(result => result !== ABORT);
       } else if (reducer === undefined || reducer === true) {
         returnStream$ = filtered$.map(({data}) => data);
       } else {
@@ -3867,7 +4032,7 @@ class Component {
       if (state === lastState) {
         return lastResult
       }
-      if (!isObj(this.calculated)) throw new Error(`'calculated' parameter must be an object mapping calculated state field named to functions`)
+      if (!isObj(this.calculated)) throw new Error(`[${this.name}] 'calculated' parameter must be an object mapping calculated state field names to functions`)
 
       const calculated = this.getCalculatedValues(state);
       if (!calculated) {
@@ -3886,19 +4051,55 @@ class Component {
   }
 
   getCalculatedValues(state) {
-    const entries = Object.entries(this.calculated || {});
-    if (entries.length === 0) {
+    if (!this._calculatedOrder || this._calculatedOrder.length === 0) {
       return
     }
-    return entries.reduce((acc, [field, fn]) => {
-      if (typeof fn !== 'function') throw new Error(`Missing or invalid calculator function for calculated field '${ field }`)
-      try {
-        acc[field] = fn(state);
-      } catch(e) {
-        console.warn(`Calculated field '${ field }' threw an error during calculation: ${ e.message }`);
+
+    const mergedState = { ...state };
+    const computedSoFar = {};
+
+    for (const [field, { fn, deps }] of this._calculatedOrder) {
+      if (deps !== null && this._calculatedFieldCache) {
+        const cache = this._calculatedFieldCache[field];
+        const currentDepValues = deps.map(d => mergedState[d]);
+
+        if (cache.lastDepValues !== undefined) {
+          let unchanged = true;
+          for (let i = 0; i < currentDepValues.length; i++) {
+            if (currentDepValues[i] !== cache.lastDepValues[i]) {
+              unchanged = false;
+              break
+            }
+          }
+          if (unchanged) {
+            computedSoFar[field] = cache.lastResult;
+            mergedState[field] = cache.lastResult;
+            continue
+          }
+        }
+
+        try {
+          const result = fn(mergedState);
+          cache.lastDepValues = currentDepValues;
+          cache.lastResult = result;
+          computedSoFar[field] = result;
+          mergedState[field] = result;
+        } catch (e) {
+          console.warn(`Calculated field '${field}' threw an error during calculation: ${e.message}`);
+        }
+      } else {
+        // No deps declared — always recompute
+        try {
+          const result = fn(mergedState);
+          computedSoFar[field] = result;
+          mergedState[field] = result;
+        } catch (e) {
+          console.warn(`Calculated field '${field}' threw an error during calculation: ${e.message}`);
+        }
       }
-      return acc
-    }, {})
+    }
+
+    return computedSoFar
   }
 
   cleanupCalculated(incomingState) {
@@ -4046,7 +4247,7 @@ class Component {
       this.newChildSources(childSources);
 
 
-      if (newInstanceCount > 0) this.log(`New sub components instantiated: ${ newInstanceCount }`, true);
+      if (newInstanceCount > 0) this.log(`New sub components instantiated: ${newInstanceCount}`, true);
 
       return newComponents
     }, {})
@@ -4112,7 +4313,7 @@ class Component {
     } else if (this.components[collectionOf]) {
       factory = this.components[collectionOf];
     } else {
-      throw new Error(`[${this.name}] Invalid 'of' propery in collection: ${ collectionOf }`)
+      throw new Error(`[${this.name}] Invalid 'of' property in collection: ${collectionOf}`)
     }
 
     const fieldLense = {
@@ -4120,7 +4321,7 @@ class Component {
         if (!Array.isArray(state[stateField])) return []
         const items = state[stateField];
         const filtered = typeof arrayOperators.filter === 'function' ? items.filter(arrayOperators.filter) : items;
-        const sorted = typeof arrayOperators.sort ? filtered.sort(arrayOperators.sort) : filtered;
+        const sorted = typeof arrayOperators.sort === 'function' ? filtered.sort(arrayOperators.sort) : filtered;
         const mapped = sorted.map((item, index) => {
           return (isObj(item)) ? { ...item, [idField]: item[idField] || index } : { value: item, [idField]: index }
         });
@@ -4129,7 +4330,7 @@ class Component {
       },
       set: (oldState, newState) => {
         if (this.calculated && stateField in this.calculated) {
-          console.warn(`Collection sub-component of ${ this.name } attempted to update state on a calculated field '${ stateField }': Update ignored`);
+          console.warn(`Collection sub-component of ${this.name} attempted to update state on a calculated field '${stateField}': Update ignored`);
           return oldState
         }
         const updated = [];
@@ -4158,17 +4359,17 @@ class Component {
     } else if (typeof stateField === 'string') {
       if (isObj(this.currentState)) {
         if(!(this.currentState && stateField in this.currentState) && !(this.calculated && stateField in this.calculated)) {
-          console.error(`Collection component in ${ this.name } is attempting to use non-existent state property '${ stateField }': To fix this error, specify a valid array property on the state.  Attempting to use parent component state.`);
+          console.error(`Collection component in ${this.name} is attempting to use non-existent state property '${stateField}': To fix this error, specify a valid array property on the state.  Attempting to use parent component state.`);
           lense = undefined;
         } else if (!Array.isArray(this.currentState[stateField])) {
-          console.warn(`State property '${ stateField }' in collection comopnent of ${ this.name } is not an array: No components will be instantiated in the collection.`);
+          console.warn(`[${this.name}] State property '${stateField}' in collection component is not an array: No components will be instantiated in the collection.`);
           lense = fieldLense;
         } else {
           lense = fieldLense;
         }
       } else {
         if (!Array.isArray(this.currentState[stateField])) {
-          console.warn(`State property '${ stateField }' in collection component of ${ this.name } is not an array: No components will be instantiated in the collection.`);
+          console.warn(`[${this.name}] State property '${stateField}' in collection component is not an array: No components will be instantiated in the collection.`);
           lense = fieldLense;
         } else {
           lense = fieldLense;
@@ -4176,14 +4377,14 @@ class Component {
       }
     } else if (isObj(stateField)) {
       if (typeof stateField.get !== 'function') {
-        console.error(`Collection component in ${ this.name } has an invalid 'from' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting child state from the current state. Attempting to use parent component state.`);
+        console.error(`Collection component in ${this.name} has an invalid 'from' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting child state from the current state. Attempting to use parent component state.`);
         lense = undefined;
       } else {
         lense = {
           get: (state) => {
             const newState = stateField.get(state);
             if (!Array.isArray(newState)) {
-              console.warn(`State getter function in collection component of ${ this.name } did not return an array: No components will be instantiated in the collection. Returned value:`, newState);
+              console.warn(`State getter function in collection component of ${this.name} did not return an array: No components will be instantiated in the collection. Returned value:`, newState);
               return []
             }
             return newState
@@ -4192,14 +4393,14 @@ class Component {
         };
       }
     } else {
-      console.error(`Collection component in ${ this.name } has an invalid 'from' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting child state from the current state. Attempting to use parent component state.`);
+      console.error(`Collection component in ${this.name} has an invalid 'from' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting child state from the current state. Attempting to use parent component state.`);
       lense = undefined;
     }
 
-    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$, PARENT: null };
+    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$, PARENT: null, __parentComponentNumber: this._componentNumber };
     const sink$   = collection(factory, lense, { container: null })(sources);
     if (!isObj(sink$)) {
-      throw new Error('Invalid sinks returned from component factory of collection element')
+      throw new Error(`[${this.name}] Invalid sinks returned from component factory of collection element`)
     }
     return sink$
   }
@@ -4221,7 +4422,7 @@ class Component {
       get: state => state[stateField],
       set: (oldState, newState) => {
         if (this.calculated && stateField in this.calculated) {
-          console.warn(`Switchable sub-component of ${ this.name } attempted to update state on a calculated field '${ stateField }': Update ignored`);
+          console.warn(`Switchable sub-component of ${this.name} attempted to update state on a calculated field '${stateField}': Update ignored`);
           return oldState
         }
         if (!isObj(newState) || Array.isArray(newState)) return { ...oldState, [stateField]: newState }
@@ -4240,13 +4441,13 @@ class Component {
       lense = fieldLense;
     } else if (isObj(stateField)) {
       if (typeof stateField.get !== 'function') {
-        console.error(`Switchable component in ${ this.name } has an invalid 'state' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting sub-component state from the current state. Attempting to use parent component state.`);
+        console.error(`Switchable component in ${this.name} has an invalid 'state' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting sub-component state from the current state. Attempting to use parent component state.`);
         lense = baseLense;
       } else {
         lense = { get: stateField.get, set: stateField.set };
       }
     } else {
-      console.error(`Invalid state provided to switchable sub-component of ${ this.name }: Expecting string, object, or undefined, but found ${ typeof stateField }. Attempting to use parent component state.`);
+      console.error(`Invalid state provided to switchable sub-component of ${this.name}: Expecting string, object, or undefined, but found ${typeof stateField}. Attempting to use parent component state.`);
       lense = baseLense;
     }
 
@@ -4262,12 +4463,12 @@ class Component {
         switchableComponents[key] = component(options);
       }
     });
-    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$ };
+    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$, __parentComponentNumber: this._componentNumber };
 
     const sink$ = isolate(switchable(switchableComponents, props$.map(props => props.current)), { [this.stateSourceName]: lense })(sources);
 
     if (!isObj(sink$)) {
-      throw new Error('Invalid sinks returned from component factory of switchable element')
+      throw new Error(`[${this.name}] Invalid sinks returned from component factory of switchable element`)
     }
 
     return sink$
@@ -4293,7 +4494,7 @@ class Component {
     const factory   = componentName === 'sygnal-factory' ? props.sygnalFactory : (this.components[componentName] || props.sygnalFactory);
     if (!factory) {
       if (componentName === 'sygnal-factory') throw new Error(`Component not found on element with Capitalized selector and nameless function: JSX transpilation replaces selectors starting with upper case letters with functions in-scope with the same name, Sygnal cannot see the name of the resulting component.`)
-      throw new Error(`Component not found: ${ componentName }`)
+      throw new Error(`Component not found: ${componentName}`)
     }
 
     let lense;
@@ -4302,7 +4503,7 @@ class Component {
       get: state => state[stateField],
       set: (oldState, newState) => {
         if (this.calculated && stateField in this.calculated) {
-          console.warn(`Sub-component of ${ this.name } attempted to update state on a calculated field '${ stateField }': Update ignored`);
+          console.warn(`Sub-component of ${this.name} attempted to update state on a calculated field '${stateField}': Update ignored`);
           return oldState
         }
         return { ...oldState, [stateField]: newState }
@@ -4320,17 +4521,17 @@ class Component {
       lense = fieldLense;
     } else if (isObj(stateField)) {
       if (typeof stateField.get !== 'function') {
-        console.error(`Sub-component in ${ this.name } has an invalid 'state' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting sub-component state from the current state. Attempting to use parent component state.`);
+        console.error(`Sub-component in ${this.name} has an invalid 'state' field: Expecting 'undefined', a string indicating an array property in the state, or an object with 'get' and 'set' functions for retrieving and setting sub-component state from the current state. Attempting to use parent component state.`);
         lense = baseLense;
       } else {
         lense = { get: stateField.get, set: stateField.set };
       }
     } else {
-      console.error(`Invalid state provided to sub-component of ${ this.name }: Expecting string, object, or undefined, but found ${ typeof stateField }. Attempting to use parent component state.`);
+      console.error(`Invalid state provided to sub-component of ${this.name}: Expecting string, object, or undefined, but found ${typeof stateField}. Attempting to use parent component state.`);
       lense = baseLense;
     }
 
-    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$ };
+    const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$, __parentComponentNumber: this._componentNumber };
     const sink$   = isolate(factory, { [this.stateSourceName]: lense })(sources);
 
     if (!isObj(sink$)) {
@@ -4405,14 +4606,22 @@ class Component {
     const fixedMsg = (typeof msg === 'function') ? msg : _ => msg;
     if (immediate) {
       if (this.debug) {
-        console.log(`[${context}] ${fixedMsg(msg)}`);
+        const text = `[${context}] ${fixedMsg(msg)}`;
+        console.log(text);
+        if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+          window.__SYGNAL_DEVTOOLS__.onDebugLog(this._componentNumber, text);
+        }
       }
       return
     } else {
       return stream => {
         return stream.debug(msg => {
           if (this.debug) {
-            console.log(`[${context}] ${fixedMsg(msg)}`);
+            const text = `[${context}] ${fixedMsg(msg)}`;
+            console.log(text);
+            if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
+              window.__SYGNAL_DEVTOOLS__.onDebugLog(this._componentNumber, text);
+            }
           }
         })
       }
@@ -4422,11 +4631,11 @@ class Component {
 
 
 
-function getComponents(currentElement, componentNames, depth=0, index=0, parentId) {
+function getComponents(currentElement, componentNames, path='r', parentId) {
   if (!currentElement) return {}
 
   if (currentElement.data?.componentsProcessed) return {}
-  if (depth === 0) currentElement.data.componentsProcessed = true;
+  if (path === 'r') currentElement.data.componentsProcessed = true;
 
   const sel          = currentElement.sel;
   const isCollection = sel && sel.toLowerCase() === 'collection';
@@ -4440,11 +4649,11 @@ function getComponents(currentElement, componentNames, depth=0, index=0, parentI
   
   let id = parentId;
   if (isComponent) {
-    id  = getComponentIdFromElement(currentElement, depth, index, parentId);
+    id  = getComponentIdFromElement(currentElement, path, parentId);
     if (isCollection) {
       if (!props.of)   throw new Error(`Collection element missing required 'component' property`)
       if (typeof props.of !== 'string' && typeof props.of !== 'function')         throw new Error(`Invalid 'component' property of collection element: found ${ typeof props.of } requires string or component factory function`)
-      if (typeof props.of !== 'function' && !componentNames.includes(props.of))   throw new Error(`Specified component for collection not found: ${ props.of }`)
+      if (typeof props.of !== 'function' && !componentNames.includes(props.of))   throw new Error(`Specified component for collection not found: ${props.of}`)
       if (typeof props.from !== 'undefined' && !(typeof props.from === 'string' || Array.isArray(props.from) || typeof props.from.get === 'function')) console.warn(`No valid array found for collection ${ typeof props.of === 'string' ? props.of : 'function component' }: no collection components will be created`, props.from);
       currentElement.data.isCollection = true;
       currentElement.data.props ||= {};
@@ -4455,7 +4664,7 @@ function getComponents(currentElement, componentNames, depth=0, index=0, parentI
       if (!switchableComponents.every(comp => typeof comp === 'function')) throw new Error(`One or more components provided to switchable element is not a valid component factory`)
       if (!props.current || (typeof props.current !== 'string' && typeof props.current !== 'function')) throw new Error(`Missing or invalid 'current' property for switchable element: found '${ typeof props.current }' requires string or function`)
       const switchableComponentNames = Object.keys(props.of);
-      if (!switchableComponentNames.includes(props.current)) throw new Error(`Component '${ props.current }' not found in switchable element`)
+      if (!switchableComponentNames.includes(props.current)) throw new Error(`Component '${props.current}' not found in switchable element`)
       currentElement.data.isSwitchable = true;
     } else ;
     if (typeof props.key === 'undefined') currentElement.data.props.key = id;
@@ -4463,7 +4672,7 @@ function getComponents(currentElement, componentNames, depth=0, index=0, parentI
   }
 
   if (children.length > 0) {
-    children.map((child, i) => getComponents(child, componentNames, depth + 1, index + i, id))
+    children.map((child, i) => getComponents(child, componentNames, `${path}.${i}`, id))
             .forEach((child) => {
               Object.entries(child).forEach(([id, el]) => found[id] = el);
             });
@@ -4472,10 +4681,10 @@ function getComponents(currentElement, componentNames, depth=0, index=0, parentI
   return found
 }
 
-function injectComponents(currentElement, components, componentNames, depth=0, index=0, parentId) {
+function injectComponents(currentElement, components, componentNames, path='r', parentId) {
   if (!currentElement) return
   if (currentElement.data?.componentsInjected) return currentElement
-  if (depth === 0 && currentElement.data) currentElement.data.componentsInjected = true;
+  if (path === 'r' && currentElement.data) currentElement.data.componentsInjected = true;
 
 
   const sel          = currentElement.sel || 'NO SELECTOR';
@@ -4487,7 +4696,7 @@ function injectComponents(currentElement, components, componentNames, depth=0, i
 
   let id = parentId;
   if (isComponent) {
-    id  = getComponentIdFromElement(currentElement, depth, index, parentId);
+    id  = getComponentIdFromElement(currentElement, path, parentId);
     const component = components[id];
     if (isCollection) {
       currentElement.sel = 'div';
@@ -4499,21 +4708,20 @@ function injectComponents(currentElement, components, componentNames, depth=0, i
       return component
     }
   } else if (children.length > 0) {
-    currentElement.children = children.map((child, i) => injectComponents(child, components, componentNames, depth + 1, index + i, id)).flat();
+    currentElement.children = children.map((child, i) => injectComponents(child, components, componentNames, `${path}.${i}`, id)).flat();
     return currentElement
   } else {
     return currentElement
   }
 }
 
-function getComponentIdFromElement(el, depth, index, parentId) {
+function getComponentIdFromElement(el, path, parentId) {
   const sel    = el.sel;
   const name   = typeof sel === 'string' ? sel : 'functionComponent';
-  const uid    = `${depth}:${index}`;
   const props  = el.data?.props || {};
-  const id     = (props.id && JSON.stringify(props.id).replaceAll('"', '')) || uid;
-  const parentString = parentId ? `${ parentId }|` : '';
-  const fullId = `${ parentString }${ name }::${ id }`;
+  const id     = (props.id && JSON.stringify(props.id).replaceAll('"', '')) || path;
+  const parentString = parentId ? `${parentId}|` : '';
+  const fullId = `${parentString}${name}::${id}`;
   return fullId
 }
 
@@ -4657,12 +4865,264 @@ function sortFunctionFromProp(sortProp) {
   } else if (isObj(sortProp)) {
     return __sortFunctionFromObj(sortProp)
   } else {
-    console.error('Invalid sort option (ignoring):', item);
+    console.error('Invalid sort option (ignoring):', sortProp);
     return undefined
   }
 }
 
+const DEVTOOLS_SOURCE = '__SYGNAL_DEVTOOLS_PAGE__';
+const EXTENSION_SOURCE = '__SYGNAL_DEVTOOLS_EXTENSION__';
+const DEFAULT_MAX_HISTORY = 200;
+
+class SygnalDevTools {
+  constructor() {
+    this._connected = false;
+    this._components = new Map();
+    this._stateHistory = [];
+    this._maxHistory = DEFAULT_MAX_HISTORY;
+  }
+
+  get connected() {
+    return this._connected && typeof window !== 'undefined'
+  }
+
+  // ─── Initialization ─────────────────────────────────────────────────────────
+
+  init() {
+    if (typeof window === 'undefined') return
+
+    window.__SYGNAL_DEVTOOLS__ = this;
+
+    window.addEventListener('message', (event) => {
+      if (event.source !== window) return
+      if (event.data?.source === EXTENSION_SOURCE) {
+        this._handleExtensionMessage(event.data);
+      }
+    });
+  }
+
+  _handleExtensionMessage(msg) {
+    switch (msg.type) {
+      case 'CONNECT':
+        this._connected = true;
+        if (msg.payload?.maxHistory) this._maxHistory = msg.payload.maxHistory;
+        this._sendFullTree();
+        break
+      case 'DISCONNECT':
+        this._connected = false;
+        break
+      case 'SET_DEBUG':
+        this._setDebug(msg.payload);
+        break
+      case 'TIME_TRAVEL':
+        this._timeTravel(msg.payload);
+        break
+      case 'GET_STATE':
+        this._sendComponentState(msg.payload.componentId);
+        break
+    }
+  }
+
+  // ─── Hooks (called from component.js) ────────────────────────────────────────
+
+  onComponentCreated(componentNumber, name, instance) {
+    const meta = {
+      id: componentNumber,
+      name: name,
+      isSubComponent: instance.isSubComponent,
+      hasModel: !!instance.model,
+      hasIntent: !!instance.intent,
+      hasContext: !!instance.context,
+      hasCalculated: !!instance.calculated,
+      components: Object.keys(instance.components || {}),
+      parentId: null,
+      children: [],
+      debug: instance._debug,
+      createdAt: Date.now(),
+      _instanceRef: new WeakRef(instance),
+    };
+    this._components.set(componentNumber, meta);
+
+    if (!this.connected) return
+    this._post('COMPONENT_CREATED', this._serializeMeta(meta));
+  }
+
+  onStateChanged(componentNumber, name, state) {
+    if (!this.connected) return
+
+    const entry = {
+      componentId: componentNumber,
+      componentName: name,
+      timestamp: Date.now(),
+      state: this._safeClone(state),
+    };
+
+    this._stateHistory.push(entry);
+    if (this._stateHistory.length > this._maxHistory) {
+      this._stateHistory.shift();
+    }
+
+    this._post('STATE_CHANGED', {
+      componentId: componentNumber,
+      componentName: name,
+      state: entry.state,
+      historyIndex: this._stateHistory.length - 1,
+    });
+  }
+
+  onActionDispatched(componentNumber, name, actionType, data) {
+    if (!this.connected) return
+    this._post('ACTION_DISPATCHED', {
+      componentId: componentNumber,
+      componentName: name,
+      actionType: actionType,
+      data: this._safeClone(data),
+      timestamp: Date.now(),
+    });
+  }
+
+  onSubComponentRegistered(parentNumber, childNumber) {
+    const parent = this._components.get(parentNumber);
+    const child = this._components.get(childNumber);
+    if (parent && child) {
+      child.parentId = parentNumber;
+      if (!parent.children.includes(childNumber)) {
+        parent.children.push(childNumber);
+      }
+    }
+
+    if (!this.connected) return
+    this._post('TREE_UPDATED', {
+      parentId: parentNumber,
+      childId: childNumber,
+    });
+  }
+
+  onContextChanged(componentNumber, name, context) {
+    if (!this.connected) return
+    this._post('CONTEXT_CHANGED', {
+      componentId: componentNumber,
+      componentName: name,
+      context: this._safeClone(context),
+    });
+  }
+
+  onDebugLog(componentNumber, message) {
+    if (!this.connected) return
+    this._post('DEBUG_LOG', {
+      componentId: componentNumber,
+      message: message,
+      timestamp: Date.now(),
+    });
+  }
+
+  // ─── Commands (from extension to page) ───────────────────────────────────────
+
+  _setDebug({ componentId, enabled }) {
+    if (typeof componentId === 'undefined' || componentId === null) {
+      if (typeof window !== 'undefined') window.SYGNAL_DEBUG = enabled ? 'true' : false;
+      this._post('DEBUG_TOGGLED', { global: true, enabled });
+      return
+    }
+
+    const meta = this._components.get(componentId);
+    if (meta && meta._instanceRef) {
+      const instance = meta._instanceRef.deref();
+      if (instance) {
+        instance._debug = enabled;
+        meta.debug = enabled;
+        this._post('DEBUG_TOGGLED', { componentId, enabled });
+      }
+    }
+  }
+
+  _timeTravel({ historyIndex }) {
+    const entry = this._stateHistory[historyIndex];
+    if (!entry) return
+
+    const app = typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS_APP__;
+    if (app?.sinks?.STATE?.shamefullySendNext) {
+      app.sinks.STATE.shamefullySendNext(() => ({ ...entry.state }));
+      this._post('TIME_TRAVEL_APPLIED', {
+        historyIndex,
+        state: entry.state,
+      });
+    }
+  }
+
+  _sendComponentState(componentId) {
+    const meta = this._components.get(componentId);
+    if (meta && meta._instanceRef) {
+      const instance = meta._instanceRef.deref();
+      if (instance) {
+        this._post('COMPONENT_STATE', {
+          componentId,
+          state: this._safeClone(instance.currentState),
+          context: this._safeClone(instance.currentContext),
+          props: this._safeClone(instance.currentProps),
+        });
+      }
+    }
+  }
+
+  _sendFullTree() {
+    const tree = [];
+    for (const [id, meta] of this._components) {
+      const instance = meta._instanceRef?.deref();
+      tree.push({
+        ...this._serializeMeta(meta),
+        state: instance ? this._safeClone(instance.currentState) : null,
+        context: instance ? this._safeClone(instance.currentContext) : null,
+      });
+    }
+    this._post('FULL_TREE', {
+      components: tree,
+      history: this._stateHistory,
+    });
+  }
+
+  // ─── Transport ───────────────────────────────────────────────────────────────
+
+  _post(type, payload) {
+    if (typeof window === 'undefined') return
+    window.postMessage({
+      source: DEVTOOLS_SOURCE,
+      type,
+      payload,
+    }, '*');
+  }
+
+  _safeClone(obj) {
+    if (obj === undefined || obj === null) return obj
+    try {
+      return JSON.parse(JSON.stringify(obj))
+    } catch (e) {
+      return '[unserializable]'
+    }
+  }
+
+  _serializeMeta(meta) {
+    const { _instanceRef, ...rest } = meta;
+    return rest
+  }
+}
+
+// ─── Singleton ────────────────────────────────────────────────────────────────
+
+let instance = null;
+
+function getDevTools() {
+  if (!instance) instance = new SygnalDevTools();
+  return instance
+}
+
 function run(app, drivers={}, options={}) {
+  // Initialize DevTools instrumentation bridge early (before component creation)
+  if (typeof window !== 'undefined') {
+    const dt = getDevTools();
+    dt.init();
+  }
+
   const { mountPoint='#root', fragments=true, useDefaultDrivers=true } = options;
   if (!app.isSygnalComponent) {
     const name = app.name || app.componentName || app.label || "FUNCTIONAL_COMPONENT";
@@ -4712,6 +5172,11 @@ function run(app, drivers={}, options={}) {
 
   const exposed = { sources, sinks, dispose };
 
+  // Store app reference for time-travel
+  if (typeof window !== 'undefined') {
+    window.__SYGNAL_DEVTOOLS_APP__ = exposed;
+  }
+
   const swapToComponent = (newComponent, state) => {
     const persistedState = (typeof window !== 'undefined') ? window.__SYGNAL_HMR_PERSISTED_STATE : undefined;
     const fallbackState = typeof persistedState !== 'undefined' ? persistedState : app.initialState;