sygnal 7.0.0 → 7.2.0-preview.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { VNode, VNodeData } from 'snabbdom/build/vnode.js';
 import { Module } from 'snabbdom/build/modules/module.js';
 import xsDefault, { Stream, MemoryStream } from 'xstream';
 export { MemoryStream, Stream } from 'xstream';
-import { FieldErrors as FieldErrors$1, BehaviorTarget as BehaviorTarget$1, Behavior as Behavior$1, RenderResult as RenderResult$1, FetchRequest as FetchRequest$1 } from 'sygnal';
+import { FieldErrors as FieldErrors$1, BehaviorTarget as BehaviorTarget$1, Behavior as Behavior$1, StandardSchemaLike as StandardSchemaLike$1, RenderResult as RenderResult$1, FetchRequest as FetchRequest$1 } from 'sygnal';
 export { h } from 'snabbdom/build/h.js';
 export { default as debounce } from 'xstream/extra/debounce.js';
 export { default as throttle } from 'xstream/extra/throttle.js';
@@ -148,6 +148,11 @@ declare class MainDOMSource {
     private _eventDelegator;
     private _name;
     constructor(_rootElement$: Stream<Element>, _sanitation$: Stream<null>, _namespace: Array<Scope$1>, _isolateModule: IsolateModule, _eventDelegator: EventDelegator, _name: string);
+    isolateSource(source: MainDOMSource, scope: string): MainDOMSource;
+    private _is?;
+    private _iv?;
+    get isolateSink(): IsolateSink<VNode>;
+    get isolateValue(): (node: any, scope: string, memo?: any) => any;
     private _elements;
     elements(): MemoryStream<Array<Element>>;
     element(): MemoryStream<Element>;
@@ -157,9 +162,6 @@ declare class MainDOMSource {
     events<K extends keyof HTMLElementEventMap>(eventType: K, options?: EventsFnOptions, bubbles?: boolean): EnrichedEventStream<HTMLElementEventMap[K]>;
     events(eventType: string, options?: EventsFnOptions, bubbles?: boolean): EnrichedEventStream<Event>;
     dispose(): void;
-    isolateSource: (source: MainDOMSource, scope: string) => MainDOMSource;
-    isolateSink: IsolateSink<VNode>;
-    isolateValue: (node: any, scope: string) => any;
 }
 
 interface DOMDriverOptions {
@@ -1456,7 +1458,7 @@ type CatalogParam =
   /** a number (LLM: a number; decisions: a bin, which names the vague words it covers) */
   | { type: 'number'; min?: number; max?: number; default?: number; bins?: Record<string | number, string>; label?: string }
   /** free text: LLM only (a decision model keeps the default; `required` with no default makes the part LLM-only) */
-  | { type: 'text'; maxLength?: number; default?: string; required?: boolean; label?: string }
+  | { type: 'text'; maxLength?: number; default?: string; required?: boolean; label?: string; /** source code (a generated part's): the prompt says so, and asked_for items keep their own length */ format?: 'code' }
   /** a list of short texts: LLM only */
   | { type: 'list'; items?: { maxLength?: number }; min?: number; max?: number; required?: boolean; default?: readonly string[]; label?: string }
   /** a record: one node per record (at most one per part) */
@@ -1795,6 +1797,99 @@ declare const compose: {
   action<K extends string = 'page'>(key?: K, options?: { description?: string; timeout?: number }): Record<`${K}.COMPOSE`, AgentAction<any, { prompt: string; fresh?: boolean }>>
   /** PLAN-9 C-2: a composition as an agent's `read` shows it: its status, the layout as a tree, the error */
   summary(slice: ComposeState | null | undefined): { status: ComposeStatus; page: ComposeTree; error?: string } | undefined
+  /**
+   * EXPERIMENTAL (outside semver): a part whose component the model writes, run in sygnal/sandbox.
+   * `runtime` is `generatedRuntime({ kernel, compile })` from 'sygnal/sandbox'. Add `gen.part` to the
+   * catalogs that may have one (never a default), `gen.instructions` to compose.llm's instructions,
+   * `fix: gen.repair()` to the host's `uses`, and read events with `gen.events(CHILD, type)`.
+   */
+  generated<STATE = any, const D extends Record<string, GeneratedData<STATE>> = {}, const E extends Record<string, GeneratedEmit> = {}>(
+    runtime: { readonly Box: any },
+    options?: ComposeGeneratedOptions<STATE, D, E>
+  ): ComposeGenerated<D, E>
+}
+
+// ---- compose.generated (experimental, outside semver) -------------------------------------------
+
+/** A data key a generated part may read: its value is `from(state)`, as JSON, when the node lists the key in `reads` */
+interface GeneratedData<STATE = any> {
+  /** what the prompt says it is */
+  description: string
+  /** its shape for the prompt (never the data): '[{ id: number, name: string }]' */
+  shape?: string
+  from: (state: STATE) => unknown
+}
+/** An event type a generated part may send: its data passes `schema` (its output reaches the host), anything else is dropped */
+interface GeneratedEmit<S extends StandardSchemaLike$1 = StandardSchemaLike$1> {
+  description?: string
+  /** a Standard Schema (zod 4's JSON Schema export goes into the prompt) */
+  schema: S
+}
+
+interface ComposeGeneratedOptions<STATE = any, D = {}, E = {}> {
+  /** what the code may read (default none) */
+  data?: D & Record<string, GeneratedData<STATE>>
+  /** what the code may send (default none: the part only displays) */
+  emits?: E & Record<string, GeneratedEmit>
+  /** the part id the prompt names (default 'custom'; use it as the catalog key) */
+  id?: string
+  /** characters of code (default 4000; the schema caps `code` at maxCode + 1) */
+  maxCode?: number
+  /** generated parts per page (default 3) */
+  maxUses?: number
+  /** default 'worker' (QuickJS in a Worker with a watchdog); 'thread' is the opt-in */
+  isolation?: 'worker' | 'thread'
+  /** over the runtime's limits */
+  limits?: Record<string, number>
+  policy?: Record<string, unknown>
+  /** none by default (e.g. `{ fetch: { allow: [...] } }`) */
+  capabilities?: Record<string, unknown>
+  /** the check before mount (default true) */
+  check?: boolean
+  /** the class names the prompt offers */
+  classes?: string
+  /** the part's description in the catalog */
+  description?: string
+  /** what a part the model couldn't fix shows (default "This part couldn't be built.") */
+  fallback?: string
+  /** the host key of `gen.repair()` (default 'fix') */
+  repairKey?: string
+  /** the repair requests' sink (default 'LLM') */
+  sink?: string
+}
+
+/** A generated part's event as the host's intent reads it */
+type GeneratedEvent<E, K extends keyof E> = { node: string } & (E[K] extends { schema: infer S } ? SchemaOutput<S> : unknown)
+
+/** gen.repair()'s slice (`state.fix`): the overlay of fixed code and each chain's status */
+interface GeneratedRepairState {
+  /** hash(failing code) → fixed code */
+  patches: Record<string, string>
+  parents: Record<string, string>
+  attempts: Record<string, number>
+  status: Record<string, 'repairing' | 'patched' | 'fixed' | 'gave-up'>
+  pending: Record<string, string>
+  log: Array<{ node: string; root: string; attempt: number; kind: string; reason?: string; message: string; gaveUp?: true }>
+}
+
+interface ComposeGenerated<D = {}, E = {}> {
+  readonly id: string
+  /** the catalog part: `defineCatalog({ parts: { custom: gen.part } })` */
+  readonly part: CatalogPartDecl
+  /** the part as a chat card's result part: the code's `type` event is the card's answer (render_component) */
+  card(type: keyof E & string): CatalogPartDecl
+  /** the part's component (CHILD.select(gen.Host) hears its reports) */
+  readonly Host: any
+  /** the prompt rules: compose.llm({ instructions: gen.instructions }) */
+  readonly instructions: string
+  /** the repair requests' instructions */
+  readonly repairInstructions: string
+  /** the host's intent: one declared event type of every generated part, validated */
+  events<K extends keyof E & string>(CHILD: any, type: K): Stream<GeneratedEvent<E, K>>
+  /** the repair loop: `uses = { fix: gen.repair({ maxAttempts: 2, model }) }` */
+  repair(options?: { maxAttempts?: number; model?: string }): Behavior$1<GeneratedRepairState, { REPLY: any; FAILED: any }>
+  readonly schemas: { [K in keyof E]: E[K] extends { schema: infer S } ? S : never }
+  readonly repairKey: string
 }
 
 /**
@@ -2459,6 +2554,192 @@ declare class MockedDOMSource {
 }
 declare function mockDOMSource(mockConfig: MockConfig, hub?: MockEventHub, onEvents?: MockOnEvents): MockedDOMSource;
 
+// Types for 'sygnal/replay' (7.2 dev preview). The implementation lives in src/extra/replay/;
+// the main entry re-exports these (replay() sits next to renderComponent).
+
+
+/** An action's cause in a recording: inputs i intent, r reply, n next, a simulateAction, B behavior, g agent, S setState; consequences b built-in, p parent */
+type RecordedCause = 'i' | 'r' | 'n' | 'a' | 'B' | 'g' | 'S' | 'b' | 'p'
+
+/** One action of a recording (RECORDING_SCHEMA has the details) */
+interface RecordedAction {
+  /** sequence number */
+  s: number
+  /** ms since the previous action kept (at enqueue) */
+  t: number
+  /** index into the recording's addresses (`p`) */
+  p: number
+  /** the action type */
+  y: string
+  c: RecordedCause
+  /** a reply's source (driver name) */
+  r?: string
+  /** the data (inputs only; events and elements as stubs) */
+  d?: unknown
+  /** the clock and randomness its handlers read, in order: ['now' | 'random' | 'uuid' | 'perf', value] */
+  e?: Array<[string, unknown]>
+  /** hash of the instance's new state, when its STATE changed */
+  h?: string
+  /** [sink, hash] of the values its other sinks produced */
+  f?: Array<[string, string]>
+}
+
+/** A recording, format version 1: plain JSON (save it with JSON.stringify) */
+interface Recording {
+  kind: 'sygnal-recording'
+  version: 1
+  /** the Sygnal version that recorded it (a replay on another version warns) */
+  sygnal: string
+  /** the root component's name */
+  app: string
+  /** ISO time the recording started */
+  recorded: string
+  /** typed text, server data and setState values pseudonymized; checkpoints masked */
+  redacted: boolean
+  /** component name -> the action names its model handled (a replay against code without one warns) */
+  components: Record<string, string[]>
+  /** the app's own sources: 'resources' (makeFetchDriver), 'timers' (makeTimerDriver), 'other' (an inert driver in the replay) */
+  sources: Record<string, 'resources' | 'timers' | 'other'>
+  /** the root state when the app started */
+  init: unknown
+  /** instance addresses: `App`, `App/Lane[lane-2]` (a Collection item), `App/Header:0` */
+  p: string[]
+  a: RecordedAction[]
+  /** checkpoints, one per patch: the last action's sequence number, the view's hash, the root state's diff */
+  k: Array<{ s: number; v: string; o?: unknown[]; html?: string }>
+  /** declaration statics sent to drivers: [seq, sink, hash] */
+  fx: Array<[number, string, string]>
+  end?: { s: number; ms: number; dropped: number; o?: unknown[] }
+}
+
+interface RecordOptions {
+  /**
+   * Default true. `true` or `{ keep, also }`: the strings of typed input (intent actions
+   * dispatched while a text-entry DOM event was delivered, and later actions of those types),
+   * server replies, setState values and the types in `also` are pseudonymized (same shape, equal
+   * strings stay equal); never the types in `keep`, nor next() data. Checkpoints are masked.
+   * A redacted string the model branches on makes the replay diverge there: add it to `keep`.
+   * `false`: nothing redacted.
+   */
+  redact?: boolean | { keep?: string[]; also?: string[] }
+  /** Default true: leave out inputs that changed nothing (an idle timer's ticks) */
+  dropNoops?: boolean
+  /** 'hash' (default), or 'html': checkpoints also keep the view's markup (for reports) */
+  vnodes?: 'hash' | 'html'
+}
+
+interface Recorder {
+  /** stop recording; the recording (undefined when no app started) */
+  stop(): Recording | undefined
+  /** the recording so far (the recording goes on) */
+  log(): Recording | undefined
+  /** an app is being recorded */
+  active(): boolean
+  /** a replay test for the recording so far: the test file, the recording's JSON and its file name */
+  test(options?: ReplayTestOptions): { code: string; recording: string; file: string }
+}
+
+/**
+ * Record the next app started (run() or renderComponent()) as a log of its input actions, the
+ * clock and randomness its handlers read, and a checkpoint per patch. Dev only: an app that never
+ * imports 'sygnal/replay' pays nothing.
+ */
+declare function startRecording(options?: RecordOptions): Recorder
+
+interface ReplayOptions {
+  /** drivers to use instead of the inert ones (by source name) */
+  drivers?: Record<string, any>
+  /** more renderComponent options */
+  render?: Record<string, any>
+  /** stop after this many checkpoints */
+  stopAt?: number
+  /** false: handlers read the real clock and randomness */
+  entropy?: boolean
+  /** false: no console.warn for version / name mismatches (they are in `warnings`) */
+  warn?: boolean
+}
+
+/** Where a replay first differs from the recording */
+interface ReplayDivergence {
+  s: number
+  type?: string
+  /** the instance's address */
+  path?: string
+  cause?: string
+  data?: unknown
+  reason: string
+  /** the checkpoint whose root state differs */
+  checkpoint?: number | 'end'
+  /** the root state's differences at that checkpoint: recorded (expected) vs now (actual) */
+  diff?: Array<{ path: string; expected: unknown; actual?: unknown; deleted?: true }>
+}
+
+interface ReplayResult<STATE = any> {
+  /** no divergence, view change, effect change, unresolved input or unhandled action */
+  ok: boolean
+  divergence: ReplayDivergence | null
+  /** the first checkpoint whose view differs while the state matches (a view-only change) */
+  view: { checkpoint: number; s: number; expected: string; actual: string; html: string; expectedHtml?: string } | null
+  /** actions whose sink values (requests, EVENTS, ...) differ: hashes, and the values sent now */
+  effects: Array<{ s: number; type: string; path: string; expected: Array<[string, string]>; actual: Array<[string, string]>; values: Array<[string, unknown]> }>
+  /** action types the code no longer handles */
+  unhandled: string[]
+  /** inputs whose instance never appeared */
+  unresolved: Array<{ s: number; type: string; path: string }>
+  /** recorded actions that didn't run, and actions that ran but weren't recorded */
+  missing: Array<{ s: number; type: string; path: string }>
+  extra: Array<{ type: string; path: string; cause: string }>
+  /** clock / randomness reads the replay had no recorded value for */
+  misses: string[]
+  /** Sygnal version, component or action names that differ from the recording's */
+  warnings: string[]
+  checkpoints: number
+  actions: number
+  /** the final root state */
+  final: STATE
+  /** the renderComponent handle (dispose it) */
+  t: RenderResult$1<STATE>
+}
+
+/**
+ * Replay a recording (the object, or its JSON) on `Component` in renderComponent: the recorded
+ * inputs go to the same instances in the same order, every handler gets the clock and randomness
+ * it read, and each action and checkpoint is compared with the recording.
+ */
+declare function replay<STATE = any>(Component: any, recording: Recording | string, options?: ReplayOptions): Promise<ReplayResult<STATE>>
+
+interface ReplayTestOptions {
+  /** the import line for the component (default `import <App> from './<App>.js'`) */
+  componentImport?: string
+  componentName?: string
+  /** the recording's path relative to the test (default `./<App>.recording.json`) */
+  logFile?: string
+  /** default 'sygnal/replay' */
+  replayImport?: string
+  /** more replay() options as source code: "drivers: { DND: myDriver }" */
+  replayOptions?: string
+  testName?: string
+  environment?: string
+}
+
+/** A Vitest file that replays the recording and asserts no divergence and the final state */
+declare function replayTest(recording: Recording, options?: ReplayTestOptions): string
+
+/** Markdown for a bug report: the timeline, what the replay found, how to reproduce */
+declare function bugReport(recording: Recording, result?: ReplayResult, options?: { title?: string; logName?: string; expected?: string }): string
+
+/** One line per recorded input: time, instance, type, cause, data */
+declare function timeline(recording: Recording, options?: { max?: number }): string[]
+
+/** The final root state the recording holds */
+declare function finalState(recording: Recording): unknown
+
+/** The recording format (version 1) as a JSON Schema */
+declare const RECORDING_SCHEMA: Record<string, unknown>
+
+/** A driver whose source accepts any call chain and never emits (a replay's stand-in for a recorded app's own drivers) */
+declare function inertDriver(): (sink$: any) => any
+
 declare const ABORT: unique symbol
 type ABORT = typeof ABORT
 /**
@@ -2525,8 +2806,11 @@ type StateProp = string | Lense<any, any>
  */
 type ElementProps<PROPS> =
   0 extends (1 & PROPS) ? PROPS
-  : 'state' extends keyof PROPS ? WithoutViewOnlyProps<PROPS> & { state?: StateProp; resetState?: boolean }
-  : PROPS
+  // PLAN-13 F-3: Switchable's own `state` (a per-page map too) is kept as it declares it
+  : PROPS extends { of: Record<string, any>; current: string } ? PROPS
+  : WithStateProp<PROPS>
+
+type WithStateProp<PROPS> = 'state' extends keyof PROPS ? WithoutViewOnlyProps<PROPS> & { state?: StateProp; resetState?: boolean } : PROPS
 
 /** PROPS without `state`, `context`, `slots` and `uid` (keeps optionality and index signatures, unlike Omit). */
 type WithoutViewOnlyProps<PROPS> = {
@@ -2547,7 +2831,21 @@ type NextFunction<ACTIONS = any> = ACTIONS extends object
  * `state` (and as its 1st argument), with the state from before the action as `previousState`
  * (in a STATE reducer both are the old state)
  */
-type ReducerExtras<PROPS, CONTEXT, STATE = any> = PROPS & { state: STATE; previousState: STATE; context: CONTEXT; children?: JSX.Element | JSX.Element[]; slots?: Record<string, JSX.Element[]>; uid: UidFunction }
+/**
+ * 7.2: the clock and randomness on a handler's 4th argument, the canonical form for reading them
+ * (instead of Date.now(), Math.random(), crypto.randomUUID(): SYG258 / SYG509). renderComponent
+ * can fix them (`now`, `random`, `uuid` options) and a replay supplies the recorded values. A
+ * component prop of the same name wins.
+ */
+interface HandlerEntropy {
+  /** Date.now() */
+  now(): number
+  /** Math.random() */
+  random(): number
+  /** crypto.randomUUID() */
+  uuid(): string
+}
+type ReducerExtras<PROPS, CONTEXT, STATE = any> = Omit<HandlerEntropy, keyof PROPS> & PROPS & { state: STATE; previousState: STATE; context: CONTEXT; children?: JSX.Element | JSX.Element[]; slots?: Record<string, JSX.Element[]>; uid: UidFunction }
 
 type Reducer<STATE, PROPS, ACTIONS = any, DATA = any, RETURN = any, CONTEXT = {}> = (
   state: STATE,
@@ -2803,7 +3101,8 @@ type ChildSource = {
 /**
  * `DOM.<event>(selector)` shorthands for the standard DOM events, typed like
  * `DOM.select(selector).events('<event>')`: `DOM.keydown('.x')` is a stream of KeyboardEvent,
- * `DOM.click('.x')` of MouseEvent (PointerEvent in newer DOM typings), and so on.
+ * `DOM.click('.x')` of MouseEvent (PointerEvent in newer DOM typings), and so on. A second argument
+ * is the events() options: `DOM.submit('form', { preventDefault: true })`.
  */
 type DOMEventShorthands = {
   [EVENT in Exclude<keyof HTMLElementEventMap, keyof MainDOMSource>]: DOMEventShorthand<HTMLElementEventMap[EVENT]>
@@ -2814,9 +3113,9 @@ type DOMEventShorthands = {
  * the event with `currentTarget` (and `ownerTarget`) typed as the control's element.
  */
 interface DOMEventShorthand<EVENT> {
-  <CONTROL extends AnyControl>(control: CONTROL): EnrichedEventStream<ControlEvent<EVENT, ControlElementOf<CONTROL>>>
+  <CONTROL extends AnyControl>(control: CONTROL, options?: EventsFnOptions): EnrichedEventStream<ControlEvent<EVENT, ControlElementOf<CONTROL>>>
   // last, so ReturnType<SygnalDOMSource['click']> stays the selector form
-  (selector: string): EnrichedEventStream<EVENT>
+  (selector: string, options?: EventsFnOptions): EnrichedEventStream<EVENT>
 }
 
 /**
@@ -3055,8 +3354,60 @@ type WidgetEmit<EV extends string = string> = WidgetDispatch<EV>
 interface WidgetDefinition<P = {}, I = unknown, EV extends string = string, TAG extends string = 'div'> {
   /** A name for diagnostics and inspect() (`'DatePicker'`); the host tag stands in without one */
   name?: string;
-  /** The host element (default `'div'`). It has no children of its own: the widget owns its content. */
+  /** The host element (default `'div'`). Without `children`, it has no children of its own: the widget owns its content. */
   tag?: TAG;
+  /**
+   * Declarative children (an "island": a WebGL scene's objects, a map's markers, a chart's
+   * series). The tag's JSX children are rendered by the app's DOM driver into a container in
+   * the host (`[data-widget-children]`), as ordinary elements: components, `<Collection>`,
+   * isolation and intents work inside. `sync` gets them; the widget paints them its own way and
+   * dispatches DOM events on them. `true`: the container is visually hidden but in the
+   * accessibility tree (Enter / Space on a focused child is its `click`; `focus` is told);
+   * `'hidden'`: hidden from everything.
+   */
+  children?: true | 'hidden';
+  /**
+   * With `children`: called after mount and after each patch in which the children's vnodes
+   * changed, with the children container's patched vnode (each child's props as the view wrote
+   * them, in `data.props` / `data.attrs`, and its element in `.elm`).
+   */
+  sync?(instance: I, children: VNode, el: WidgetElementOf<TAG>): void;
+  /** With `children`: a child got keyboard focus (`null`: none has it); draw a focus ring where it is */
+  focus?(instance: I, child: Element | null, el: WidgetElementOf<TAG>): void;
+  /**
+   * Tags of the widget's children vocabulary that are SVG tags to the JSX pragma (`marker`,
+   * `line`, `text`): they become plain elements app-wide (props stay props). Children of a
+   * literal `<svg>` in the same template are still SVG.
+   */
+  tags?: readonly string[];
+  /**
+   * Experimental (7.2): the widget carries a value both the app and the user change (an
+   * editor's text, a camera, a map's viewport). The `value` prop is controlled: `write` is
+   * called only when the app changed it to something the widget didn't report itself (no echo
+   * loops, no stale writes); the widget reports its own changes with `dispatch(event, value)`
+   * (`event` default `'change'`). With `strict` (here, or the `strict` prop), an edit the model
+   * didn't take (the prop never moved) is written back after the app's turn. `read` makes the
+   * host's `value` the widget's (`.value()` in intents). `update` is not called for `value` alone.
+   */
+  value?: {
+    write(instance: I, value: any, el: WidgetElementOf<TAG>): void;
+    read?(instance: I, el: WidgetElementOf<TAG>): any;
+    equals?(a: any, b: any): boolean;
+    event?: NoInfer<EV>;
+    strict?: boolean;
+  };
+  /**
+   * The widget is a form field named by its `name` prop (the widget field contract): when it
+   * dispatches `event` (default: `value.event`, else `'change'`), its host also fires a bubbling
+   * `input` event, which the `form` behavior reads as the field's new value (the event's detail);
+   * the focus leaving the host marks the field touched; processForm entries get `read()` (default:
+   * the last value dispatched, else the `value` prop). Its own nameless controls' `input` events
+   * don't count. `true`: the defaults.
+   */
+  field?: true | {
+    event?: NoInfer<EV>;
+    read?(instance: I, el: WidgetElementOf<TAG>): any;
+  };
   /**
    * Called once the host is in the document (or on the first client patch after SSR) with the
    * props the view passed. Returns the instance that `update`, `unmount` and `commands` get.
@@ -3090,7 +3441,8 @@ interface WidgetDefinition<P = {}, I = unknown, EV extends string = string, TAG
  * (`controls({ Due: DatePicker })`, the alternative form).
  */
 interface Widget<P = {}, I = unknown, EV extends string = string, TAG extends string = string> extends ControlSpecObject<P & WidgetHostProps> {
-  (props: P & WidgetHostProps): JSX.Element;
+  /** (JSX children: rendered for a widget with `children`, ignored otherwise) */
+  (props: P & WidgetHostProps & { children?: unknown }): JSX.Element;
   readonly kind: 'widget';
   /** The declared events */
   readonly events: readonly EV[];
@@ -3123,6 +3475,22 @@ interface Widget<P = {}, I = unknown, EV extends string = string, TAG extends st
  */
 declare function defineWidget<P = {}, I = unknown, const EV extends string = string, const TAG extends string = 'div'>(definition: WidgetDefinition<P, I, EV, TAG>): Widget<P, I, EV, TAG>
 
+/**
+ * Keyboard shortcuts as named action streams (7.2):
+ *
+ *   App.intent = ({ DOM }) => ({ ...keymap(DOM, { 'mod+z': 'UNDO', 'shift+mod+z': 'REDO', delete: 'DELETE', left: ['NUDGE', { dx: -1 }] }) })
+ *
+ * A combo is modifiers (`mod` = ⌘ or Ctrl, `ctrl`, `meta`, `shift`, `alt`) then a key (`e.key`
+ * lower-cased; `left` `right` `up` `down` `del` `esc` `space` aliases; digits by `e.code`), and
+ * matches only its own modifiers. A value is an action name (its stream emits `undefined`) or
+ * `[name, data]`. Matched keys are default-prevented; nothing fires while typing in a field.
+ */
+declare function keymap<const T extends Record<string, string | readonly [string, any]>>(
+  DOM: { select(selector: string): any },
+  table: T,
+  options?: { on?: string },
+): { [K in T[keyof T] extends infer V ? V extends readonly [infer N extends string, any] ? N : V extends string ? V : never : never]: Stream<any> }
+
 /**
  * The target of an element command: a control, or a selector. It is looked up in the view of the
  * component instance that sends the command (a child's elements are isolated from its parent; a
@@ -3255,6 +3623,11 @@ interface BehaviorDefinition<SLICE = any, ACTIONS = {}, CALCULATED = {}, OPTIONS
    * name is sent to the host as written. They join the host's own `timers`.
    */
   timers?: (slice: SLICE, options: OPTIONS, key: string) => Timers;
+  /**
+   * ui-sweep R1: the option each action's trigger is built from (`{ TOGGLE: 'toggle' }`). Dev
+   * only: SYG118 when a host intent action of that name replaces it while the host passes the option.
+   */
+  triggers?: { [A in keyof ACTIONS]?: keyof OPTIONS & string };
   /** `false`: the slice is UI state (sortable's drag): a root's `persist()` neither saves nor restores it (the root's own `uses` only: a sub-component's or Collection item's slice is saved with its data) */
   persist?: false;
   /**
@@ -3473,7 +3846,8 @@ interface FormOptions<V = any, OUT = any> {
    * function of the schema's output and the host's state (`(data, state) => ({ url: '/api/items/' + state.id, method: 'PUT' })`;
    * `ABORT` / falsy sends nothing and leaves the submit pending). The form adds the body
    * (`multipart: data` when a top-level value is a File or files, else `json: data`, unless the
-   * request sets `json`, `multipart` or `body`), `progress: 'form.PROGRESS'` (unless set) and its own
+   * request sets `json`, `multipart` or `body`), `progress: 'form.PROGRESS'` for a multipart submit or
+   * `progress: true` (a JSON submit stays on fetch: progress goes over XMLHttpRequest) and its own
    * `ok: 'form.DONE'`, `error: 'form.ERRORS'`
    */
   request?: FormRequest<OUT>;
@@ -3517,8 +3891,8 @@ type FormServerErrors =
   | { status?: number; body?: any; error?: any; request?: any }
 
 interface FormActions<V = any> {
-  /** A field changed (the form element's input events): `{ name, value }`; a checkbox gives `checked` as `value` and its own value as `item` (on an array field: added or removed); a file input its File (`multiple`: File[]; none: null) */
-  CHANGE: { name: string; value: any; item?: any; file?: boolean };
+  /** A field changed (the form element's input events): `{ name, value }`; a checkbox gives `checked` as `value` and its own value as `item` (on an array field: added or removed, kept in document order: 7.2) and as `order` its group's values as rendered; a file input its File (`multiple`: File[]; none: null) */
+  CHANGE: { name: string; value: any; item?: any; order?: ReadonlyArray<string>; file?: boolean };
   /**
    * Several fields at once, by field name (`{ values: { name: 'Dana', 'addresses.7.city': 'Hilo' } }`),
    * as if typed: one validation, `touched` as for CHANGE, their server errors and check results
@@ -4016,10 +4390,12 @@ type Component<
    * actions on this instance; send with `{ to: 'room', json }` from a model entry (a connection
    * the same action opens or changes is declared first). Dispose closes them.
    */
-  connections?: (state: STATE & CALCULATED) => Connections;
+  connections?: (state: STATE & CALCULATED, context: CONTEXT) => Connections;
   /**
    * PLAN-3: declarative reads (`makeFetchDriver()`). Each entry derives a
-   * request from state; falsy means idle:
+   * request from state (and, PLAN-13 F-1, the context as its second argument, as every
+   * declaration static: `(state, { route }) => '/api/items/' + route.params.id`; re-run when the
+   * context changes); falsy means idle:
    * `Quote.resources = { quote: (state) => state.id && '/api/quotes/' + state.id }`.
    * `state.quote` is a `Resource`: `{ status: 'idle' | 'loading' | 'success' | 'error', data,
    * error, refreshing }`, written by the built-in RESOURCE action (idle until the first request).
@@ -4029,7 +4405,7 @@ type Component<
    * `data`, `error` and `status` and sets `refreshing: true` (D78). `ok` / `error` on the
    * request also dispatch those actions after the write.
    */
-  resources?: { [name: string]: (state: STATE & CALCULATED) => ResourceRequest | false | null | undefined | '' | 0 };
+  resources?: { [name: string]: (state: STATE & CALCULATED, context: CONTEXT) => ResourceRequest | false | null | undefined | '' | 0 };
   /**
    * The router's reply action (`makeRouter()`): `App.route = 'ROUTE'`. The driver sends this
    * instance ROUTE with the `Route` (`{ name, params, query, hash, path }`) once declared and on
@@ -4051,7 +4427,7 @@ type Component<
    * `renderToString(App, { head: list })` for SSR (`renderHead(list)`). Like every declaration
    * static, it is sent with or without a model; a root needs `initialState` (SYG132).
    */
-  head?: (state: STATE & CALCULATED) => HeadValue | false | null | undefined;
+  head?: (state: STATE & CALCULATED, context: CONTEXT) => HeadValue | false | null | undefined;
   /**
    * PLAN-4 GS-1: behaviors this component uses, each under its state key:
    * `TaskList.uses = { pager: pager({ pageSize: 10, next: Newer, prev: Older }) }` gives
@@ -4068,7 +4444,7 @@ type Component<
    * fires once (`{ t }`), `frame` runs every animation frame (`{ t, dt }`). A hidden Switchable
    * page's timers stop unless `background: true`; dispose stops them; nothing runs during SSR.
    */
-  timers?: (state: STATE & CALCULATED) => Timers<ActionNameOf<ACTIONS>>;
+  timers?: (state: STATE & CALCULATED, context: CONTEXT) => Timers<ActionNameOf<ACTIONS>>;
   /**
    * PLAN-5 B-3: browser sources derived from state, run by `makeBrowserDriver()` (registered:
    * `run(App, { BROWSER: makeBrowserDriver() })`; renderComponent provides a fake, `t.browser`)
@@ -4078,7 +4454,7 @@ type Component<
    * restarts. A hidden Switchable page's sources stop unless `background: true`; dispose stops
    * them; nothing runs during SSR.
    */
-  browser?: (state: STATE & CALCULATED) => BrowserSources<ActionNameOf<ACTIONS>>;
+  browser?: (state: STATE & CALCULATED, context: CONTEXT) => BrowserSources<ActionNameOf<ACTIONS>>;
   /**
    * PLAN-4 GS-5: save this root component's state and restore it at startup:
    * `TodoApp.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'] })`. `pick` / `omit`
@@ -4201,8 +4577,8 @@ type VirtualCollectionProps<PROPS = any, STATE = any> = {
 /** Where `scrollToIndex` / `scrollToId` put the row: 'auto' (default) scrolls only when it isn't in view */
 type ScrollToAlign = 'auto' | 'start' | 'center' | 'end'
 
-type SwitchableProps<PROPS = any> = {
-  of: Record<string, AnyComponent>;
+type SwitchableProps<PROPS = any, OF extends Record<string, AnyComponent> = Record<string, AnyComponent>> = {
+  of: OF;
   current: string;
   /**
    * The current page's instance key. When it changes, the current page is disposed and created
@@ -4210,7 +4586,14 @@ type SwitchableProps<PROPS = any> = {
    * show. Switching `current` alone keeps pages alive. Router recipe: `instance={state.route.path}`
    */
   instance?: string | number;
-  state?: string | Lense;
+  /**
+   * The pages' state: a key or path (`'pages'`), a lens, or (PLAN-13 F-3) a map from page names to
+   * those (`{ projects: 'pages.projects', settings: byId('teams', state.teamId) }`): each listed
+   * page binds its own target with a tag child's lifetime rules (another key or id makes that page
+   * again, a deleted target disposes it), and the pages not listed share the owner's state. A key
+   * that names no page is SYG429
+   */
+  state?: string | Lense | { [PAGE in keyof NoInfer<OF>]?: string | Lense };
 } & Omit<PROPS, 'of' | 'state' | 'current' | 'instance'>
 
 type PortalProps = {
@@ -4554,7 +4937,12 @@ type FormSource = {
   events(eventName: string, ...args: any[]): Stream<any>
 }
 
-type FormData<FIELDS extends Record<string, string> = Record<string, string>> = FIELDS & {
+/**
+ * processForm's entries: a field's string (a file input: its File); a `<select multiple>`, checkboxes
+ * sharing a name (7.2) and a multiple widget field an array of their values; declare those in
+ * FIELDS: `{ tags: string[] }`
+ */
+type FormData<FIELDS extends Record<string, any> = Record<string, string>> = FIELDS & {
   event: globalThis.Event;
   eventType: string;
 }
@@ -4578,7 +4966,7 @@ type ProcessFormOptions = {
  * // form$ is Stream<FormData<{ username: string; email: string }>>
  * // form$.username is typed as string ✓
  */
-declare function processForm<FIELDS extends Record<string, string> = Record<string, string>>(
+declare function processForm<FIELDS extends Record<string, any> = Record<string, string>>(
   target: FormSource,
   options?: ProcessFormOptions
 ): Stream<FormData<FIELDS>>
@@ -4692,7 +5080,7 @@ declare function Collection<PROPS extends { [prop: string]: any }, STATE = any>(
  *   <VirtualCollection of={Row} from="rows" className="rows" estimateSize={32} />
  */
 declare function VirtualCollection<PROPS extends { [prop: string]: any }, STATE = any>(props: VirtualCollectionProps<PROPS, STATE>): JSX.Element
-declare function Switchable<PROPS extends { [prop: string]: any }>(props: SwitchableProps<PROPS>): JSX.Element
+declare function Switchable<PROPS extends { [prop: string]: any }, OF extends Record<string, AnyComponent> = Record<string, AnyComponent>>(props: SwitchableProps<PROPS, OF>): JSX.Element
 declare function Portal(props: PortalProps): JSX.Element
 declare function Transition(props: TransitionProps): JSX.Element
 declare function Suspense(props: SuspenseProps): JSX.Element
@@ -4753,6 +5141,48 @@ type ReplyRequest = {
   catch?: never;
 }
 
+declare const replySenderBrand: unique symbol
+/**
+ * The component instance that sent a request to a driver (opaque). `senderOf(request)` reads it;
+ * pass it to `reply()` to answer that instance with one of its actions.
+ */
+type ReplySender = { readonly [replySenderBrand]: true }
+
+/** What makeReplies() returns: the source part that marks the driver, and the way to answer */
+type ReplyChannel = {
+  /**
+   * Spread into the driver's source (`return { ...replies, select }`): the core then stamps each
+   * request a component sends with its sender and delivers `reply()`s as that instance's actions.
+   */
+  replies: { readonly __sygnalReplies: true; replies(sender: ReplySender): Stream<{ type: string; data: any }> };
+  /** Dispatch `type` with `data` on the sender (dropped when it is gone). Call it as often as needed */
+  reply(sender: ReplySender, type: string, data?: any): void;
+  /** Whether the sender is still mounted (a reply would reach it) */
+  listening(sender: ReplySender): boolean;
+}
+
+/**
+ * PLAN-13 D-1: reply actions for a driver you write (the protocol makeFetchDriver,
+ * driverFromAsync and the socket driver use). `onStop(sender)` runs when a sender is disposed:
+ * abort what it still has in flight.
+ *
+ *   const { replies, reply } = makeReplies((sender) => inflight.get(sender)?.abort())
+ *   sink$.addListener({ next: (req) => {
+ *     const sender = senderOf(req)
+ *     if (sender === undefined) return                    // not sent by a component
+ *     run(req, (f) => req.progress && reply(sender, req.progress, f))
+ *       .then((v) => req.ok && reply(sender, req.ok, v), (error) => req.error && reply(sender, req.error, { error, request: req }))
+ *   } })
+ *   return { ...replies }
+ *
+ * A name with no model entry on the sender is SYG112 in the dev entry (ok / error / progress
+ * statically). Guide: https://sygnal.js.org/guide/custom-drivers/
+ */
+declare function makeReplies(onStop?: (sender: ReplySender) => void): ReplyChannel
+
+/** The component instance that sent `request` to a driver with reply actions, or undefined (not sent by a component) */
+declare function senderOf(request: object): ReplySender | undefined
+
 /**
  * A request to a driverFromAsync() sink: your own fields (`value`, the args, ...) plus the
  * reply-action keys `ok` / `error`. Type the driver's sink with it: `{ QUOTE: { source:
@@ -5228,6 +5658,15 @@ type SocketActions = {
    * hidden page's connections close, and open again as new ones when it is shown)
    */
   background?: boolean;
+  /**
+   * PLAN-13 S-1: a connection that stays silent this long (ms) is taken as dead (a half-open
+   * socket behind a proxy): it is closed as a drop, `close` gets `{ stale: true, willReconnect }`,
+   * and the reconnect policy applies. Every event counts; over fetch (an `sse` with `headers`)
+   * any bytes do, heartbeat comments (`: ping`) included, while the native EventSource needs a
+   * real event (a `message`, or a named event listed in `events`). Set it above the server's
+   * heartbeat interval
+   */
+  staleAfterMs?: number;
   /** Not allowed: a `then` key makes the value a thenable (SYG610). Use `message` / `open` */
   then?: never;
   catch?: never;
@@ -5254,6 +5693,29 @@ type SseConnection = SocketActions & {
   headers?: Record<string, string>;
   /** Named events → actions: `{ 'price-update': 'PRICE' }` (data JSON-parsed when it parses) */
   events?: Record<string, string>;
+  /**
+   * PLAN-13 S-1: the `message` and `events` actions get `SseEvent` (`{ data, id, event }`: the
+   * event id and type) instead of the data alone
+   */
+  meta?: boolean;
+  /**
+   * PLAN-13 S-1: resume after a reconnect the driver makes (EventSource gave up: a proxy 502, a
+   * non-2xx on the `headers` path) from the last event id. Over fetch (`headers`) it is sent as
+   * `Last-Event-ID`; the native EventSource can't send it, so it goes on the URL:
+   * `?lastEventId=<id>` (`true`) or `?<name>=<id>` (a parameter name). EventSource's own retries
+   * send `Last-Event-ID` anyway
+   */
+  resume?: true | string;
+}
+
+/** PLAN-13 S-1: an SSE event as a `meta: true` connection's actions get it */
+type SseEvent<DATA = any> = {
+  /** The data, JSON-parsed when it parses */
+  data: DATA;
+  /** The event's `id:` (the last one sent when this event has none; '' when there was none) */
+  id: string;
+  /** The event type: 'message', or the named event's name */
+  event: string;
 }
 
 /**
@@ -5279,7 +5741,7 @@ type SocketRequest =
 /** Data of a connection's `open` action */
 type SocketOpen = { reconnected: boolean }
 /** Data of a connection's `close` action (SSE: no code / reason) */
-type SocketClose = { code?: number; reason?: string; willReconnect: boolean }
+type SocketClose = { code?: number; reason?: string; willReconnect: boolean; /** PLAN-13 S-1: closed by staleAfterMs (nothing arrived) */ stale?: true }
 /** Data of a connection's `error` action: the error Event (or the constructor's exception) */
 type SocketError = { error: any }
 
@@ -5464,11 +5926,16 @@ declare function makeHeadDriver(options?: { titleTemplate?: string; document?: a
  * `after`: once, after ms (0 or more); `frame`: every animation frame (requestAnimationFrame,
  * else every 16 ms). `background: true` keeps it running while its Switchable page is hidden.
  * An invalid spec is not started (SYG422 in dev).
+ *
+ * A `frame` timer for a game (canvas-game R2): `keys` samples the keyboard with each frame
+ * (`{ left: ['ArrowLeft', 'KeyA'], jump: 'Space' }`, KeyboardEvent codes or keys; the data gets
+ * `held`, `pressed`, `released`: TimerFrameInput), and `step` (ms) makes it a fixed timestep: one
+ * action per whole step the frame time owes, at most `max` (default 5) a frame.
  */
 type TimerSpec<ACTION extends string = string> =
   | { every: number; action: ACTION; background?: boolean; after?: never; frame?: never }
   | { after: number; action: ACTION; background?: boolean; every?: never; frame?: never }
-  | { frame: ACTION; background?: boolean; every?: never; after?: never; action?: never }
+  | { frame: ACTION; keys?: Record<string, string | readonly string[]>; step?: number; max?: number; background?: boolean; every?: never; after?: never; action?: never }
 
 /** A component's whole set of timers, by name: a falsy entry (`state.running && { ... }`) is stopped */
 type Timers<ACTION extends string = string> = { [name: string]: TimerSpec<ACTION> | false | null | undefined | 0 | '' }
@@ -5477,8 +5944,21 @@ type Timers<ACTION extends string = string> = { [name: string]: TimerSpec<ACTION
 interface TimerTick { n: number; t: number }
 /** The data of an `after` timer's action: Date.now() */
 interface TimerAfter { t: number }
-/** The data of a `frame` timer's action: Date.now() and the ms since the previous frame (0 on the first) */
-interface TimerFrame { t: number; dt: number }
+/**
+ * The data of a `frame` timer's action: Date.now() and the ms since the previous frame (0 on the
+ * first); with `step`, `dt` is the step and `steps` / `i` say how many steps this frame sends and
+ * which one this is; with `keys`, the input (TimerFrameInput)
+ */
+interface TimerFrame<BUTTON extends string = string> extends Partial<TimerFrameInput<BUTTON>> { t: number; dt: number; steps?: number; i?: number }
+/**
+ * A `frame` timer's sampled keys: `held` (every button, true while one of its keys is down; the
+ * same object while nothing changed), `pressed` / `released` (the buttons that went down / up since
+ * the last frame, so a tap shorter than a frame counts; with `step`, on the frame's first step).
+ * Listened for on the document while the timer runs: the keys are default-prevented (repeats
+ * ignored), not while a text field has the focus; the window losing focus or the page hiding
+ * releases every button.
+ */
+interface TimerFrameInput<BUTTON extends string = string> { held: Record<BUTTON, boolean>; pressed: BUTTON[]; released: BUTTON[] }
 
 /**
  * PLAN-4 GS-7: runs the components' `timers` statics: `run(App, { TIMER: makeTimerDriver() })`.
@@ -5628,6 +6108,14 @@ interface InstallPrompt {
 
 declare function createInstallPrompt(): InstallPrompt
 
+/** Which instance t.simulateAction() sends to (default: the rendered component) */
+interface SimulateActionOptions {
+  /** The first rendered instance of this component (or its name) */
+  component?: AnyComponent | string;
+  /** Only an instance rendered inside the first element matching this selector or control (a Collection item) */
+  within?: string | AnyControl;
+}
+
 interface SimulatedEventInit {
   /** Merged into `event.target` (value, checked, dataset, ...) */
   target?: Record<string, any>;
@@ -5641,6 +6129,12 @@ interface SimulatedEventInit {
   data?: Record<string, any>;
   /** Keyboard key (e.key) */
   key?: string;
+  /**
+   * Shorthand for target.files: the files a file input holds. The target gets them as a FileList
+   * (with `dom: 'real'` a real one where the environment has DataTransfer, else defined on the
+   * element): `t.simulateEvent('[name="avatar"]', 'input', { files: [new File(['…'], 'me.png')] })`
+   */
+  files?: ArrayLike<File> | File[];
   /**
    * Don't fail when the selector matches no rendered element: wait up to 300ms for it, then
    * drop the event with SYG103 (info). Not copied onto the event.
@@ -5739,6 +6233,23 @@ interface RenderOptions {
   timingAudit?: boolean;
   /** Override initial state (defaults to component's .initialState) */
   initialState?: any;
+  /**
+   * 7.2: what handlers' `now()` (4th argument) returns: a number fixes the clock at that time (ms
+   * since the epoch, or a Date), a function is called each time. Default: Date.now() (fake timers
+   * apply)
+   */
+  now?: number | Date | (() => number);
+  /**
+   * 7.2: what handlers' `random()` returns: a number seeds a deterministic generator (the same
+   * sequence on every run), a function is called each time. Default: Math.random()
+   */
+  random?: number | (() => number);
+  /**
+   * 7.2: what handlers' `uuid()` returns: `true` gives deterministic UUID-shaped ids in order
+   * (`00000000-0000-4000-8000-000000000001`, `…002`, ...), a function is called each time.
+   * Default: crypto.randomUUID()
+   */
+  uuid?: true | (() => string);
   /**
    * D214: context from the ancestors the rendered component would have, for testing a child
    * alone: `renderComponent(Greeting, { context: { lang: 'fr' } })`. The view, reducers and
@@ -5957,16 +6468,32 @@ interface RenderResult<STATE = any> {
   sinks: Record<string, any>;
   /** All source objects by driver name */
   sources: Record<string, any>;
-  /** Push an action into the intent→model pipeline under its real name (all sinks of the entry run) */
-  simulateAction: (actionName: string, data?: any) => void;
+  /**
+   * Push an action into the intent→model pipeline under its real name (all sinks of the entry run),
+   * like the component's intent emitting it. It reaches one instance: the rendered component, or
+   * with `{ component: Child }` the first rendered instance of `Child` (`within`: inside the first
+   * element matching a selector or control, e.g. one Collection item). A name that instance has no
+   * model entry for (nor a behavior action or a built-in) fails the test, naming the components
+   * that handle it: `t.simulateAction('INFER_FILE', file, { component: Start })`. Awaitable:
+   * resolves once the action is delivered and the tree has rendered it
+   */
+  simulateAction: (actionName: string, data?: any, options?: SimulateActionOptions) => Promise<void>;
+  /**
+   * Wait for `n` frames (default 1) of the running `frame` timers: their actions reduced, the tree
+   * rendered. Under fake timers it moves the clock frame by frame (deterministic: the same input,
+   * the same frames); with real timers it waits for them. Rejects when no frame timer runs.
+   * `settle()` doesn't wait on a frame loop: what a frame timer causes isn't activity.
+   */
+  frames: (n?: number) => Promise<void>;
   /**
    * Dispatch a synthetic DOM event through the mock DOM source so the component's real intent
    * streams fire (DOM.click('.x'), DOM.select('.x').events('click'), .value(), .data()).
    * Targets the first rendered element matching `selector` and bubbles within its isolation scope.
    * Selectors match the rendered tree like the real DOM: tag, .class, #id, [attr], [attr="v"]
    * (^= $= *= ~=), :first-child, :last-child, :only-child, :nth-child(an+b|odd|even),
-   * :nth-last-child(), :first/last/only/nth-of-type, :not(), descendant ' ' and child '>'
-   * combinators, ',' lists. Other syntax (:has(), '+', '~', pseudo-elements...) throws.
+   * :nth-last-child(), :first/last/only/nth-of-type, :not(), descendant ' ', child '>',
+   * next-sibling '+' and later-sibling '~' combinators, ',' lists. Other syntax (:has(),
+   * pseudo-elements...) throws.
    * If nothing matches yet, the event waits (up to 300ms, re-checked on every render) for a
    * matching element, then targets the first one. If none renders, the test fails with an
    * error naming the selector: it rejects the pending next()/waitForState()/settle(), or is
@@ -5977,8 +6504,15 @@ interface RenderResult<STATE = any> {
    * `'document'` / `'body'` go to the DOM.select('document' | 'body') listeners.
    * simulateAction/simulateEvent calls are delivered in call order; a waiting event holds the
    * calls after it. Reports SYG104 (selector only matches inside a child component).
+   *
+   * The event is delivered later, not during the call, so `t.query()` / `t.html()` right after it
+   * still show the old view. The returned promise resolves once the event is delivered and the
+   * tree has rendered what it caused (the real DOM: patched): `await t.simulateEvent('.retry',
+   * 'click')`, then `t.query('.skeleton')`. It never rejects (a selector that matches nothing still
+   * fails the next wait), and awaiting it moves fake timers like the other waits; an un-awaited
+   * call doesn't. A `t.next(pred)` after it waits for a further state.
    */
-  simulateEvent: (selector: string | AnyControl, eventType: string, eventInit?: SimulatedEventInit) => void;
+  simulateEvent: (selector: string | AnyControl, eventType: string, eventInit?: SimulatedEventInit) => Promise<void>;
   /**
    * Resolves once the component is subscribed (earlier simulate* calls are buffered and replayed).
    * Also a cursor: the first next() after `await t.ready()` also matches the states the replayed
@@ -6101,9 +6635,10 @@ interface RenderResult<STATE = any> {
   open: (sinkName: string, target?: FakeConnectionTarget) => Promise<void>;
   /**
    * The server sends `data` (objects as JSON text) on open connection(s): `message` fires with
-   * the data, JSON-parsed when it parses. `{ event, connection? }` sends an SSE named event.
+   * the data, JSON-parsed when it parses. `{ event, connection? }` sends an SSE named event;
+   * `{ id }` gives an SSE event its id (what `meta: true` reports and `resume` resumes from).
    */
-  push: (sinkName: string, data: any, target?: FakeConnectionTarget | { event?: string; connection?: FakeConnectionTarget }) => Promise<void>;
+  push: (sinkName: string, data: any, target?: FakeConnectionTarget | { event?: string; id?: string | number; connection?: FakeConnectionTarget }) => Promise<void>;
   /**
    * Connection(s) close without the app closing them: `close` fires with `{ code, reason,
    * willReconnect }` (default `{ code: 1006, reason: '' }`; a connecting one fails to open: `error`
@@ -6196,16 +6731,21 @@ interface RenderResult<STATE = any> {
    * null: `expect(t.query('input[name="plan"]:checked').value).toBe('team')`. With `dom: 'real'`
    * a real element (any CSS selector); with the mock DOM a read-only snapshot of what the view
    * rendered (simulateEvent's selectors plus `:checked`/`:disabled`/`:enabled`; textContent,
-   * value, checked, disabled, getAttribute, classList, dataset, querySelector, closest...; no
-   * focus()). Throws before the first render (`await t.ready()` first). Right after
-   * `await t.next(pred)` / `waitForState` / `settle()` / `ready()` it shows the state the wait resolved with.
+   * value, checked, disabled, getAttribute, classList, dataset, querySelector, closest,
+   * next/previousElementSibling...; no focus()). Throws before the first render (`await t.ready()`
+   * first). Right after `await t.next(pred)` / `waitForState` / `settle()` / `ready()` /
+   * `simulateEvent()` it shows the state the wait resolved with.
    */
   query: {
     <E extends Element = Element>(selector: string): E | null;
     /** A control's element (`t.query(Draft)` is an HTMLInputElement for an 'input' control), or null */
     <CONTROL extends AnyControl>(control: CONTROL): ControlElementOf<CONTROL> | null;
   };
-  /** Every element matching a selector (or a control) in the rendered tree (Portals included), as query() */
+  /**
+   * Every element matching a selector (or a control) in the rendered tree (Portals included), as
+   * query(), in document order, also for a ',' list: `t.queryAll('.empty, .filters')` lists
+   * whichever comes first first (an order check)
+   */
   queryAll: {
     <E extends Element = Element>(selector: string): E[];
     <CONTROL extends AnyControl>(control: CONTROL): Array<ControlElementOf<CONTROL>>;
@@ -6374,4 +6914,4 @@ declare global {
  */
 declare function byId<T = any, S = any>(field: string, id: unknown, idKey?: string): { get(state: S): T | undefined; set(state: S, value: T): S }
 
-export { ABORT, type ActionCause, type ActionsOf, type ActiveTimer, type AgentAction, type AgentConfirm, type AgentConfirmInfo, type AgentDeclaration, type AgentIssue, type AgentQuery, type AgentQueryResult, type AgentResult, type AgentSchema, type AgentTool, type AgentToolSet, type AgentToolsOptions, type AguiOptions, type AnswerPick, type AnswerPicks, type AnthropicMessagesOptions, type AnyComponentModule, type AnyControl, type AppErrorHook, type AppErrorInfo, type AppErrorPhase, type ArrayKeysOf, type ArrayPathsOf, type AsyncDriverError, type AsyncDriverFromFunction, type AsyncRequest, type Behavior, type BehaviorDefinition, type BehaviorFactory, type BehaviorHandler, type BehaviorModelEntry, type BehaviorProps, type BehaviorSources, type BehaviorState, type BehaviorTarget, type BrowserCommand, type BrowserFake, type BrowserFakeOptions, type BrowserIntersection, type BrowserPosition, type BrowserResize, type BrowserSource, type BrowserSources, type BrowserSpec, type Catalog, type CatalogContainer, type CatalogContainerDecl, type CatalogDecl, type CatalogOption, type CatalogParam, type CatalogParamValue, type CatalogParamsOf, type CatalogPart, type CatalogPartDecl, type CatalogRecord, type CatalogTree, type CatalogTreeNode, type ChatAbort, type ChatActions, type ChatAskOptions, type ChatCall, type ChatCard, type ChatCardStatus, type ChatClientTool, type ChatCompletionsOptions, type ChatDelta, type ChatDone, type ChatDriverOptions, type ChatError, type ChatEvent, type ChatOk, type ChatOptions, type ChatOutputOf, type ChatOutputSchema, type ChatRequest, type ChatSource, type ChatState, type ChatStatus, type ChatTool, type ChatToolCall, type ChatToolPart, type ChatTransport, type ChatUsage, type ChromePromptOptions, type ChromePromptStatus, type ChromePromptTransport, type ClassesType, Collection, type CollectionFrom, type CollectionProps, type Command, type CommandBarActions, type CommandBarOptions, type CommandBarResult, type CommandBarState, type CommandBarStatus, type CommandBarUnsure, type CommandSource, type Component, type ComposeActions, type ComposeAnswer, type ComposeBackend, type ComposeNames, type ComposeOptions, type ComposeRenderOptions, type ComposeRenderable, type ComposeState, type ComposeStatus, type ComposeTree, Composed, type ComposedProps, type Connections, type ContainerView, type Control, type ControlCommonProps, type ControlDOMSource, type ControlElementOf, type ControlEvent, type ControlH, type ControlPropsOf, type ControlSpec, type ControlSpecObject, type ControlsOf, type ConvertedSchema, type CycleDOMEvent, type CycleDriver, type DOMDriverOptions, type DOMEventShorthand, type DOMEventShorthands, type DOMSource, type DefaultDrivers, type DefineComponentOptions, type DevToolsActionCause, type DevToolsCopyAsTestOptions, type DevToolsSessionRecording, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticsMode, type DiagnosticsOptions, type DragDriverCategory, type DragDriverRegistration, type DragDriverSource, type DragSource, type DragStartPayload, type DriverFactories, type DriverFromAsyncOptions, type DriverSpec, type DriverSpecs, type DropPayload, type ElementCommand, type ElementCommandRegistry, type ElementCommands, type ElementProps, type ElementTarget, type EmittedEvent, type EnrichedEventStream, type Event$1 as Event, type EventName, type EventPayload, type EventPayloadFunction, type EventSink, type EventsFnOptions, type EventsSource, type ExactShape, type ExplainedAction, type ExposeWebMcpOptions, type FakeCacheEntry, type FakeChatChunk, type FakeConnection, type FakeConnectionTarget, type FakeReplyOptions, type FetchCacheOptions, type FetchDriverOptions, type FetchError, type FetchFailure, type FetchInit, type FetchInvalidate, type FetchProgress, type FetchRequest, type FetchResponse, type FetchRetry, type FetchSource, type FieldErrors, type Filter, type FixDrivers, type FormActions, type FormBehavior, type FormCalculated, type FormData, type FormField, type FormFieldCheck, type FormFields, type FormOptions, type FormOutput, type FormRequest, type FormServerErrors, type FormSource, type FormState, type FormTool, type FormToolHandle, type FormToolResult, type FromAISDKOptions, type HeadValue, type HotModuleAPI, type HttpTransportOptions, type InspectAction, type InspectActionTrigger, type InspectChild, type InspectChildSelect, type InspectCommand, type InspectComponent, type InspectDiagnostic, type InspectFix, type InspectGraph, type InspectLocation, type InspectRecentAction, type InspectRelatedLocation, type InspectSelector, type InspectTextEdit, type InspectTimer, type InstallPrompt, type IntentSources, type IntrinsicControlProps, type JsonSchemaObject, type Layout, type LayoutNode, type LazyComponent, type LazyOptions, type Lens, type Lense, MainDOMSource, type McpAppDisplayMode, type McpAppDriverOptions, type McpAppError, type McpAppRequest, type McpAppSource, type McpContentBlock, type McpDownloadItem, type McpHostContext, type McpHostInfo, type McpLogLevel, type McpResourceContents, type McpSamplingRequest, type McpToolResult, type MockConfig, MockedDOMSource, type MultipartValue, type NonStateSinkReturns, type OpenResponsesEvent, type OpenResponsesOptions, type PagerActions, type PagerCalculated, type PagerOptions, type PagerState, type ParamNames, type ParentPayloadOf, type Persist, type PersistOptions, type PersistOptionsFor, type PersistStorage, type PersistedEntry, Portal, type PortalProps, type ProcessFormOptions, type QueryCache, type QueryCacheSnapshot, type QueryCacheSnapshotEntry, type Ref, type Ref$, type RegisteredEvent, type RenderOptions, type RenderResult, type RenderToStringOptions, type RenderableComponent, type ReplyRequest, type Resource, type ResourceRequest, type RootComponent, type Route, type RouteName, type RouteParamsArg, type RouteQuery, type Router, type RouterBlocked, type RouterCommand, type RouterOptions, type RouterSource, type RunOptions, type SchemaInput, type SchemaOutput, type ScrollToAlign, type SelectedDOMSource, type SelectionActions, type SelectionCalculated, type SelectionOptions, type SelectionState, type ServiceWorkerCommand, type ServiceWorkerOptions, type ServiceWorkerSource, type SimulatedEventInit, Slot, type SlotProps, type SocketActions, type SocketClose, type SocketConnection, type SocketDriverOptions, type SocketError, type SocketEvent, type SocketOpen, type SocketReconnect, type SocketRequest, type SocketSource, type SortFunction, type SortObject, type SortSpec, type SortableActions, type SortableDropped, type SortableOptions, type SortableState, type SseConnection, type StandardSchemaLike, type StateProp, type StrictDialect, type StrictSchemas, Suspense, type SuspenseProps, Switchable, type SwitchableProps, type SygnalApp, type SygnalBodyDOMSource, type SygnalDOMSource, type SygnalDevTools, type SygnalDocumentDOMSource, type SygnalEvents, type SygnalSinks, type TestAction, type Thunk, type ThunkData, type TimerAfter, type TimerFrame, type TimerSpec, type TimerTick, type Timers, Transition, type TransitionProps, type UIMessageStreamOptions, type UidFunction, type UndoBehaviorOptions, type UndoHistory, type UndoOptions, type UsesActions, type UsesState, type ViewProps, VirtualCollection, type VirtualCollectionProps, type WebMcpHandle, type Widget, type WidgetDefinition, type WidgetDispatch, type WidgetElementOf, type WidgetEmit, type WidgetHandle, type WidgetHostProps, type WithinTarget, abort, agentTools, agui, answers, anthropicMessages, askCard, byId, chat, chatCompletions, checkForm, choice, chromePrompt, classes, clearDiagnostics, clipboardSource, commandBar, compose, composeWith, controls, createCommand, createInstallPrompt, createRef, createRef$, decide, defineBehavior, defineCatalog, defineComponent, defineWidget, driverFromAsync, emit, enableHMR, encodeOpenResponses, event, exactState, experimentalExposeWebMcp, fieldName, fieldNames, focusInvalid, focusWithin, form, formErrors, formTool, fromAISDK, fromTree, geolocationSource, getDevTools, getDiagnostics, getField, hasField, intersectionSource, isSelected, jsonSchema, lazy, makeBrowserDriver, makeBrowserDriverWith, makeChatDriver, makeDOMDriver, makeDragDriver, makeFetchDriver, makeHeadDriver, makeMcpAppDriver, makeRouter, makeRouterDriver, makeServiceWorkerDriver, makeSocketDriver, makeTimerDriver, makeViewTransitionDOMDriver, mediaSource, messageText, mockDOMSource, noul, onDiagnostic, onlineSource, onlineStatus$, openResponses, openToolCalls, outputJsonSchema, pager, parseInput, persist, portal, processDrag, processForm, queryCache, removeNode, renderComponent, renderHead, renderToString, replyErrors, resizeSource, run, score, selection, set, setField, sortable, storageSource, strictSchemas, thunk, toJsonSchema, toTree, toggle, uiMessageStream, undo, undoable, visibilitySource, withToolResults, xs };
+export { ABORT, type ActionCause, type ActionsOf, type ActiveTimer, type AgentAction, type AgentConfirm, type AgentConfirmInfo, type AgentDeclaration, type AgentIssue, type AgentQuery, type AgentQueryResult, type AgentResult, type AgentSchema, type AgentTool, type AgentToolSet, type AgentToolsOptions, type AguiOptions, type AnswerPick, type AnswerPicks, type AnthropicMessagesOptions, type AnyComponentModule, type AnyControl, type AppErrorHook, type AppErrorInfo, type AppErrorPhase, type ArrayKeysOf, type ArrayPathsOf, type AsyncDriverError, type AsyncDriverFromFunction, type AsyncRequest, type Behavior, type BehaviorDefinition, type BehaviorFactory, type BehaviorHandler, type BehaviorModelEntry, type BehaviorProps, type BehaviorSources, type BehaviorState, type BehaviorTarget, type BrowserCommand, type BrowserFake, type BrowserFakeOptions, type BrowserIntersection, type BrowserPosition, type BrowserResize, type BrowserSource, type BrowserSources, type BrowserSpec, type Catalog, type CatalogContainer, type CatalogContainerDecl, type CatalogDecl, type CatalogOption, type CatalogParam, type CatalogParamValue, type CatalogParamsOf, type CatalogPart, type CatalogPartDecl, type CatalogRecord, type CatalogTree, type CatalogTreeNode, type ChatAbort, type ChatActions, type ChatAskOptions, type ChatCall, type ChatCard, type ChatCardStatus, type ChatClientTool, type ChatCompletionsOptions, type ChatDelta, type ChatDone, type ChatDriverOptions, type ChatError, type ChatEvent, type ChatOk, type ChatOptions, type ChatOutputOf, type ChatOutputSchema, type ChatRequest, type ChatSource, type ChatState, type ChatStatus, type ChatTool, type ChatToolCall, type ChatToolPart, type ChatTransport, type ChatUsage, type ChromePromptOptions, type ChromePromptStatus, type ChromePromptTransport, type ClassesType, Collection, type CollectionFrom, type CollectionProps, type Command, type CommandBarActions, type CommandBarOptions, type CommandBarResult, type CommandBarState, type CommandBarStatus, type CommandBarUnsure, type CommandSource, type Component, type ComposeActions, type ComposeAnswer, type ComposeBackend, type ComposeGenerated, type ComposeGeneratedOptions, type ComposeNames, type ComposeOptions, type ComposeRenderOptions, type ComposeRenderable, type ComposeState, type ComposeStatus, type ComposeTree, Composed, type ComposedProps, type Connections, type ContainerView, type Control, type ControlCommonProps, type ControlDOMSource, type ControlElementOf, type ControlEvent, type ControlH, type ControlPropsOf, type ControlSpec, type ControlSpecObject, type ControlsOf, type ConvertedSchema, type CycleDOMEvent, type CycleDriver, type DOMDriverOptions, type DOMEventShorthand, type DOMEventShorthands, type DOMSource, type DefaultDrivers, type DefineComponentOptions, type DevToolsActionCause, type DevToolsCopyAsTestOptions, type DevToolsSessionRecording, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticsMode, type DiagnosticsOptions, type DragDriverCategory, type DragDriverRegistration, type DragDriverSource, type DragSource, type DragStartPayload, type DriverFactories, type DriverFromAsyncOptions, type DriverSpec, type DriverSpecs, type DropPayload, type ElementCommand, type ElementCommandRegistry, type ElementCommands, type ElementProps, type ElementTarget, type EmittedEvent, type EnrichedEventStream, type Event$1 as Event, type EventName, type EventPayload, type EventPayloadFunction, type EventSink, type EventsFnOptions, type EventsSource, type ExactShape, type ExplainedAction, type ExposeWebMcpOptions, type FakeCacheEntry, type FakeChatChunk, type FakeConnection, type FakeConnectionTarget, type FakeReplyOptions, type FetchCacheOptions, type FetchDriverOptions, type FetchError, type FetchFailure, type FetchInit, type FetchInvalidate, type FetchProgress, type FetchRequest, type FetchResponse, type FetchRetry, type FetchSource, type FieldErrors, type Filter, type FixDrivers, type FormActions, type FormBehavior, type FormCalculated, type FormData, type FormField, type FormFieldCheck, type FormFields, type FormOptions, type FormOutput, type FormRequest, type FormServerErrors, type FormSource, type FormState, type FormTool, type FormToolHandle, type FormToolResult, type FromAISDKOptions, type GeneratedData, type GeneratedEmit, type GeneratedEvent, type GeneratedRepairState, type HandlerEntropy, type HeadValue, type HotModuleAPI, type HttpTransportOptions, type InspectAction, type InspectActionTrigger, type InspectChild, type InspectChildSelect, type InspectCommand, type InspectComponent, type InspectDiagnostic, type InspectFix, type InspectGraph, type InspectLocation, type InspectRecentAction, type InspectRelatedLocation, type InspectSelector, type InspectTextEdit, type InspectTimer, type InstallPrompt, type IntentSources, type IntrinsicControlProps, type JsonSchemaObject, type Layout, type LayoutNode, type LazyComponent, type LazyOptions, type Lens, type Lense, MainDOMSource, type McpAppDisplayMode, type McpAppDriverOptions, type McpAppError, type McpAppRequest, type McpAppSource, type McpContentBlock, type McpDownloadItem, type McpHostContext, type McpHostInfo, type McpLogLevel, type McpResourceContents, type McpSamplingRequest, type McpToolResult, type MockConfig, MockedDOMSource, type MultipartValue, type NonStateSinkReturns, type OpenResponsesEvent, type OpenResponsesOptions, type PagerActions, type PagerCalculated, type PagerOptions, type PagerState, type ParamNames, type ParentPayloadOf, type Persist, type PersistOptions, type PersistOptionsFor, type PersistStorage, type PersistedEntry, Portal, type PortalProps, type ProcessFormOptions, type QueryCache, type QueryCacheSnapshot, type QueryCacheSnapshotEntry, RECORDING_SCHEMA, type RecordOptions, type RecordedAction, type RecordedCause, type Recorder, type Recording, type Ref, type Ref$, type RegisteredEvent, type RenderOptions, type RenderResult, type RenderToStringOptions, type RenderableComponent, type ReplayDivergence, type ReplayOptions, type ReplayResult, type ReplayTestOptions, type ReplyChannel, type ReplyRequest, type ReplySender, type Resource, type ResourceRequest, type RootComponent, type Route, type RouteName, type RouteParamsArg, type RouteQuery, type Router, type RouterBlocked, type RouterCommand, type RouterOptions, type RouterSource, type RunOptions, type SchemaInput, type SchemaOutput, type ScrollToAlign, type SelectedDOMSource, type SelectionActions, type SelectionCalculated, type SelectionOptions, type SelectionState, type ServiceWorkerCommand, type ServiceWorkerOptions, type ServiceWorkerSource, type SimulateActionOptions, type SimulatedEventInit, Slot, type SlotProps, type SocketActions, type SocketClose, type SocketConnection, type SocketDriverOptions, type SocketError, type SocketEvent, type SocketOpen, type SocketReconnect, type SocketRequest, type SocketSource, type SortFunction, type SortObject, type SortSpec, type SortableActions, type SortableDropped, type SortableOptions, type SortableState, type SseConnection, type SseEvent, type StandardSchemaLike, type StateProp, type StrictDialect, type StrictSchemas, Suspense, type SuspenseProps, Switchable, type SwitchableProps, type SygnalApp, type SygnalBodyDOMSource, type SygnalDOMSource, type SygnalDevTools, type SygnalDocumentDOMSource, type SygnalEvents, type SygnalSinks, type TestAction, type Thunk, type ThunkData, type TimerAfter, type TimerFrame, type TimerFrameInput, type TimerSpec, type TimerTick, type Timers, Transition, type TransitionProps, type UIMessageStreamOptions, type UidFunction, type UndoBehaviorOptions, type UndoHistory, type UndoOptions, type UsesActions, type UsesState, type ViewProps, VirtualCollection, type VirtualCollectionProps, type WebMcpHandle, type Widget, type WidgetDefinition, type WidgetDispatch, type WidgetElementOf, type WidgetEmit, type WidgetHandle, type WidgetHostProps, type WithinTarget, abort, agentTools, agui, answers, anthropicMessages, askCard, bugReport, byId, chat, chatCompletions, checkForm, choice, chromePrompt, classes, clearDiagnostics, clipboardSource, commandBar, compose, composeWith, controls, createCommand, createInstallPrompt, createRef, createRef$, decide, defineBehavior, defineCatalog, defineComponent, defineWidget, driverFromAsync, emit, enableHMR, encodeOpenResponses, event, exactState, experimentalExposeWebMcp, fieldName, fieldNames, finalState, focusInvalid, focusWithin, form, formErrors, formTool, fromAISDK, fromTree, geolocationSource, getDevTools, getDiagnostics, getField, hasField, inertDriver, intersectionSource, isSelected, jsonSchema, keymap, lazy, makeBrowserDriver, makeBrowserDriverWith, makeChatDriver, makeDOMDriver, makeDragDriver, makeFetchDriver, makeHeadDriver, makeMcpAppDriver, makeReplies, makeRouter, makeRouterDriver, makeServiceWorkerDriver, makeSocketDriver, makeTimerDriver, makeViewTransitionDOMDriver, mediaSource, messageText, mockDOMSource, noul, onDiagnostic, onlineSource, onlineStatus$, openResponses, openToolCalls, outputJsonSchema, pager, parseInput, persist, portal, processDrag, processForm, queryCache, removeNode, renderComponent, renderHead, renderToString, replay, replayTest, replyErrors, resizeSource, run, score, selection, senderOf, set, setField, sortable, startRecording, storageSource, strictSchemas, thunk, timeline, toJsonSchema, toTree, toggle, uiMessageStream, undo, undoable, visibilitySource, withToolResults, xs };