sygnal 5.3.7 → 6.0.0

package/src/core/hooks.ts

@@ -0,0 +1,314 @@
+/**
+ * PLAN-4.6 R0: the extension contract of the component core (types only: 0 bytes in any bundle).
+ * R1-R4 implemented it; R5 deleted the old core's instance patching it replaces. The prose
+ * contract, with the consumers mapped to these hooks, is
+ * dev-plans/research/core-rewrite/04-hooks-contract.md.
+ *
+ * Three layers:
+ * 1. Registries (module level, filled on import): what a feature module adds to the core without
+ *    the core naming it: hosts, markers (pre/post processors), view resolvers, definition hooks,
+ *    statics. An app that never imports the module pays nothing (D157).
+ * 2. Hooks (per app, from run() / renderComponent / the dev entries): observation and wrapping
+ *    points for diagnostics, devtools, testing and the dev action log. Every hook is optional and
+ *    the core calls it as `hooks.x?.(...)`.
+ * 3. The runtime API handed to hooks: inspection views and `setState`, so no consumer needs a raw
+ *    instance or a stream internal (`shamefullySendNext`, `_v`, `_n`).
+ *
+ * Invariants the hooks must not break (the flush contract, PLAN-4.6 §2 change 4):
+ * - Actions drain run-to-completion, FIFO: an action dispatched while another is processed (a
+ *   driver emitting synchronously during sink delivery, an EFFECT, a PARENT, a hook) is appended
+ *   to the queue, never run nested.
+ * - A STATE reducer is applied when its action is processed. Every other sink of that action gets
+ *   the state from before it.
+ * - A flush (one microtask after the first commit of a batch) repeats { render top-down, recompute
+ *   statics, drain the queue } until nothing changed, then emits ONE root vnode (one patch), then
+ *   runs ELEMENT commands and dispatches BOOTSTRAP for the instances created in it.
+ * - Loop guard: at most 100 passes per flush and 100 flushes per macrotask; past that the next
+ *   flush waits for a MessageChannel message. No timer anywhere in startup, flush or teardown.
+ * - Hooks run synchronously inside these steps. A hook may dispatch (it is queued), but must not
+ *   render, patch or dispose.
+ */
+
+// ---------------------------------------------------------------------------------- shared types
+
+/** A component function with its statics (view + `.intent`, `.model`, `.initialState`, ...) */
+export type ComponentFn = ((input: any) => any) & Record<string, any>
+
+/** One normalized model entry: the sink and its handler (a function, or a constant value) */
+export type Handler = [sink: string, fn: any]
+
+/**
+ * What a definition hook may read and edit: the component's statics, before normalization.
+ * Behaviors' existing `merge(component, key)` runs on a shim with these fields (spike finding 5),
+ * so `uses`, `undo`, `selection`, `pager` and `persist` work unchanged, once per component
+ * function instead of once per instance.
+ */
+export interface DefSource {
+  model: Record<string, any> | undefined
+  intent: ((sources: any) => Record<string, any>) | undefined
+  initialState: any
+  /** defaults of missing state keys (a behavior's slice or a resource's `{status: 'idle'}` on a sub-component) */
+  idle: Record<string, any> | null
+  calculated: Record<string, any> | undefined
+  context: Record<string, (state: any) => any> | undefined
+  /** action -> behavior key, for action logs (`pager.NEXT` comes from `pager`) */
+  behaviorActions: Record<string, string>
+}
+
+/** The normalized definition: computed once per component function (WeakMap) */
+export interface Def {
+  readonly name: string
+  readonly view: ComponentFn
+  readonly intent?: (sources: any) => Record<string, any>
+  /** action -> handlers in model order; a function entry is STATE */
+  readonly handlers: ReadonlyMap<string, readonly Handler[]>
+  readonly sinks: ReadonlySet<string>
+  readonly initialState: any
+  readonly idle: Record<string, any> | null
+  readonly isolated: boolean
+  /** calculated fields in topological order (SYG206 / SYG209 thrown at definition) */
+  readonly calculated: ReadonlyArray<[field: string, fn: (s: any) => any, deps: string[] | null]> | null
+  readonly context: ReadonlyArray<[key: string, fn: (s: any) => any]> | null
+  /** the statics this definition declares that some driver takes (`__sygnalStatic`) */
+  readonly statics: ReadonlyArray<string>
+  readonly behaviorActions: Readonly<Record<string, string>>
+  readonly onError?: (error: any, info: {componentName: string}) => any
+  /**
+   * R4 (renderComponent's root only): the model actions the test may dispatch with
+   * simulateAction that the intent doesn't name (wiring's SYG101/SYG102, inspect(); today's
+   * `__sygnalTestActions` on the intent object)
+   */
+  readonly testActions?: readonly string[]
+}
+
+/** Where an action came from (testing's t.actions `cause`, devtools, the action log) */
+export type ActionCause = 'intent' | 'next' | 'reply' | 'built-in' | 'simulateAction' | 'behavior' | 'parent' | 'setState'
+
+/**
+ * A read-only view of a live instance: everything devtools, diagnostics and testing read today
+ * from raw instance fields (`_componentNumber`, `name`, `currentState`, `currentProps`,
+ * `currentContext`, `isSubComponent`, `sources.__parentComponentNumber`, `_disposed`, ...).
+ * Getters are live; the object is stable for the instance's life.
+ */
+export interface InstanceView {
+  /** stable id (inspect()'s component id; today `_componentNumber`) */
+  readonly id: number
+  readonly parentId: number | undefined
+  readonly name: string
+  readonly def: Def
+  /** the state the view gets (calculated fields included; `currentState` + `addCalculated`) */
+  readonly state: any
+  readonly props: Record<string, any>
+  readonly context: Record<string, any>
+  readonly isRoot: boolean
+  /** 'item' (Collection), 'page' (Switchable), 'child' (tag), 'root' */
+  readonly kind: 'root' | 'child' | 'item' | 'page'
+  /** Switchable page: shown now (hidden pages skip render, keep actions and background statics) */
+  readonly shown: boolean
+  readonly disposed: boolean
+  /** the uid() root of this instance (`__uid`) */
+  readonly uid: string
+  /** its children, in render order */
+  children(): InstanceView[]
+  /** the sources its intent got (after wrapSources), e.g. to compare with run()'s sources */
+  readonly sources: Readonly<Record<string, any>>
+}
+
+/** An action as the queue holds it */
+export interface ActionRecord {
+  readonly type: string
+  readonly data: any
+  readonly cause: ActionCause
+  /** the instance that runs it */
+  readonly target: InstanceView
+  /** a reply: the source (driver name) that delivered it (R4: devtools' replySink) */
+  readonly source?: string
+}
+
+// ---------------------------------------------------------------------------------- 2. hooks
+
+export interface Hooks {
+  // ------------------------------------------------------------------ definition time
+  /**
+   * Called once per component function, before normalization, with the definition's statics.
+   * Return a new (or the same, edited) DefSource. Runs for every app on the page (definitions are
+   * shared), so it must depend only on `view`. Behaviors, undo, selection, pager, persist's model
+   * rewrite and resources' RESOURCE entry use the module registry (`defHooks`) instead; this hook
+   * is for a per-app consumer that needs the same point (diagnostics' SYG222 reducer wrapping,
+   * strict checks of the model's shape).
+   */
+  transformDef?(src: DefSource, view: ComponentFn): DefSource | void
+
+  // ------------------------------------------------------------------ instance lifetime
+  /** after the instance's state cell and INITIALIZE, before its intent subscribes */
+  onCreate?(inst: InstanceView): void
+  /** at the start of dispose (DISPOSE has been queued; its streams are not stopped yet) */
+  onDispose?(inst: InstanceView): void
+  /** after the instance's view ran and its children were injected (only when it re-rendered) */
+  onRender?(inst: InstanceView, vnode: any): void
+  /** after the root vnode was patched (one per flush that changed the vnode) */
+  onPatch?(vnode: any): void
+
+  // ------------------------------------------------------------------ sources
+  /**
+   * The sources an instance's intent gets. Return a wrapper (a Proxy that records selectors, a
+   * fake for a driverless sink, a checking DOM source). Called once per instance, before the
+   * intent; `fake(name)` style sources added here take part in replies/statics detection, which
+   * happens after this hook (today testing mutates `sources`/`sourceNames` from onIntent).
+   */
+  wrapSources?(inst: InstanceView, sources: Record<string, any>): Record<string, any>
+  /** the intent's action names (the wiring checks, inspect()) */
+  onIntent?(inst: InstanceView, actionNames: string[]): void
+
+  // ------------------------------------------------------------------ actions
+  /** an action is about to be processed (dequeued); `cause` says where it came from */
+  onAction?(inst: InstanceView, action: ActionRecord): void
+  /**
+   * Wrap one handler of an action. `fn` is the model entry (a function or a constant). Return a
+   * replacement with the same contract; ABORT / the same state still mean "no change". Used by
+   * the action log (which sinks produced a value), SYG222 checks, devtools.
+   */
+  wrapHandler?(inst: InstanceView, type: string, sink: string, fn: any): any
+  /** the STATE reducer of an action ran (`next` is what was written; `prev === next`: no change) */
+  onReducer?(inst: InstanceView, type: string, prev: any, next: any): void
+  /**
+   * a non-STATE sink produced a value (before it is stamped with `__emitterId`/`__emitterName`).
+   * R4: a declaration static sent to a driver (`{ resources }`, `{ connections }`, `{ timers }`,
+   * ...) comes here too, with `type` null
+   */
+  onSink?(inst: InstanceView, type: string | null, sink: string, value: any): void
+  /**
+   * R4 (04 §4 #3): a host's props when it is created and each time its owner re-renders it
+   * (`sel`: the marker's, a Collection's or a VirtualCollection's), before it renders; the Collection checks (SYG401
+   * for a missing `from`) read them here. `data`: the marker's vnode data (4-H: the buckets a
+   * removed wrapper element would have had: style, class, attrs, ...)
+   */
+  onHostProps?(owner: InstanceView, sel: string, props: Record<string, any>, data?: Record<string, any>): void
+  /** a model next(type, data, ms) was scheduled (replaces testing's NEXT_LOG debug-text parsing) */
+  onNext?(inst: InstanceView, type: string, data: any, ms: number): void
+  /**
+   * an ELEMENT command (or an array of them) was sent; it runs after the next patch (testing
+   * records, diagnostics checks). `false`: not run (renderComponent's mock DOM records only)
+   */
+  onElementCommand?(inst: InstanceView, command: any): void | false
+
+  // ------------------------------------------------------------------ state, context, readiness
+  /** an instance's (calculated) state changed in this flush (devtools onStateChanged) */
+  onStateChanged?(inst: InstanceView, state: any): void
+  /** an instance's props changed (devtools onPropsChanged, SYG props checks) */
+  onPropsChanged?(inst: InstanceView, props: any): void
+  /** an instance's context changed; `keys`: the keys that changed (D168) */
+  onContextChanged?(inst: InstanceView, context: any, keys: string[]): void
+  /**
+   * D174: an `isolatedState` child bound to a slice that already exists (state="key" or a lens,
+   * without `resetState`) keeps the parent's data instead of its initialState. R4's dev warning
+   * reports the keys `initialState` defines that the slice lacks.
+   */
+  onStateSeed?(inst: InstanceView, slice: any, initialState: any): void
+  /** D169: a Collection item key (id, or raw index) that appears more than once; only its first element renders. R4's dev warning */
+  onDuplicateKey?(owner: InstanceView, key: any): void
+  /** a child's READY flag changed (devtools, Suspense diagnostics) */
+  onReady?(inst: InstanceView, child: InstanceView, ready: boolean): void
+  /**
+   * D168 safety net (dev only; R4): context tracking skipped this view's re-render (the context
+   * changed, but no key the view read). `render(ctx)` calls the view again with the instance's
+   * current inputs and that context (a fresh template, nothing injected or patched), so the
+   * consumer can compare `render(prev)` with `render(next)` on a sample of skips and report a
+   * difference (sygnal/diagnostics: SYG423). `keysRead`: the keys the last view call read.
+   */
+  onContextSkip?(inst: InstanceView, render: (context: any) => any, prev: any, next: any, keysRead: string[]): void
+
+  // ------------------------------------------------------------------ errors
+  /** the app-level error hook (run()'s `onError`, GS-11), with the phase the error came from */
+  onError?(error: any, info: {componentName: string; phase: 'view' | 'model' | 'intent' | 'calculated' | 'context' | 'widget' | 'driver'; action?: string}): void
+}
+
+/**
+ * What the runtime hands to hooks and tools (devtools, testing, sygnal/element, HMR, Vike). It
+ * replaces every `sinks.STATE.shamefullySendNext(...)` and `STATE.stream._v` reach-in.
+ */
+export interface RuntimeAPI {
+  /** the root instance (devtools tree, inspect()) */
+  readonly root: InstanceView
+  /** find an instance by id (devtools selection, time travel) */
+  get(id: number): InstanceView | undefined
+  /** the current root state, synchronously (today `STATE.stream._v`) */
+  getState(): any
+  /**
+   * Replace the state of `target` (the root, or an instance's own cell: a Collection item, an
+   * isolatedState component) as a 'setState' action: queued, applied run-to-completion, one patch.
+   * A function gets the current state. Devtools time travel, element prop sync, HMR state
+   * restore, Vike page swaps, persist RESTORE.
+   */
+  setState(target: 'root' | InstanceView | number, state: any | ((current: any) => any)): void
+  /** dispatch an action to an instance, as if its intent emitted it (testing's simulateAction) */
+  dispatch(target: 'root' | InstanceView | number, type: string, data?: any, cause?: ActionCause): void
+  /** add / remove hooks on a live app (devtools connecting late; sygnal/diagnostics installed after run()) */
+  addHooks(hooks: Hooks): () => void
+  /** a resolved promise after the current flush (testing's settle without polling) */
+  flushed(): Promise<void>
+  /** R4: debug logging for one instance on / off (the DevTools toggle; core/debug.ts) */
+  setDebug(target: 'root' | InstanceView | number, on: boolean): void
+}
+
+// ---------------------------------------------------------------------------------- 1. registries
+
+/**
+ * A child that renders in place of a marker vnode (Collection, Switchable). The registry entries
+ * are core modules: they get the owner's raw instance (R2), unlike hooks.
+ */
+export interface Host {
+  /** render with the latest props; return the vnode to inject (the cached one when nothing changed) */
+  render(): any
+  /** the latest props and children; `marker` / `id`: the marker vnode and its id in the owner */
+  setProps(props: Record<string, any>, children: any[], marker?: any, id?: string): void
+  dispose(): void
+  /** READY of its instances (Suspense); Collection and Switchable stay ready, as today */
+  readonly ready: boolean
+  /** its instances (byId, InstanceView.children) */
+  insts(): any[]
+}
+
+export interface Registry {
+  /** marker sel -> host factory (Collection, Switchable) */
+  hosts: Record<string, (owner: any, props: Record<string, any>, children: any[], id: string, marker: any) => Host>
+  /**
+   * marker sel -> template rewrite during the reconcile walk (Portal, Transition, ClientOnly,
+   * Slot): replace the marker with a plain vnode and keep walking its children.
+   */
+  pres: Record<string, (vnode: any, owner: any) => any>
+  /** marker sel -> post-processor of the injected vnode of an instance whose template had it (Suspense) */
+  posts: Record<string, (vnode: any, owner: any) => any>
+  /**
+   * component function -> the function to instantiate (lazy: the loaded component once resolved;
+   * `owner.refresh()` renders the owner again when it loads)
+   */
+  resolvers: Array<(view: ComponentFn, owner: any) => ComponentFn | undefined>
+  /** definition time, every app: behaviors (`uses`), undo, selection, pager, persist, resources */
+  defHooks: Array<(src: DefSource, view: ComponentFn) => DefSource | void>
+}
+
+/**
+ * The statics contract (unchanged from today's generic path, `__sygnalStatic`): a driver source
+ * that names a static (`__sygnalStatic: 'timers'`) gets each declaring instance's value of
+ * `view[static](state)` on its sink, recomputed on commits that changed that instance's state,
+ * dropped when deep-equal to the last (objIsEqual), filtered to `background: true` entries while
+ * the instance is on a hidden Switchable page, stamped with `__emitterId` / `__emitterName`.
+ * A source with `__sygnalReplies: true` and `replies(emitterId)` sends reply actions back to
+ * exactly that instance. Optional `isolateValue(value, scope)` lets a driver scope a sink value
+ * without a stream per instance (03 §5); without it the core falls back to `isolateSink`.
+ */
+export interface StaticsSource {
+  __sygnalStatic?: string
+  __sygnalReplies?: true
+  replies?(emitterId: number): any
+  isolateSource?(source: any, scope: string): any
+  isolateSink?(sink$: any, scope: string): any
+  isolateValue?(value: any, scope: string): any
+}
+
+/** Options of run() the core reads; `hooks` is internal (dev entries, testing), not documented */
+export interface InternalRunOptions {
+  /** hooks of this app (testing, devtools, diagnostics install theirs through these) */
+  __hooks?: Hooks
+}

package/src/core/hosts/collection.ts

@@ -0,0 +1,325 @@
+/**
+ * PLAN-4.6 core: the Collection host (03-proposal §2 hosts/, R2). Registered on import (the
+ * public `Collection` module imports this file); the core only looks `hosts.collection` up.
+ *
+ * It stands where the `<Collection>` marker was in its owner's template and renders the items
+ * inside the owner's render: no stream of its own, no pickCombine.
+ * - `of`: a component function (D163: no names). `from`: a state key (SYG409 on a calculated
+ *   one), a `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
+ *   owner's state is the array).
+ * - Items are keyed by `id`, an id-less item by its raw index (D169); one key -> index map per
+ *   array identity serves every item (cell.ts indexer). A duplicate key renders its first element
+ *   only; the dev warning is R4's (hooks.onDuplicateKey is the hook point).
+ * - `filter` / `sort` (every form today's core accepts; SYG418 for an invalid one) change what
+ *   renders and in which order; the state array keeps its order, and an item writes back to its
+ *   own element. An item returning `undefined` removes itself.
+ * - The other props go to every item, and the Collection's children are each item's children.
+ * - 4-H (D229): no element of its own. It renders a keyed fragment of the items' vnodes (its key:
+ *   the marker's, else its id), which the DOM driver splices into the parent's children before
+ *   each patch (utils.ts flat): the items are the parent element's own children, and their keys
+ *   take the fragment's, so two sibling Collections' items never collide. The wrapper `div` of
+ *   5.x is gone: `className` / `style` / `class` / ... on the marker are a removed-form error in development
+ *   (checks/next.ts) and are ignored.
+ * - Removed items are disposed synchronously in the render that drops them (G-257: a move between
+ *   two Collections is one patch).
+ * - PLAN-5 A-1: `viewTransitionName="card"` styles each keyed item's root element with
+ *   `view-transition-name: card-<id>` (shared.ts vtStyle) and `view-transition-class:
+ *   card`, the item's own style winning, so a `viewTransitions` action animates each item between
+ *   its places, across Collections with the same prefix too. Id-less items (keyed by index) and
+ *   fragment roots get none.
+ */
+import {hosts, resolvers} from '../registry'
+import {Inst, shallowEq} from '../instance'
+import {Cell, Index, indexer, itemCell, keyCell, keyOf, keyName} from '../cell'
+import {CoreDef, isObj} from '../define'
+import {uidPart, vtStyle} from '../../shared'
+import {viewOf} from '../view'
+import {warn, error as logError, fail} from '../../extra/diagnostics/legacy'
+
+const SORT_FIX = "Use a field name, { field: 'asc'|'desc'|1|-1 }, or a function"
+const sortError = (msg: string, value: any): undefined => void logError('SYG418', 'Collection', msg, SORT_FIX, value)
+const base = (a: any, b: any, asc = true) => (a > b ? (asc ? 1 : -1) : a < b ? (asc ? -1 : 1) : 0)
+
+function fromObj(item: Record<string, any>): ((a: any, b: any) => number) | undefined {
+  const e = Object.entries(item)
+  if (e.length > 1) return sortError('sort object must have one key; ignored', item)
+  const [f, d] = e[0]
+  let asc
+  if (typeof d == 'string') {
+    const x = d.toLowerCase()
+    if (x != 'asc' && x != 'desc') return sortError("sort direction must be 'asc' or 'desc'; ignored", item)
+    asc = x == 'asc'
+  } else if (typeof d == 'number') {
+    if (d !== 1 && d !== -1) return sortError('sort direction must be 1 or -1; ignored', item)
+    asc = d === 1
+  } else return sortError('sort direction must be a string or number; ignored', item)
+  return (a, b) => base(a[f], b[f], asc)
+}
+
+/** the comparator of a `sort` prop (today's sortFunctionFromProp) */
+export function sortFn(p: any): ((a: any, b: any) => number) | undefined {
+  if (!p) return
+  if (typeof p == 'function') return p
+  if (typeof p == 'string') {
+    const d = p.toLowerCase()
+    if (d == 'asc' || d == 'desc') return (a, b) => base(a, b, d == 'asc')
+    return (a, b) => base(a[p], b[p])
+  }
+  if (Array.isArray(p)) {
+    const fs: any[] = p.map(i => typeof i == 'function' ? i
+      : typeof i == 'string' ? (['asc', 'desc'].includes(i.toLowerCase()) ? undefined : (a: any, b: any) => base(a[i], b[i]))
+      : isObj(i) ? fromObj(i) : undefined).filter(f => typeof f == 'function')
+    return (a, b) => fs.reduce((r, f) => (r !== 0 ? r : f(a, b)), 0)
+  }
+  if (isObj(p)) return fromObj(p)
+  return sortError('Invalid sort prop; ignored', p)
+}
+
+/** the Collection's own props (`idfield`, removed in 6.0 (D164), is still kept off the items) */
+const OWN = new Set(['of', 'from', 'filter', 'sort', 'idfield', 'className', 'viewTransitionName'])
+const NONE: any[] = []
+
+/** the array cell for `from` (D178: a missing key renders once it appears), or null for an invalid `from` (renders nothing) */
+function arrayCell(owner: Inst, from: any): Cell | null {
+  const oc = owner.cell, name = owner.def.name
+  if (from === undefined) {
+    // the owner's state is the array (or its `value`, as today)
+    return {
+      get: () => { const s = oc.get(); return !Array.isArray(s) && Array.isArray(s?.value) ? s.value : s },
+      set: (v) => oc.set(v),
+    }
+  }
+  if (typeof from == 'string') {
+    const cs = oc.get(), calc = owner.def.calcNames?.has(from)
+    if (isObj(cs) && !(from in cs) && !calc) {
+      const arrays = Object.keys(cs).filter(k => Array.isArray(cs[k]))
+      warn('SYG401', name, `Collection from="${from}" is not in state${arrays.length ? ` (array fields: '${arrays.join("', '")}')` : ''}; it renders nothing until it exists`, 'Set it to an array in initialState')
+    } else if (isObj(cs) && !Array.isArray(cs[from])) warn('SYG401', name, `Collection 'from' field '${from}' is not an array; it renders nothing`, 'Set it to an array in initialState')
+    return keyCell(oc, from, calc && name, undefined, 'Collection')
+  }
+  if (isObj(from) && typeof from.get == 'function') {
+    let lp: any = {}, lv: any
+    return {
+      get() {
+        const p = oc.get()
+        if (p !== lp) {
+          lp = p
+          let g: any
+          try { g = from.get(p) } catch (e) {
+            // G-298: keeps the items it had
+            logError('SYG412', name, "Collection 'from' getter threw; it keeps its items", 'Guard the getter against missing data', e)
+            owner.app.appError(owner, e, 'view')
+            return lv
+          }
+          lv = g
+          if (!Array.isArray(lv)) { warn('SYG401', name, "Collection 'from' getter returned a non-array; it renders nothing", 'Return an array from get()', lv); lv = NONE }
+        }
+        return lv
+      },
+      set(v) {
+        if (typeof from.set != 'function') return
+        const p = oc.get(), n = from.set(p, v)
+        if (n !== p) oc.set(n)
+      },
+    }
+  }
+  logError('SYG412', name, "Collection 'from' prop is invalid; it renders nothing", 'Use a state key string or { get, set }', from)
+  return null
+}
+
+/** a component function through the view resolvers (lazy: the loaded one; the owner renders again when it loads) */
+export function resolve(view: any, owner: Inst) {
+  for (const r of resolvers) view = r(view, owner) || view
+  return view
+}
+
+export class CollectionHost {
+  /** key -> item instance */
+  items = new Map<any, Inst>()
+  /** the items shown, in render order */
+  shown: Inst[] = []
+  arr: Cell | null
+  index: Index | null
+  def!: CoreDef
+  ready = true
+  disposed = false
+  outv: any; last: any; lr = true
+  ip: Record<string, any> = {}
+  kids: any[] = NONE
+  props!: Record<string, any>
+  // the inputs of the last item list: array, filter, sort prop, comparator
+  la: any; lf: any; ls: any; cmp: any
+  uidBase: string
+  /** the fragment's key (the marker's, else the Collection's id) */
+  key: any
+  tr: any
+  /** the app's render epoch it last rendered at (G-311) */
+  ep = 0
+
+  constructor(public owner: Inst, props: Record<string, any>, children: any[], id: string, marker: any) {
+    this.hostProps(props, marker)
+    const of = props.of
+    if (!of) fail('SYG411', owner, "Collection is missing 'of'", 'Use of={ItemComponent}')
+    if (typeof of != 'function') fail('SYG411', owner, `Collection 'of' is a ${typeof of}`, 'Use of={ItemComponent}')
+    this.uidBase = owner.uid(uidPart(id.replace(/.*::(r\.)?/, '')))
+    this.arr = arrayCell(owner, props.from)
+    this.index = this.arr && indexer(this.arr)
+    this.def = owner.app.def(this.view = resolve(of, owner))
+    this.setProps(props, children, marker, id)
+  }
+
+  /**
+   * onHostProps (R4): the Collection checks of the dev entry (SYG401 for a missing `from`, D173's
+   * string `of`, 4-H's wrapper props: the marker's data); the marker's sel tells a
+   * VirtualCollection from a Collection
+   */
+  hostProps(props: Record<string, any>, m: any) {
+    const H = this.owner.app.hooks
+    if (H.onHostProps) H.onHostProps(viewOf(this.owner), m.sel, props, m.data)
+  }
+
+  /** the item component (a lazy() one: the loaded component once it has loaded, G-317) */
+  view: any
+
+  setProps(props: Record<string, any>, children: any[], marker?: any, id?: string) {
+    // (the constructor called the hook before its own checks)
+    if (this.props) this.hostProps(props, marker)
+    const v = typeof props.of == 'function' ? resolve(props.of, this.owner) : this.view
+    if (v !== this.view) {
+      // another item component (or a lazy one loaded): the items are made again
+      this.def = this.owner.app.def(this.view = v)
+      this.clear()
+    }
+    this.props = props
+    if (marker) {
+      // tr: a <Transition> around it, applied to each item (4-I G-559, markers/transition.ts):
+      // the fragment is made again on each of the owner's renders while there is one (or was)
+      const k = marker.key ?? id
+      if (this.tr !== (this.tr = marker.data?.tr) || k !== this.key) { this.key = k; this.outv = undefined }
+    }
+    const ip: Record<string, any> = {}
+    for (const k in props) if (!OWN.has(k)) ip[k] = props[k]
+    const kids = children.length ? children : NONE
+    if (!shallowEq(ip, this.ip) || kids !== this.kids) {
+      this.ip = ip
+      this.kids = kids
+      this.items.forEach(i => i.setProps(ip, kids))
+    }
+  }
+
+  clear() {
+    this.items.forEach(i => i.dispose())
+    this.items.clear()
+    this.shown = []
+    this.la = undefined
+  }
+
+  /** the item instances in the order shown (byId, InstanceView.children) */
+  insts(): Inst[] { return this.shown }
+
+  /** the visible keys in order: filter and sort over the raw array; a duplicate key once */
+  list(a: any[], m: Map<any, number>): any[] {
+    const {filter, sort} = this.props
+    const cmp = sort !== this.ls ? sortFn(sort) : this.cmp
+    let idx: number[] | null = null
+    if (typeof filter == 'function' || cmp) {
+      idx = []
+      for (let i = 0; i < a.length; i++) if (typeof filter != 'function' || filter(a[i], i, a)) idx.push(i)
+      if (cmp) idx.sort((x, y) => cmp(a[x], a[y]))
+    }
+    // G-311: the inputs are kept only once the list was made (a throwing filter / sort is retried)
+    this.ls = sort; this.cmp = cmp
+    const n = idx ? idx.length : a.length, keys: any[] = []
+    for (let x = 0; x < n; x++) {
+      const i = idx ? idx[x] : x, k = keyOf(a[i], i)
+      // D169: a duplicate key renders its first element (R4 reports it)
+      if (m.get(k) !== i) { const H = this.owner.app.hooks; H.onDuplicateKey && H.onDuplicateKey(viewOf(this.owner), k[0] == '\0' ? i : a[i].id); continue }
+      keys.push(k)
+    }
+    return keys
+  }
+
+  /**
+   * G-319: on a hidden Switchable page (no render): the items follow the array (removed ones are
+   * disposed, new ones created, so their background statics and replies run), with no view call
+   */
+  sync() {
+    if (this.disposed) return
+    this.items_()
+    for (const i of this.shown) i.sync()
+  }
+
+  /** the item instances for the current array, filter and sort; true when the list changed */
+  items_(): boolean {
+    if (!this.index) return false
+    const app = this.owner.app
+    let changed = false
+    {
+      const [a, m] = this.index()
+      const {filter, sort} = this.props
+      if (a !== this.la || filter !== this.lf || sort !== this.ls) {
+        const keys = this.list(a, m), seen = new Set(keys)
+        this.la = a; this.lf = filter
+        for (const [k, inst] of this.items) if (!seen.has(k)) { inst.dispose(); this.items.delete(k) }
+        const o = this.owner, shown: Inst[] = []
+        for (const k of keys) {
+          let inst = this.items.get(k)
+          if (!inst) {
+            const scope = app.scope()
+            inst = new Inst(app, this.def, o, itemCell(this.arr!, this.index, k), o.dom && o.dom.isolateSource(o.dom, scope),
+              this.ip, this.kids, scope, this.uidBase + '-' + keyName(k), 'item')
+            this.items.set(k, inst);
+            // its key (A-1's view-transition name)
+            (inst as any).k = k
+          }
+          shown.push(inst)
+        }
+        if (shown.length != this.shown.length || shown.some((s, i) => s !== this.shown[i])) changed = true
+        this.shown = shown
+      }
+    }
+    return changed
+  }
+
+  render(): any {
+    if (this.disposed) return this.outv
+    // G-311: after a render that threw, every container is made again once
+    const app = this.owner.app
+    let changed = !this.outv || this.ep !== app.ep
+    this.ep = app.ep
+    if (this.items_()) changed = true
+    const shown = this.shown, out: any[] = Array(shown.length), vn = this.props.viewTransitionName
+    let j = 0
+    for (let i = 0; i < shown.length; i++) {
+      const inst: any = shown[i], v = inst.render()
+      if (v !== inst.last) { inst.last = v; changed = true }
+      // an item without state yet (or a removed one) is left out
+      if (v !== undefined) out[j++] = this.tr ? this.tr(vn ? named(inst, v, vn) : v) : vn ? named(inst, v, vn) : v
+    }
+    out.length = j
+    if (!changed) return this.outv
+    return (this.outv = {sel: undefined, data: {}, children: out, text: undefined, elm: undefined, key: this.key})
+  }
+
+  dispose() {
+    if (this.disposed) return
+    this.disposed = true
+    this.clear()
+  }
+}
+
+/**
+ * A-1: the item's vnode with its view-transition name (cached per item, so an unchanged item
+ * keeps its vnode). VirtualCollection's rows too (extra/virtual.ts, G-417)
+ */
+export function named(inst: any, v: any, p: string): any {
+  const k = inst.k
+  if (!v.sel || k[0] == '\0') return v
+  if (inst.vi !== v || inst.vp !== p) {
+    inst.vi = v; inst.vp = p
+    inst.vo = {...v, data: {...v.data, style: vtStyle(p, k, v.data?.style)}}
+  }
+  return inst.vo
+}
+
+hosts.collection = (owner, props, children, id, marker) => new CollectionHost(owner, props, children, id, marker)