sygnal 5.3.7 → 5.4.0

package/src/component.ts

@@ -6,17 +6,12 @@ import {init as snabbdomInit} from './cycle/dom/snabbdom';
 import defaultModules from './cycle/dom/modules';
 import {makeCommandSource} from './extra/command';
 import type {Command} from './extra/command';
+// [diagnostics hook] shared diagnostics core — hooks are no-ops when diagnostics are off
+import * as diag from './extra/diagnostics/index';
+import {warn, error as logError, fail} from './extra/diagnostics/legacy';
 
-import xs, {Stream, resolveInteropDefault} from './extra/xstreamCompat';
-import * as delayModule from 'xstream/extra/delay.js';
-import * as concatModule from 'xstream/extra/concat.js';
-import * as debounceModule from 'xstream/extra/debounce.js';
-import * as dropRepeatsModule from 'xstream/extra/dropRepeats.js';
-
-const delay = resolveInteropDefault(delayModule);
-const concat = resolveInteropDefault(concatModule);
-const debounce = resolveInteropDefault(debounceModule);
-const dropRepeats = resolveInteropDefault(dropRepeatsModule);
+import xs, {Stream} from './extra/xstreamCompat';
+import {delay, concat, debounce, dropRepeats} from './extra/xstreamExtras';
 
 declare var process: { env: Record<string, any> };
 
@@ -31,8 +26,14 @@ const PARENT_SINK_NAME = 'PARENT';
 const CHILD_SOURCE_NAME = 'CHILD';
 const READY_SINK_NAME = 'READY';
 const EFFECT_SINK_NAME = 'EFFECT';
+// fix hint for coded messages that carry the caught error (printed after the text, or diagnostic.data)
+const ERR_FIX = 'See the attached error'
+// B-003: the state an action's non-STATE sinks see (stamped by initModel$)
+const STATE_SNAPSHOT = Symbol('sygnal.stateSnapshot');
 
 let COMPONENT_COUNT = 0;
+// 1H-1: STATE reducers emitted but not applied yet (in any component)
+let pendingReducers = 0;
 
 function wrapDOMSource(domSource: any): any {
   return new Proxy(domSource, {
@@ -68,9 +69,7 @@ function normalizeCalculatedEntry(field: string, entry: any): {fn: (...args: any
       && 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]`
-  )
+  fail('SYG206', undefined, `Invalid calculated field '${field}'`, 'Use fn or [deps, fn]')
 }
 
 export interface ComponentOptions {
@@ -100,7 +99,7 @@ export default function component(opts: ComponentOptions): any {
   const { name, sources, isolateOpts, stateSourceName='STATE' } = opts
 
   if (sources && !isObj(sources)) {
-    throw new Error(`[${name}] Sources must be a Cycle.js sources object`)
+    fail('SYG601', name, 'Invalid sources', 'Pass sources from run()')
   }
 
   let fixedIsolateOpts
@@ -197,15 +196,17 @@ class Component {
   _calculatedOrder: Array<[string, {fn: (...args: any[]) => any; deps: string[] | null}]> | null;
   _calculatedFieldCache: Record<string, {lastDepValues: any; lastResult: any}> | null;
   _subscriptions: any[];
+  _processedChildren$: any;
   _disposeListener: any;
   _dispose$: any;
+  _disposed?: boolean;
   _activeSubComponents: Map<string, any>;
   _childReadyState: Record<string, boolean>;
   _readyChanged$: any;
   _readyChangedListener: any;
 
   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}: ComponentOptions) {
-    if (!sources || !isObj(sources)) throw new Error(`[${name}] Missing or invalid sources`)
+    if (!sources || !isObj(sources)) fail('SYG601', name, 'Missing or invalid sources', 'Pass sources from run()')
 
     this._componentNumber = COMPONENT_COUNT++
 
@@ -235,10 +236,7 @@ class Component {
         && 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.`
-          )
+          warn('SYG207', name, `Calculated field '${key}' overwrites the initialState key of the same name`, 'Rename one of them')
         }
       }
     }
@@ -261,10 +259,7 @@ class Component {
           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`
-              )
+              warn('SYG208', name, `Calculated field '${field}' depends on unknown key '${dep}'`, 'Add it to initialState')
             }
           }
         }
@@ -328,7 +323,7 @@ class Component {
         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 ')}`)
+        fail('SYG209', name, `Circular calculated dependency: ${cycle.join(' \u2192 ')}`, 'Break the cycle')
       }
 
       this._calculatedOrder = sorted.map(f => [f, this._calculatedNormalized![f]])
@@ -378,17 +373,20 @@ class Component {
 
     const children$ = sources.children$
     if (children$) {
-      this.sources.children$ = children$.map((val: any) => {
+      // Process children and extract slots once, share across subscribers
+      this._processedChildren$ = children$.map((val: any) => {
         if (Array.isArray(val)) {
           const { slots, defaultChildren } = extractSlots(val)
           this.currentSlots = slots
           this.currentChildren = defaultChildren
+          return { children: defaultChildren, slots }
         } else {
           this.currentSlots = {}
           this.currentChildren = val
+          return { children: val, slots: {} }
         }
-        return val
       })
+      this.sources.children$ = this._processedChildren$.map((p: any) => p.children)
     }
 
     if (this.sources[DOMSourceName]) {
@@ -453,6 +451,10 @@ class Component {
   }
 
   dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    // [diagnostics hook]
+    diag.onDispose(this)
     if (typeof window !== 'undefined' && window.__SYGNAL_DEVTOOLS__?.connected) {
       window.__SYGNAL_DEVTOOLS__.onComponentDisposed(this._componentNumber, this.name)
     }
@@ -471,7 +473,11 @@ class Component {
       } catch (_) {}
       this._disposeListener = null
     }
-    // Tear down streams on next microtask to allow DISPOSE/cleanup actions to process
+    // Dispose the sub-components now (R3), so the whole subtree's DISPOSE actions and
+    // onDispose hooks run within this call (e.g. before renderComponent restores diagnostics)
+    this._activeSubComponents.forEach((entry) => entry?.sink$?.__dispose?.())
+    this._activeSubComponents.clear()
+    // Tear down streams on next macrotask to allow DISPOSE/cleanup actions to process
     setTimeout(() => {
       // Complete the action$ stream to stop the entire component cycle
       if (this.action$ && typeof this.action$.shamefullySendComplete === 'function') {
@@ -488,11 +494,6 @@ class Component {
         }
       }
       this._subscriptions = []
-      // Dispose any active sub-components
-      this._activeSubComponents.forEach((entry) => {
-        if (entry?.sink$?.__dispose) entry.sink$.__dispose()
-      })
-      this._activeSubComponents.clear()
     }, 0)
   }
 
@@ -502,17 +503,22 @@ class Component {
 
   initIntent$(): void {
     if (!this.intent) {
+      // [diagnostics hook]
+      diag.onIntent(this, [], undefined)
       return
     }
     if (typeof this.intent != 'function') {
-      throw new Error(`[${this.name}] Intent must be a function`)
+      fail('SYG602', this, 'intent must be a function', 'Use intent = sources => ({ ACTION: stream$ })')
     }
 
     this.intent$ = this.intent(this.sources)
 
     if (!(this.intent$ instanceof Stream) && (!isObj(this.intent$))) {
-      throw new Error(`[${this.name}] Intent must return either an action$ stream or map of event streams`)
+      fail('SYG603', this, 'intent must return a stream or an object of streams', 'Return { ACTION: stream$ }')
     }
+
+    // [diagnostics hook] TODO(1A): selectorsUsed via MainDOMSource.select instrumentation
+    diag.onIntent(this, this.intent$ instanceof Stream ? [] : Object.keys(this.intent$), undefined)
   }
 
   initHmrActions(): void {
@@ -523,11 +529,8 @@ class Component {
     if (typeof this.hmrActions === 'string') {
       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`)
-    }
-    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`)
+    if (!Array.isArray(this.hmrActions) || this.hmrActions.some(action => typeof action !== 'string')) {
+      fail('SYG604', this, 'hmrActions must be an action name or an array of action names', "Use hmrActions = ['ACTION']")
     }
     this.hmrAction$ = xs.fromArray(this.hmrActions.map(action => ({ type: action })))
   }
@@ -547,12 +550,12 @@ class Component {
       // Validate that no intent action names contain '|' (reserved for model shorthand)
       for (const key of Object.keys(this.intent$)) {
         if (key.includes('|')) {
-          throw new Error(`[${this.name}] Intent action name '${key}' contains '|', which is reserved for the model shorthand syntax (e.g., 'ACTION | DRIVER'). Rename this action.`)
+          fail('SYG605', this, `Intent action '${key}' contains '|', which is reserved for model shorthand`, 'Rename the action')
         }
       }
       const mapped = Object.entries(this.intent$)
                            .map(([type, data$]: [string, any]) => data$.map((data: any) => ({type, data})))
-      runner = xs.merge(xs.never(), ...mapped)
+      runner = mapped.length > 0 ? xs.merge(...mapped) : xs.never()
     }
 
     const action$    = ((runner instanceof Stream) ? runner : (runner.apply && runner(this.sources) || xs.never()))
@@ -593,7 +596,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}`)
+            warn('SYG210', this, `${INITIALIZE_ACTION} only supports the ${this.stateSourceName} sink; ignoring '${name}'`, 'Use another action')
             delete this.model[INITIALIZE_ACTION][name]
           }
         })
@@ -610,7 +613,7 @@ class Component {
     const state$ = this.sources[this.stateSourceName]?.stream.startWith({}).compose(dropRepeats(objIsEqual)) || xs.never()
     const parentContext$ = this.sources.__parentContext$?.startWith({}).compose(dropRepeats(objIsEqual)) || xs.of({})
     if (this.context && !isObj(this.context)) {
-      console.error(`[${this.name}] Context must be an object mapping names to values of functions: ignoring provided ${ typeof this.context }`)
+      logError('SYG402', this, `context must be an object, got ${typeof this.context}; ignoring it`, 'Use context = { name: state => value }')
     }
     this.context$ = xs.combine(state$, parentContext$)
       .map(([_, parent]: [any, any]) => {
@@ -628,7 +631,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`)
+            logError('SYG403', this, `Invalid context entry '${name}'; skipping it`, 'Use a state key or state => value')
             return acc
           }
           acc[name] = _value
@@ -643,7 +646,7 @@ class Component {
       })
       .compose(dropRepeats(objIsEqual))
       .startWith({})
-    this._subscriptions.push(this.context$.subscribe({ next: (_: any) => _, error: (err: any) => console.error(`[${this.name}] Error in context stream:`, err) }))
+    this._subscriptions.push(this.context$.subscribe({ next: (_: any) => _, error: (err: any) => logError('SYG404', this, 'Context stream errored; context stops updating', 'Check the context functions', err) }))
   }
 
   initModel$(): void {
@@ -652,6 +655,8 @@ class Component {
         a[s] = xs.never()
         return a
       }, {} as Record<string, any>)
+      // [diagnostics hook]
+      diag.onModel(this, {})
       return
     }
 
@@ -659,19 +664,39 @@ class Component {
     const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState
     const initial  = { type: INITIALIZE_ACTION, data: effectiveInitialState }
     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.`)
+      warn('SYG405', this, 'Sub-component initialState replaces the state its parent passes in', 'Remove initialState, or set isolatedState = true')
     }
     const hasInitialState = (typeof effectiveInitialState !== 'undefined')
     const shouldInjectInitialState = hasInitialState && (ENVIRONMENT?.__SYGNAL_HMR_UPDATING !== true || typeof hmrState !== 'undefined')
-    const shimmed$ = shouldInjectInitialState ? concat(xs.of(initial), this.action$).compose(delay(0)) : this.action$
-    const onState  = () => this.makeOnAction(shimmed$, true, this.action$)
-    const onNormal = () => this.makeOnAction(this.action$, false, this.action$)
+    // Only INITIALIZE is delayed (user actions start >= 1ms later), so the other actions, and
+    // their non-STATE sinks, stay synchronous with the event that caused them (1H-1).
+    const shimmed$ = shouldInjectInitialState ? xs.merge(xs.of(initial).compose(delay(0)), this.action$) : this.action$
+    // B-003: STATE reducers are applied later (withState queues each one in a microtask), so
+    // while one is pending a non-STATE sink must not read this.currentState. Then, before the
+    // action reaches any reducer, queue a microtask (ahead of this action's own STATE reducer,
+    // behind every earlier one) that snapshots the state and runs the non-STATE sinks.
+    // Otherwise run them now, so EFFECT can still preventDefault() the live event (1H-1).
+    let snapListener: any = null
+    const sequenced$ = shimmed$.map((action: any) => {
+      const l = snapListener
+      const run = () => l.next({ ...action, [STATE_SNAPSHOT]: this.currentState })
+      if (l) pendingReducers ? queueMicrotask(run) : run()
+      return action
+    })
+    let snapSub: any
+    const snapshotted$ = xs.create({
+      start: (l: any) => { snapListener = l; snapSub = sequenced$.subscribe({}) },
+      stop: () => { snapListener = null; snapSub?.unsubscribe() },
+    })
+    const onState  = () => this.makeOnAction(sequenced$, true, this.action$)
+    const onNormal = () => this.makeOnAction(snapshotted$, false, this.action$)
 
 
     const modelEntries = Object.entries(this.model)
 
     const reducers: Record<string, any[]> = {}
     const seenActionSinks = new Set<string>()
+    const modelMap: Record<string, string[]> = {}  // [diagnostics hook]
 
     modelEntries.forEach((entry) => {
       let [action, sinks]: [string, any] = entry
@@ -680,7 +705,7 @@ class Component {
       if (action.includes('|')) {
         const parts = action.split('|').map((s: string) => s.trim())
         if (parts.length !== 2 || !parts[0] || !parts[1]) {
-          throw new Error(`[${this.name}] Invalid shorthand model entry '${action}'. Expected 'ACTION | DRIVER' format.`)
+          fail('SYG211', this, `Invalid shorthand model entry '${action}'`, "Use 'ACTION | SINK'")
         }
         action = parts[0]
         sinks = { [parts[1]]: sinks }
@@ -691,7 +716,7 @@ class Component {
       }
 
       if (!isObj(sinks)) {
-        throw new Error(`[${this.name}] Entry for each action must be an object: ${action}`)
+        fail('SYG212', this, `Model entry '${action}' must be a function or an object`, 'Use { STATE: reducer }')
       }
 
       const sinkEntries = Object.entries(sinks)
@@ -701,13 +726,14 @@ class Component {
 
         const actionSinkKey = `${action}::${sink}`
         if (seenActionSinks.has(actionSinkKey)) {
-          console.warn(`[${this.name}] Duplicate model entry for action '${action}' on sink '${sink}'. Only the last definition will take effect.`)
+          warn('SYG213', this, `Duplicate model entry for action '${action}' on sink '${sink}'; both run`, 'Remove the duplicate')
         }
         seenActionSinks.add(actionSinkKey)
+        ;(modelMap[action] ||= []).push(sink)  // [diagnostics hook]
 
         // EFFECT sink: run the reducer for side effects only, no state change or sink output
         if (sink === EFFECT_SINK_NAME) {
-          const effect$ = this.makeEffectHandler(this.action$, action, reducer)
+          const effect$ = this.makeEffectHandler(snapshotted$, action, reducer, this.action$)
           if (Array.isArray(reducers[sink])) {
             reducers[sink].push(effect$)
           } else {
@@ -744,11 +770,14 @@ class Component {
 
     const model$ = Object.entries(reducers).reduce((acc: Record<string, any>, entry: [string, any]) => {
       const [sink, streams] = entry
-      acc[sink] = xs.merge(xs.never(), ...streams)
+      acc[sink] = streams.length === 1 ? streams[0] : xs.merge(...streams)
       return acc
     }, {} as Record<string, any>)
 
     this.model$ = model$
+
+    // [diagnostics hook]
+    diag.onModel(this, modelMap)
   }
 
   initPeers$(): void {
@@ -812,7 +841,7 @@ class Component {
 
       }
     })
-    this._subscriptions.push(subComponentSink$.subscribe({ next: (_: any) => _, error: (err: any) => console.error(`[${this.name}] Error in sub-component sink stream:`, err) }))
+    this._subscriptions.push(subComponentSink$.subscribe({ next: (_: any) => _, error: (err: any) => logError('SYG901', this, 'Sub-component sink stream errored', ERR_FIX, err) }))
     this.subComponentSink$ = subComponentSink$.filter((sinks: any) => Object.keys(sinks).length > 0)
   }
 
@@ -844,23 +873,23 @@ class Component {
           return this.view({ ...sanitizedProps, state, children, slots: slots || {}, context, peers }, state, context, peers)
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err))
-          console.error(`[${this.name}] Error in view:`, error)
+          // B-022: an error handled by .onError is a warning, without the "add .onError" hint
           if (typeof this.onError === 'function') {
             try {
-              return this.onError(error, { componentName: this.name })
+              const fallback = this.onError(error, { componentName: this.name })
+              warn('SYG406', this, 'View threw; rendered the onError fallback', undefined, error)
+              return fallback
             } catch (fallbackErr) {
-              console.error(`[${this.name}] Error in onError handler:`, fallbackErr)
+              logError('SYG406', this, 'View threw; rendering the error fallback', undefined, error)
+              logError('SYG407', this, 'onError threw; rendering an empty error <div>', 'Make onError return a vnode', fallbackErr)
             }
-          }
+          } else logError('SYG406', this, 'View threw; rendering the error fallback', 'Add .onError for a custom fallback', error)
           return { sel: 'div', data: { attrs: { 'data-sygnal-error': this.name } }, children: [] }
         }
       })
       .compose(this.log('View rendered'))
       .map((vDom: any) => vDom || { sel: 'div', data: {}, children: [] })
-      .map((vdom: any) => processLazy(vdom, this))
-      .map(processPortals)
-      .map(processTransitions)
-      .map(processClientOnly)
+      .map((vdom: any) => preprocessVdom(vdom, this))
       .compose(this.instantiateSubComponents.bind(this))
       .filter((val: any) => val !== undefined)
       .compose(this.renderVdom.bind(this))
@@ -868,6 +897,15 @@ class Component {
   }
 
   initSinks(): void {
+    // Stamp this component's own EVENTS emissions with its info for devtools, before they are
+    // merged with the sub-components' (B-023: stamping the merged sink made every ancestor
+    // re-stamp, so the emitter was always the root). Non-enumerable (G-020), so sink values
+    // still toEqual what the model returned.
+    const ev$ = this.model$.EVENTS
+    if (ev$) this.model$.EVENTS = ev$.map((ev: any) => Object.defineProperties({...ev}, {
+      __emitterId: { value: this._componentNumber, configurable: true },
+      __emitterName: { value: this.name, configurable: true },
+    }))
     this.sinks = this.sourceNames.reduce((acc: Record<string, any>, name) => {
       if (name == this.DOMSourceName) return acc
       const subComponentSink$ = (this.subComponentSink$ && name !== PARENT_SINK_NAME) ? this.subComponentSink$.map((sinks: any) => sinks[name]).filter((sink: any) => !!sink).flatten() : xs.never()
@@ -876,12 +914,6 @@ 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>)
 
@@ -892,7 +924,7 @@ class Component {
     if (this.model$[EFFECT_SINK_NAME]) {
       const effectSub = this.model$[EFFECT_SINK_NAME].subscribe({
         next: () => {},
-        error: (err: any) => console.error(`[${this.name}] Uncaught error in EFFECT stream:`, err),
+        error: (err: any) => logError('SYG902', this, 'EFFECT stream errored; effects stop running', ERR_FIX, err),
       })
       this._subscriptions.push(effectSub)
       delete this.sinks[EFFECT_SINK_NAME]
@@ -922,7 +954,7 @@ class Component {
       if (typeof reducer === 'function') {
         returnStream$ = filtered$.map((action: any) => {
           const next = (type: any, data: any, 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') fail('SYG215', this, `next() delay in '${name}' must be a number`, "Use next('ACTION', data, 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
@@ -935,33 +967,50 @@ class Component {
 
           let data = action.data
           if (isStateSink) {
+            // withState applies reducers in microtasks, so none is legitimately pending at the
+            // next macrotask: reset then, in case one was never applied (e.g. app disposed)
+            if (!pendingReducers++) setTimeout(() => { pendingReducers = 0 })
+            let applied = false
             return (state: any) => {
-              const _state = this.isSubComponent ? this.currentState : state
+              if (!applied && pendingReducers) { applied = true; pendingReducers-- }
+              // Reduce from the fresh argument, not currentState (B-013, 1H-3): below a
+              // Collection, currentState lags behind instantiateCollection's debounce, so a
+              // second same-tick action would start from the pre-update state. The parents'
+              // lenses add their calculated fields, so it matches what the view gets.
+              const fresh = typeof state !== 'undefined'
+              const _state = this.isSubComponent && !fresh ? this.currentState : state
               try {
                 const enhancedState = this.addCalculated(_state)
                 props.state = enhancedState
                 const newState = reducer(enhancedState, data, next, props)
                 if (isAbort(newState)) return _state
-                return this.cleanupCalculated(newState)
+                // [diagnostics hook]
+                diag.onReducer(this, name, _state, newState, this.stateSourceName)
+                const result = this.cleanupCalculated(newState)
+                // B-013: later same-tick actions' non-STATE sinks snapshot currentState (B-003)
+                if (fresh) this.currentState = result
+                return result
               } catch (err) {
-                console.error(`[${this.name}] Error in model reducer '${name}':`, err)
+                logError('SYG216', this, `Reducer for '${name}' threw; state unchanged`, ERR_FIX, err)
                 return _state
               }
             }
           } else {
             try {
-              const enhancedState = this.addCalculated(this.currentState)
+              const enhancedState = this.addCalculated(STATE_SNAPSHOT in action ? action[STATE_SNAPSHOT] : this.currentState)
               props.state = enhancedState
               const reduced = reducer(enhancedState, data, next, props)
+              // B-029: ABORT = send nothing (filtered below), before the type checks
+              if (isAbort(reduced)) return reduced
               const type = typeof reduced
               if (isObj(reduced) || ['string', 'number', 'boolean', 'function'].includes(type)) return reduced
               if (type === 'undefined') {
-                console.warn(`[${this.name}] 'undefined' value sent to ${name}`)
+                warn('SYG217', this, `Reducer for '${name}' sent undefined to the driver`, 'Return a value, or ABORT to send nothing')
                 return reduced
               }
-              throw new Error(`[${this.name}] Invalid reducer type for action '${name}': ${type}`)
+              fail('SYG218', this, `Reducer for '${name}' returned a ${type}`, 'Return a value, or ABORT to send nothing')
             } catch (err) {
-              console.error(`[${this.name}] Error in model reducer '${name}':`, err)
+              logError('SYG216', this, `Reducer for '${name}' threw; nothing sent`, ERR_FIX, err)
               return ABORT
             }
           }
@@ -977,28 +1026,28 @@ class Component {
     }
   }
 
-  makeEffectHandler(action$: any, name: string, reducer: any): any {
+  makeEffectHandler(action$: any, name: string, reducer: any, rootAction$: any = action$): any {
     const filtered$ = action$.filter(({type}: any) => type == name)
 
     return filtered$.map((action: any) => {
       if (typeof reducer === 'function') {
         const next = (type: any, data: any, delay=10) => {
-          if (typeof delay !== 'number') throw new Error(`[${this.name}] Invalid delay value provided to next() function in EFFECT handler '${name}'. Must be a number in ms.`)
+          if (typeof delay !== 'number') fail('SYG215', this, `next() delay in '${name}' must be a number`, "Use next('ACTION', data, ms)")
           setTimeout(() => {
-            action$.shamefullySendNext({ type, data })
+            rootAction$.shamefullySendNext({ type, data })
           }, delay)
           this.log(`<${name}> EFFECT triggered a next() action: <${type}> ${delay}ms delay`, true)
         }
 
         try {
-          const enhancedState = this.addCalculated(this.currentState)
+          const enhancedState = this.addCalculated(STATE_SNAPSHOT in action ? action[STATE_SNAPSHOT] : this.currentState)
           const props = { ...this.currentProps, children: this.currentChildren, slots: this.currentSlots || {}, context: this.currentContext, state: enhancedState }
           const result = reducer(enhancedState, action.data, next, props)
-          if (result !== undefined) {
-            console.warn(`[${this.name}] EFFECT handler '${name}' returned a value. EFFECT handlers are for side effects only — return values are ignored.`)
+          if (result !== undefined && !isAbort(result)) {
+            warn('SYG219', this, `EFFECT handler '${name}' returned a value, which is ignored`, 'Use a STATE or driver sink')
           }
         } catch (err) {
-          console.error(`[${this.name}] Error in EFFECT handler '${name}':`, err)
+          logError('SYG214', this, `EFFECT handler '${name}' threw`, ERR_FIX, err)
         }
       }
       return null
@@ -1014,7 +1063,7 @@ class Component {
       if (state === lastState) {
         return lastResult
       }
-      if (!isObj(this.calculated)) throw new Error(`[${this.name}] 'calculated' parameter must be an object mapping calculated state field names to functions`)
+      if (!isObj(this.calculated)) fail('SYG606', this, 'calculated must be an object', 'Use calculated = { field: state => value }')
 
       const calculated = this.getCalculatedValues(state)
       if (!calculated) {
@@ -1067,7 +1116,7 @@ class Component {
           computedSoFar[field] = result
           mergedState[field] = result
         } catch (e: unknown) {
-          console.warn(`Calculated field '${field}' threw an error during calculation: ${e instanceof Error ? e.message : e}`)
+          warn('SYG220', this, `Calculated field '${field}' threw (${e instanceof Error ? e.message : e}); skipped this update`, 'Guard against missing data')
         }
       } else {
         // No deps declared — always recompute
@@ -1076,7 +1125,7 @@ class Component {
           computedSoFar[field] = result
           mergedState[field] = result
         } catch (e: unknown) {
-          console.warn(`Calculated field '${field}' threw an error during calculation: ${e instanceof Error ? e.message : e}`)
+          warn('SYG220', this, `Calculated field '${field}' threw (${e instanceof Error ? e.message : e}); skipped this update`, 'Guard against missing data')
         }
       }
     }
@@ -1114,14 +1163,9 @@ class Component {
       renderParams.props = this.sources.props$.compose(dropRepeats(propsIsEqual))
     }
 
-    if (this.sources.children$) {
-      const processedChildren$ = this.sources.children$.map((val: any) => {
-        if (!Array.isArray(val)) return { children: val, slots: {} }
-        const { slots, defaultChildren } = extractSlots(val)
-        return { children: defaultChildren, slots }
-      })
-      renderParams.children = processedChildren$.map((p: any) => p.children).compose(dropRepeats(objIsEqual))
-      renderParams.slots = processedChildren$.map((p: any) => p.slots).compose(dropRepeats(objIsEqual))
+    if (this._processedChildren$) {
+      renderParams.children = this._processedChildren$.map((p: any) => p.children).compose(dropRepeats(objIsEqual))
+      renderParams.slots = this._processedChildren$.map((p: any) => p.slots).compose(dropRepeats(objIsEqual))
     }
 
     if (this.context$) {
@@ -1155,9 +1199,11 @@ class Component {
   }
 
   instantiateSubComponents(vDom$: any): any {
+    // Build the component name Set once outside the fold — avoids rebuilding per render
+    const componentNameSet = new Set(['collection', 'switchable', 'sygnal-factory', ...Object.keys(this.components)])
+
     return vDom$.fold((previousComponents: any, vDom: any) => {
-      const componentNames  = Object.keys(this.components)
-      const foundComponents = getComponents(vDom, componentNames)
+      const foundComponents = getComponents(vDom, componentNameSet)
       const entries         = Object.entries(foundComponents)
 
       const rootEntry: Record<string, any> = { '::ROOT::': vDom }
@@ -1178,7 +1224,8 @@ class Component {
       const newComponents =  entries.reduce((acc, [id, el]) => {
         const data     = el.data
         const props    = data.props  || {}
-        const children = el.children || []
+        // a string-tag component with a single text child is a text-only vnode (B-011)
+        const children = el.children || (el.text != null ? [{ text: el.text }] : [])
 
         const isCollection = data.isCollection || false
         const isSwitchable = data.isSwitchable || false
@@ -1224,13 +1271,13 @@ class Component {
           sink$ = instantiator(el, props$, children$)
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err))
-          console.error(`[${this.name}] Error instantiating sub-component:`, error)
+          logError('SYG408', this, 'Sub-component threw; rendering the error fallback', ERR_FIX, error)
           let fallbackVNode = { sel: 'div', data: { attrs: { 'data-sygnal-error': this.name } }, children: [] }
           if (typeof this.onError === 'function') {
             try {
               fallbackVNode = this.onError(error, { componentName: this.name }) || fallbackVNode
             } catch (fallbackErr) {
-              console.error(`[${this.name}] Error in onError handler:`, fallbackErr)
+              logError('SYG407', this, 'onError threw; rendering an empty error <div>', 'Make onError return a vnode', fallbackErr)
             }
           }
           sink$ = { [this.DOMSourceName]: xs.of(fallbackVNode) }
@@ -1273,16 +1320,52 @@ class Component {
   }
 
   makeCoordinatedSubComponentDomSink(domSink$: any): any {
-    const remembered$   = domSink$.remember()
-
-    const coordinated = this.sources[this.stateSourceName].stream
-      .compose(dropRepeats(objIsEqual))
-      .map((state: any) => remembered$)
-      .flatten()
+    return domSink$
       .debug((_: any) => this.triggerSubComponentsRendered())
       .remember()
+  }
 
-    return coordinated
+  // A child's reducers get their state through its lens from this component's raw reducer
+  // state; adding the calculated fields here gives them what the child's view gets (1H-3).
+  withCalculated(lense: any): any {
+    return this.calculated ? { get: (state: any) => lense.get(isObj(state) ? this.addCalculated(state) : state), set: lense.set } : lense
+  }
+
+  createSubComponentLense(stateField: any, componentType: string, defaultState?: any): any {
+    const baseLense = {
+      get: (state: any) => state,
+      set: (_oldState: any, newState: any) => newState
+    }
+
+    if (typeof stateField === 'undefined') return baseLense
+
+    if (typeof stateField === 'string') {
+      return {
+        get: (state: any) => {
+          const slice = state[stateField]
+          if (typeof slice === 'undefined' && defaultState) return defaultState
+          return slice
+        },
+        set: (oldState: any, newState: any) => {
+          if (this.calculated && stateField in this.calculated) {
+            warn('SYG409', this, `${componentType} tried to update calculated field '${stateField}'; ignored`, 'Bind it to a non-calculated field')
+            return oldState
+          }
+          return { ...oldState, [stateField]: newState }
+        }
+      }
+    }
+
+    if (isObj(stateField)) {
+      if (typeof stateField.get !== 'function') {
+        logError('SYG410', this, `${componentType} 'state' prop has no get(); it gets the parent's whole state`, 'Use a state key string or { get, set }')
+        return baseLense
+      }
+      return { get: stateField.get, set: stateField.set }
+    }
+
+    logError('SYG410', this, `${componentType} 'state' prop is a ${typeof stateField}; it gets the parent's whole state`, 'Use a state key string or { get, set }')
+    return baseLense
   }
 
   instantiateCollection(el: any, props$: any, children$: any): any {
@@ -1307,8 +1390,8 @@ class Component {
         if (props.sort !== arrayOperators.sort) {
           arrayOperators.sort = sortFunctionFromProp(props.sort)
         }
-        
-        return isObj(state) ? this.addCalculated(state) : state
+        // calculated fields are added by the lens (B-013)
+        return state
       })
 
     const stateSource  = new StateSource(state$, this.stateSourceName)
@@ -1332,7 +1415,7 @@ class Component {
     } else if (this.components[collectionOf]) {
       factory = this.components[collectionOf]
     } else {
-      throw new Error(`[${this.name}] Invalid 'of' property in collection: ${collectionOf}`)
+      fail('SYG411', this, `Collection 'of' is not a component: ${collectionOf}`, 'Use of={ItemComponent}')
     }
 
     const fieldLense = {
@@ -1349,7 +1432,7 @@ class Component {
       },
       set: (oldState: any, newState: any) => {
         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`)
+          warn('SYG409', this, `Collection tried to update calculated field '${stateField}'; ignored`, 'Bind it to a non-calculated field')
           return oldState
         }
         const updated = []
@@ -1378,17 +1461,18 @@ 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.`)
+          const arrayFields = Object.keys(this.currentState).filter(k => Array.isArray(this.currentState[k]))
+          logError('SYG401', this, `Collection from="${stateField}" is not in state${arrayFields.length ? ` (array fields: '${arrayFields.join("', '")}')` : ''}; it renders nothing`, 'Set it to an array in initialState')
           lense = undefined
         } else if (!Array.isArray(this.currentState[stateField])) {
-          console.warn(`[${this.name}] State property '${stateField}' in collection component is not an array: No components will be instantiated in the collection.`)
+          warn('SYG401', this, `Collection 'from' field '${stateField}' is not an array; it renders nothing`, 'Set it to an array in initialState')
           lense = fieldLense
         } else {
           lense = fieldLense
         }
       } else {
         if (!Array.isArray(this.currentState[stateField])) {
-          console.warn(`[${this.name}] State property '${stateField}' in collection component is not an array: No components will be instantiated in the collection.`)
+          warn('SYG401', this, `Collection 'from' field '${stateField}' is not an array; it renders nothing`, 'Set it to an array in initialState')
           lense = fieldLense
         } else {
           lense = fieldLense
@@ -1396,14 +1480,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.`)
+        logError('SYG412', this, "Collection 'from' prop is invalid; it renders nothing", 'Use a state key string or { get, set }', stateField)
         lense = undefined
       } else {
         lense = {
           get: (state: any) => {
             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)
+              warn('SYG401', this, "Collection 'from' getter returned a non-array; it renders nothing", 'Return an array from get()', newState)
               return []
             }
             return newState
@@ -1412,10 +1496,15 @@ 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.`)
+      logError('SYG412', this, "Collection 'from' prop is invalid; it renders nothing", 'Use a state key string or { get, set }', stateField)
       lense = undefined
     }
 
+    // B-013: add this component's calculated fields inside the lens, not on state$, so the
+    // items' reducers (which read through the lens from the raw state) see the same item
+    // array as their views, e.g. for from={calculatedField} or a custom get().
+    if (lense) lense = this.withCalculated(lense)
+
     // Strip collection-specific props and forward only user-defined extra props to each item
     const collectionKeys = ['of', 'from', 'filter', 'sort', 'idfield', 'className']
     const itemProps$ = props$.map((p: any) => {
@@ -1430,7 +1519,7 @@ class Component {
     const sources = { ...this.sources, [this.stateSourceName]: stateSource, props$: itemProps$, children$, __parentContext$: this.context$, PARENT: null, __parentComponentNumber: this._componentNumber }
     const sink$   = collection(factory, lense as any, { container: null as any })(sources)
     if (!isObj(sink$)) {
-      throw new Error(`[${this.name}] Invalid sinks returned from component factory of collection element`)
+      fail('SYG903', this, 'Collection factory returned invalid sinks', 'Return a sinks object')
     }
 
     // Notify devtools of collection mount
@@ -1458,40 +1547,7 @@ class Component {
 
     const stateSource = new StateSource(state$, this.stateSourceName)
     const stateField  = props.state
-    let lense
-
-    const fieldLense = {
-      get: (state: any) => state[stateField],
-      set: (oldState: any, newState: any) => {
-        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`)
-          return oldState
-        }
-        if (!isObj(newState) || Array.isArray(newState)) return { ...oldState, [stateField]: newState }
-        return { ...oldState, [stateField]: newState }
-      }
-    }
-
-    const baseLense = {
-      get: (state: any) => state,
-      set: (oldState: any, newState: any) => newState
-    }
-
-    if (typeof stateField === 'undefined') {
-      lense = baseLense
-    } else if (typeof stateField === 'string') {
-      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.`)
-        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.`)
-      lense = baseLense
-    }
+    const lense = this.withCalculated(this.createSubComponentLense(stateField, 'Switchable sub-component'))
 
     const switchableComponents = props.of
     const keys = Object.keys(switchableComponents)
@@ -1510,7 +1566,7 @@ class Component {
     const sink$ = isolate(switchable(switchableComponents, props$.map((props: any) => props.current), ''), { [this.stateSourceName]: lense })(sources)
 
     if (!isObj(sink$)) {
-      throw new Error(`[${this.name}] Invalid sinks returned from component factory of switchable element`)
+      fail('SYG903', this, 'Switchable factory returned invalid sinks', 'Return a sinks object')
     }
 
     return sink$
@@ -1526,7 +1582,7 @@ class Component {
         return isObj(state) ? this.addCalculated(state) : state
       })
 
-    const stateSource = new StateSource(state$, this.stateSourceName)
+    let stateSource = new StateSource(state$, this.stateSourceName)
     const stateField  = props.state
 
     if (typeof props.sygnalFactory !== 'function' && isObj(props.sygnalOptions)) {
@@ -1535,8 +1591,8 @@ 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}`)
+      if (componentName === 'sygnal-factory') fail('SYG413', this, 'Unnamed component has no factory', 'Name the function, or set Comp.componentName')
+      fail('SYG414', this, `Component '${componentName}' not found`, 'Import it, or add it to .components')
     }
 
     // Guard against sub-components accidentally overwriting parent state with .initialState
@@ -1544,52 +1600,24 @@ class Component {
     const subIsolatedState = props.sygnalOptions?.isolatedState
     if (subInitialState && !subIsolatedState) {
       const subName = props.sygnalOptions?.name || componentName
-      throw new Error(
-        `[${subName}] Sub-component has .initialState but no .isolatedState = true. ` +
-        `This will overwrite parent state. If this is intentional, add .isolatedState = true to the component.`
-      )
+      fail('SYG405', subName, 'Sub-component initialState replaces the state its parent passes in', 'Remove initialState, or set isolatedState = true')
     }
 
-    let lense
-
     const subInitState = subIsolatedState ? subInitialState : undefined
-    const fieldLense = {
-      get: (state: any) => {
-        const slice = state[stateField]
-        if (typeof slice === 'undefined' && subInitState) return subInitState
-        return slice
-      },
-      set: (oldState: any, newState: any) => {
-        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`)
-          return oldState
-        }
-        return { ...oldState, [stateField]: newState }
-      }
-    }
-
-    const baseLense = {
-      get: (state: any) => state,
-      set: (oldState: any, newState: any) => newState
-    }
-
-    if (typeof stateField === 'undefined') {
-      lense = baseLense
-    } else if (typeof stateField === 'string') {
-      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.`)
-        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.`)
-      lense = baseLense
+    let lense = this.createSubComponentLense(stateField, 'Sub-component', subInitState)
+    // B-008: isolatedState without a `state` prop = state local to this instance; the
+    // parent's state is never replaced. It's kept off the parent's state stream (1H-9): the
+    // child's reducers are applied below and feed its own state source, so a child write
+    // doesn't produce a new parent state. Until the child first writes (INITIALIZE; never,
+    // without a model) it reads the parent's state, as before.
+    let local: any, local$: any
+    if (subIsolatedState && typeof stateField === 'undefined') {
+      local$ = xs.create()
+      stateSource = new StateSource(xs.merge(state$.filter(() => local === undefined), local$), this.stateSourceName)
     }
 
     const sources: Record<string, any> = { ...this.sources, [this.stateSourceName]: stateSource, props$, children$, __parentContext$: this.context$, __parentComponentNumber: this._componentNumber }
+    lense = local$ ? null : this.withCalculated(lense)
 
     // Detect Command objects in props and expose as commands$ source
     for (const key of Object.keys(props)) {
@@ -1605,18 +1633,24 @@ class Component {
 
     if (!isObj(sink$)) {
       const name = componentName === 'sygnal-factory' ? 'custom element' : componentName
-      throw new Error(`Invalid sinks returned from component factory: ${name}`)
+      fail('SYG903', this, `Factory for ${name} returned invalid sinks`, 'Return a sinks object')
+    }
+    if (local$ && sink$[this.stateSourceName]) {
+      sink$[this.stateSourceName] = sink$[this.stateSourceName]
+        .map((reducer: any) => local$.shamefullySendNext(local = reducer(local === undefined ? this.addCalculated(this.currentState) : local)))
+        .filter(() => false)
     }
 
     return sink$
   }
 
   renderVdom(componentInstances$: any): any {
+    // Build the component name Set once — avoids rebuilding per render cycle
+    const componentNameSet = new Set(['collection', 'switchable', 'sygnal-factory', ...Object.keys(this.components)])
+
     return xs.combine(this.subComponentsRendered$, componentInstances$, this._readyChanged$.startWith(null))
       .compose(debounce(1))
       .map(([_, components]: [any, any]) => {
-        const componentNames = Object.keys(this.components)
-
         const root  = components['::ROOT::']
         const entries = Object.entries(components).filter(([id]) => id !== '::ROOT::')
 
@@ -1665,19 +1699,20 @@ class Component {
         }
 
         return xs.combine(...vdom$)
-          .compose(debounce(1))
+          .filter((vdoms: any) => vdoms.every((v: any) => v !== undefined))
           .map((vdoms: any) => {
             const withIds = vdoms.reduce((acc: Record<string, any>, vdom: any, index: any) => {
               acc[ids[index]] = vdom
               return acc
             }, {} as Record<string, any>)
-            const rootCopy = deepCopyVdom(root)
-            const injected = injectComponents(rootCopy, withIds, componentNames, 'r', undefined, this._childReadyState)
+            const injected = injectComponents(root, withIds, componentNameSet, 'r', undefined, this._childReadyState)
             return processSuspensePost(injected)
           })
       })
       .flatten()
       .filter((val: any) => !!val)
+      // [diagnostics hook]
+      .map((vdom: any) => { diag.onRender(this, vdom); return vdom })
       .remember()
   }
 
@@ -1731,93 +1766,92 @@ class Component {
 
 
 
-function getComponents(currentElement: any, componentNames: string[], path: string = 'r', parentId?: string): Record<string, any> {
-  if (!currentElement) return {}
+function getComponents(currentElement: any, componentNameSet: Set<string>, path: string = 'r', parentId?: string, found?: Record<string, any>): Record<string, any> {
+  if (!currentElement) return found || {}
 
-  if (currentElement.data?.componentsProcessed) return {}
+  if (currentElement.data?.componentsProcessed) return found || {}
   if (path === 'r') currentElement.data.componentsProcessed = true
 
+  // Allocate the result object only at the root call
+  if (!found) found = {}
+
   const sel          = currentElement.sel
   const isCollection = sel && sel.toLowerCase() === 'collection'
   const isSwitchable = sel && sel.toLowerCase() === 'switchable'
-  const isComponent  = sel && (['collection', 'switchable', 'sygnal-factory', ...componentNames].includes(sel)) || typeof currentElement.data?.props?.sygnalFactory === 'function' || isObj(currentElement.data?.props?.sygnalOptions)
+  const isComponent  = (sel && componentNameSet.has(sel)) || typeof currentElement.data?.props?.sygnalFactory === 'function' || isObj(currentElement.data?.props?.sygnalOptions)
   const props        = (currentElement.data && currentElement.data.props) || {}
-  const attrs        = (currentElement.data && currentElement.data.attrs) || {}
   const children     = currentElement.children || []
 
-  let found: Record<string, any>    = {}
-
   let id = parentId
   if (isComponent) {
     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.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)
+      if (!props.of)   fail('SYG411', undefined, "Collection is missing 'of'", 'Use of={ItemComponent}')
+      if (typeof props.of !== 'string' && typeof props.of !== 'function')         fail('SYG411', undefined, `Collection 'of' is a ${typeof props.of}`, 'Use of={ItemComponent}')
+      if (typeof props.of !== 'function' && !componentNameSet.has(props.of))   fail('SYG411', undefined, `Collection 'of' component not found: ${props.of}`, 'Use of={ItemComponent}')
+      // an invalid 'from' is reported once, with the component name, by instantiateCollection (G-026)
       currentElement.data.isCollection = true
       currentElement.data.props ||= {}
     } else if (isSwitchable) {
-      if (!props.of)        throw new Error(`Switchable element missing required 'of' property`)
-      if (!isObj(props.of)) throw new Error(`Invalid 'of' property of switchable element: found ${ typeof props.of } requires object mapping names to component factories`)
+      if (!props.of)        fail('SYG415', undefined, "Switchable is missing 'of'", 'Use of={{ name: Component }}')
+      if (!isObj(props.of)) fail('SYG415', undefined, `Switchable 'of' is a ${typeof props.of}`, 'Use of={{ name: Component }}')
       const switchableComponents = Object.values(props.of)
-      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`)
+      if (!switchableComponents.every(comp => typeof comp === 'function')) fail('SYG415', undefined, "Switchable 'of' has a value that is not a component", 'Use of={{ name: Component }}')
+      if (!props.current || (typeof props.current !== 'string' && typeof props.current !== 'function')) fail('SYG416', undefined, `Switchable 'current' is missing or a ${typeof props.current}`, "Set current to a key of 'of'")
       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)) fail('SYG416', undefined, `Switchable 'current' '${props.current}' is not a key of 'of'`, "Set current to a key of 'of'")
       currentElement.data.isSwitchable = true
-    } else {
-
     }
-    if (typeof props.key === 'undefined') currentElement.data.props.key = id
+    if (typeof props.key === 'undefined') (currentElement.data.props ||= {}).key = id
     found[id] = currentElement
   }
 
-  if (children.length > 0) {
-    children.map((child: any, i: any) => getComponents(child, componentNames, `${path}.${i}`, id))
-            .forEach((child: any) => {
-              Object.entries(child).forEach(([id, el]: [string, any]) => found[id] = el)
-            })
+  for (let i = 0; i < children.length; i++) {
+    getComponents(children[i], componentNameSet, `${path}.${i}`, id, found)
   }
 
   return found
 }
 
-function injectComponents(currentElement: any, components: Record<string, any>, componentNames: string[], path: string = 'r', parentId?: string, readyMap?: Record<string, boolean>): any {
-  if (!currentElement) return
-  if (currentElement.data?.componentsInjected) return currentElement
-  if (path === 'r' && currentElement.data) currentElement.data.componentsInjected = true
-
+function injectComponents(currentElement: any, components: Record<string, any>, componentNameSet: Set<string>, path: string = 'r', parentId?: string, readyMap?: Record<string, boolean>): any {
+  if (!currentElement) return undefined
 
   const sel          = currentElement.sel || 'NO SELECTOR'
-  const isComponent  = ['collection', 'switchable', 'sygnal-factory', ...componentNames].includes(sel) || typeof currentElement.data?.props?.sygnalFactory === 'function' || isObj(currentElement.data?.props?.sygnalOptions)
+  const isComponent  = componentNameSet.has(sel) || typeof currentElement.data?.props?.sygnalFactory === 'function' || isObj(currentElement.data?.props?.sygnalOptions)
   const isCollection = currentElement?.data?.isCollection
-  const isSwitchable = currentElement?.data?.isSwitchable
-  const props        = (currentElement.data && currentElement.data.props) || {}
   const children     = currentElement.children || []
 
   let id = parentId
   if (isComponent) {
     id  = getComponentIdFromElement(currentElement, path, parentId)
     let component = components[id]
-    // Annotate the injected VNode with its READY state
-    if (readyMap && id && component && typeof component === 'object' && component.sel) {
-      component.data = component.data || {}
-      component.data.attrs = component.data.attrs || {}
-      component.data.attrs['data-sygnal-ready'] = readyMap[id] !== false ? 'true' : 'false'
+    // Mark an injected VNode that is NOT ready (non-mutating) so Suspense can find it.
+    // Ready children get no attribute (G-018): moving markup into a child component
+    // must not change the DOM.
+    if (readyMap && id && readyMap[id] === false && component && typeof component === 'object' && component.sel) {
+      component = {
+        ...component,
+        data: {
+          ...(component.data || {}),
+          attrs: {
+            ...(component.data?.attrs || {}),
+            'data-sygnal-ready': 'false'
+          }
+        }
+      }
     }
     if (isCollection) {
-      currentElement.sel = 'div'
-      currentElement.children = Array.isArray(component) ? component : [component]
-      return currentElement
-    } else if (isSwitchable) {
-      return component
+      return {
+        ...currentElement,
+        sel: 'div',
+        children: Array.isArray(component) ? component : [component]
+      }
     } else {
       return component
     }
   } else if (children.length > 0) {
-    currentElement.children = children.map((child: any, i: any) => injectComponents(child, components, componentNames, `${path}.${i}`, id, readyMap)).flat()
-    return currentElement
+    const newChildren = children.map((child: any, i: any) => injectComponents(child, components, componentNameSet, `${path}.${i}`, id, readyMap)).flat()
+    return { ...currentElement, children: newChildren }
   } else {
     return currentElement
   }
@@ -1873,66 +1907,14 @@ function processSuspensePost(vnode: any): any {
     return { sel: 'div', data: { attrs: { 'data-sygnal-suspense': 'resolved' } }, children: children.map((c: any) => processSuspensePost(c)), text: undefined, elm: undefined, key: undefined }
   }
   if (vnode.children && vnode.children.length > 0) {
-    vnode.children = vnode.children.map((c: any) => processSuspensePost(c))
+    const newChildren = vnode.children.map((c: any) => processSuspensePost(c))
+    return { ...vnode, children: newChildren }
   }
   return vnode
 }
 
 const portalPatch = snabbdomInit(defaultModules);
 
-function processPortals(vnode: any): any {
-  if (!vnode || !vnode.sel) return vnode
-  if (vnode.sel === 'portal') {
-    const target = vnode.data?.props?.target
-    const children = vnode.children || []
-    return createPortalPlaceholder(target, children)
-  }
-  if (vnode.children && vnode.children.length > 0) {
-    vnode.children = vnode.children.map(processPortals)
-  }
-  return vnode
-}
-
-function processTransitions(vnode: any): any {
-  if (!vnode || !vnode.sel) return vnode
-  if (vnode.sel === 'transition') {
-    const props = vnode.data?.props || {}
-    const name = props.name || 'v'
-    const duration = props.duration
-    const children = vnode.children || []
-    const child = children[0]
-    if (!child || !child.sel) return child || vnode
-    return applyTransitionHooks(processTransitions(child), name, duration)
-  }
-  if (vnode.children && vnode.children.length > 0) {
-    vnode.children = vnode.children.map(processTransitions)
-  }
-  return vnode
-}
-
-function processClientOnly(vnode: any): any {
-  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: any, name: string, duration?: number): any {
   const existingInsert = vnode.data?.hook?.insert
   const existingRemove = vnode.data?.hook?.remove
@@ -1976,14 +1958,17 @@ function applyTransitionHooks(vnode: any, name: string, duration?: number): any
   return vnode
 }
 
-function processLazy(vnode: any, componentInstance: any): any {
+/**
+ * Single-pass VNode preprocessor that handles lazy, portal, transition, and clientonly
+ * nodes in one recursive walk instead of four separate passes.
+ */
+function preprocessVdom(vnode: any, componentInstance: any): any {
   if (!vnode || !vnode.sel) return vnode
 
-  // Check if this VNode wraps a lazy component via sygnalOptions
+  // Handle lazy components
   const view = vnode.data?.props?.sygnalOptions?.view
   if (view && view.__sygnalLazy) {
     if (view.__sygnalLazyLoaded()) {
-      // Lazy component is loaded — rebuild VNode with loaded component's properties
       const loaded = view.__sygnalLazyLoadedComponent
       if (loaded) {
         const props = vnode.data?.props || {}
@@ -2000,14 +1985,12 @@ function processLazy(vnode: any, componentInstance: any): any {
         }
       }
     } else {
-      // Schedule re-render when lazy promise resolves
       if (!view.__sygnalLazyReRenderScheduled && view.__sygnalLazyPromise && componentInstance) {
         view.__sygnalLazyReRenderScheduled = true
         view.__sygnalLazyPromise.then(() => {
           setTimeout(() => {
             const stateSource = componentInstance.sources?.[componentInstance.stateSourceName]
             if (stateSource && stateSource.stream) {
-              // Add a unique token to bypass dropRepeats deep comparison
               const stateCopy = { ...componentInstance.currentState, __sygnalLazyTick: Date.now() }
               stateSource.stream.shamefullySendNext(stateCopy)
             }
@@ -2017,8 +2000,42 @@ function processLazy(vnode: any, componentInstance: any): any {
     }
   }
 
+  // Handle portals
+  if (vnode.sel === 'portal') {
+    const target = vnode.data?.props?.target
+    const children = vnode.children || []
+    return createPortalPlaceholder(target, children)
+  }
+
+  // Handle transitions — recursively preprocess the child before applying hooks
+  if (vnode.sel === 'transition') {
+    const props = vnode.data?.props || {}
+    const name = props.name || 'v'
+    const duration = props.duration
+    const children = vnode.children || []
+    const child = children[0]
+    if (!child || !child.sel) return child || vnode
+    return applyTransitionHooks(preprocessVdom(child, componentInstance), name, duration)
+  }
+
+  // Handle clientonly — unwrap to children on client
+  if (vnode.sel === 'clientonly') {
+    const children = vnode.children || []
+    if (children.length === 0) return { sel: 'div', data: {}, children: [] }
+    if (children.length === 1) return preprocessVdom(children[0], componentInstance)
+    return {
+      sel: 'div',
+      data: {},
+      children: children.map((c: any) => preprocessVdom(c, componentInstance)),
+      text: undefined,
+      elm: undefined,
+      key: undefined,
+    }
+  }
+
+  // Recurse into children
   if (vnode.children && vnode.children.length > 0) {
-    vnode.children = vnode.children.map((child: any) => processLazy(child, componentInstance))
+    vnode.children = vnode.children.map((child: any) => preprocessVdom(child, componentInstance))
   }
   return vnode
 }
@@ -2037,6 +2054,21 @@ function onTransitionEnd(el: any, duration: number | undefined, cb: () => void):
 }
 
 
+function portalMount(vnode: any, target: string, children: any[]): void {
+  const container = document.querySelector(target)
+  if (!container) {
+    warn('SYG417', 'Portal', `Target '${target}' not found; content not rendered`, 'Render the target first')
+    return
+  }
+  const anchor = document.createElement('div')
+  container.appendChild(anchor)
+  vnode.data._portalVnode = portalPatch(anchor, {
+    sel: 'div', data: {}, children,
+    text: undefined, elm: undefined, key: undefined,
+  })
+  vnode.data._portalContainer = container
+}
+
 function createPortalPlaceholder(target: string, children: any[]): any {
   const portalChildren = children || []
 
@@ -2048,24 +2080,41 @@ function createPortalPlaceholder(target: string, children: any[]): any {
       portalChildren,
       hook: {
         insert: (vnode: any) => {
+          // Try synchronously first (target outside component tree or
+          // plain element in the same patch cycle).
           const container = document.querySelector(target)
-          if (!container) {
-            console.warn(`[Portal] Target "${target}" not found in DOM`)
+          if (container) {
+            portalMount(vnode, target, portalChildren)
             return
           }
-          const anchor = document.createElement('div')
-          container.appendChild(anchor)
-          vnode.data._portalVnode = portalPatch(anchor, {
-            sel: 'div', data: {}, children: portalChildren,
-            text: undefined, elm: undefined, key: undefined,
-          })
-          vnode.data._portalContainer = container
+          // Target may be rendered by a sub-component whose streams
+          // haven't settled yet (debounced). Retry a few times to
+          // allow sub-component rendering to complete.
+          let attempts = 0
+          const tryMount = () => {
+            if (vnode.data._portalVnode) return // already mounted
+            if (document.querySelector(target)) {
+              portalMount(vnode, target, portalChildren)
+            } else if (++attempts < 10) {
+              setTimeout(tryMount, 5)
+            } else {
+              warn('SYG417', 'Portal', `Target '${target}' not found; content not rendered`, 'Render the target first')
+            }
+          }
+          setTimeout(tryMount, 5)
         },
         postpatch: (oldVnode: any, newVnode: any) => {
           const prevPortalVnode = oldVnode.data?._portalVnode
           const container = oldVnode.data?._portalContainer
-          if (!prevPortalVnode || !container) return
           const newChildren = newVnode.data?.portalChildren || []
+          if (!prevPortalVnode || !container) {
+            // insert was deferred and hasn't fired yet, or target
+            // wasn't found. Try mounting now with updated children.
+            if (!newVnode.data._portalVnode) {
+              portalMount(newVnode, target, newChildren)
+            }
+            return
+          }
           newVnode.data._portalVnode = portalPatch(prevPortalVnode, {
             sel: 'div', data: {}, children: newChildren,
             text: undefined, elm: undefined, key: undefined,
@@ -2088,11 +2137,6 @@ function createPortalPlaceholder(target: string, children: any[]): any {
 }
 
 
-function deepCopyVdom(obj: any): any {
-  if (typeof obj === 'undefined') return obj
-  return { ...obj, children: Array.isArray(obj.children) ? obj.children.map(deepCopyVdom) : undefined, data: obj.data && { ...obj.data, componentsInjected: false } }
-}
-
 function propsIsEqual(obj1: any, obj2: any): boolean {
   return objIsEqual(sanitizeObject(obj1), sanitizeObject(obj2))
 }
@@ -2128,16 +2172,15 @@ function objIsEqual(obj1: any, obj2?: any, maxDepth: number = 5, depth: number =
 
   // Get keys of both objects
   const keys1 = Object.keys(obj1);
-  const keys2 = Object.keys(obj2);
 
   // Check if the number of properties is different
-  if (keys1.length !== keys2.length) {
+  if (keys1.length !== Object.keys(obj2).length) {
       return false;
   }
 
   // Recursively check each property
   for (const key of keys1) {
-      if (!keys2.includes(key)) {
+      if (!(key in obj2)) {
           return false;
       }
       if (!objIsEqual(obj1[key], obj2[key], maxDepth, depth + 1)) {
@@ -2158,6 +2201,8 @@ function isObj(obj: any): obj is Record<string, any> {
   return typeof obj === 'object' && obj !== null && !Array.isArray(obj)
 }
 
+const SORT_FIX = "Use a field name, { field: 'asc'|'desc'|1|-1 }, or a function"
+
 function __baseSort(a: any, b: any, ascending: boolean = true): number {
   const direction = ascending ? 1 : -1
   switch(true) {
@@ -2170,26 +2215,26 @@ function __baseSort(a: any, b: any, ascending: boolean = true): number {
 function __sortFunctionFromObj(item: Record<string, any>): ((a: any, b: any) => number) | undefined {
   const entries = Object.entries(item)
   if (entries.length > 1) {
-    console.error('Sort objects can only have one key:', item)
+    logError('SYG418', 'Collection', 'sort object must have one key; ignored', SORT_FIX, item)
     return undefined
   }
   const entry = entries[0]
   const [field, directionRaw] = entry
   if (!['string', 'number'].includes(typeof directionRaw)) {
-    console.error('Sort object properties must be a string or number:', item)
+    logError('SYG418', 'Collection', 'sort direction must be a string or number; ignored', SORT_FIX, item)
     return undefined
   }
   let ascending = true
   if (typeof directionRaw === 'string') {
     if (!['asc', 'desc'].includes(directionRaw.toLowerCase())) {
-      console.error('Sort object string values must be asc or desc:', item)
+      logError('SYG418', 'Collection', "sort direction must be 'asc' or 'desc'; ignored", SORT_FIX, item)
       return undefined
     }
     ascending = directionRaw.toLowerCase() !== 'desc'
   }
   if (typeof directionRaw === 'number') {
     if (directionRaw !== 1 && directionRaw !== -1) {
-      console.error('Sort object number values must be 1 or -1:', item)
+      logError('SYG418', 'Collection', 'sort direction must be 1 or -1; ignored', SORT_FIX, item)
       return undefined
     }
     ascending = directionRaw === 1
@@ -2227,7 +2272,7 @@ function sortFunctionFromProp(sortProp: any): ((a: any, b: any) => number) | und
   } else if (isObj(sortProp)) {
     return __sortFunctionFromObj(sortProp)
   } else {
-    console.error('Invalid sort option (ignoring):', sortProp)
+    logError('SYG418', 'Collection', 'Invalid sort prop; ignored', SORT_FIX, sortProp)
     return undefined
   }
 }