sygnal 6.5.0 → 7.0.0

package/src/extra/testing.ts

@@ -252,6 +252,13 @@ export interface RenderOptions {
    * Default: unchanged (off unless configureStrict(true) was called).
    */
   strict?: boolean;
+  /**
+   * 7.0 timing audit (SYG257, info) while the component is rendered; restored on dispose():
+   * each output sink that reads a top-level state field its action's STATE changed is reported
+   * (it gets the new value since 7.0; 6.x gave it the old one). Requires 'sygnal/diagnostics'.
+   * Default: unchanged (off unless configureTimingAudit(true) was called).
+   */
+  timingAudit?: boolean;
   /**
    * settle()'s quiet window in ms (default 20): settle() resolves once nothing in the tree has
    * rendered, reduced or changed state for this long. A model `next('X', data, ms)` with a
@@ -454,6 +461,11 @@ export interface RenderResult {
    * `status`/`body`), or an Error / message (a network failure: the fetch rejects with it).
    */
   fail: (sinkName: string, error: any, target?: FakeReplyTarget) => Promise<void>;
+  /**
+   * PLAN-11 U-2: one progress step `{ loaded, total?, phase? }` of a pending request sent with
+   * `progress` (chosen as in respond()); it stays pending until respond()/fail().
+   */
+  progress: (sinkName: string, step: {loaded: number; total?: number; phase?: 'upload' | 'download'}, target?: FakeReplyTarget) => Promise<void>;
   /**
    * PLAN-6 L-4: stream chunks into a pending request of the LLM fake (the sink named by `llmSink`,
    * default 'LLM': the real chat driver over an in-memory transport). Chunks: strings (text),
@@ -550,9 +562,9 @@ export interface RenderResult {
    * render (await t.ready() first). 4-A1: after `await` of any wait, it shows the state the wait
    * resolved with (a later render is held back until the next macrotask).
    */
-  query: (selector: string) => Element | null;
+  query: <E extends Element = Element>(selector: string) => E | null;
   /** Every element matching a selector in the rendered tree (Portals included), as query() */
-  queryAll: (selector: string) => Element[];
+  queryAll: <E extends Element = Element>(selector: string) => E[];
   /**
    * PLAN-5 W-1: a widget's host by selector or control: `.props` (what the view passed it),
    * `.instance` (`dom: 'real'`: what mount returned) and `.dispatch(name, detail)` (the event
@@ -1197,6 +1209,13 @@ const validMs = (v: any) => typeof v == 'number' && Number.isFinite(v) && v >= 0
 // too, so its time is the clock's (Date may be left real by `toFake`), and its waits drive it.
 const fakeClock = (): any => (setTimeout as any).clock;
 const clockNow = (): number => { const c = fakeClock(); return c ? c.now : Date.now(); };
+/** PLAN-11 Q-3: ms until the next pending fake timer (0: none, or real timers) */
+const nextFakeTimer = (): number => {
+  const c = fakeClock();
+  let due = Infinity;
+  try { Object.values(c?.timers || {}).forEach((t: any) => { if (t && t.callAt > c.now && t.callAt < due) due = t.callAt; }); } catch (_) {}
+  return due < Infinity ? due - c.now : 0;
+};
 /**
  * Under fake timers, advance the clock timer by timer (nextAsync flushes promises around each
  * one) until `p` settles. Every pending wait has a timer (its timeout, a quiet-window tick), so
@@ -1369,6 +1388,7 @@ const headFake = () => {
 };
 let savedConfig: ReturnType<typeof _getDiagnosticsConfig>;
 let savedStrict: any;
+let savedAudit: any;
 
 /*
  * PLAN-4 GS-2, mock DOM: could the element a command targets have this method? The core runs any
@@ -1468,7 +1488,7 @@ export function renderComponent(
   componentDef: any,
   options: RenderOptions = {}
 ): RenderResult {
-  const {initialState, mockConfig = {}, drivers = {}, diagnostics, strict, dom = 'mock', autoConnect = true, socketSink = 'WS', resourceSink = 'HTTP', llmSink = 'LLM', http: httpOptions, context: ancestors} = options;
+  const {initialState, mockConfig = {}, drivers = {}, diagnostics, strict, timingAudit, dom = 'mock', autoConnect = true, socketSink = 'WS', resourceSink = 'HTTP', llmSink = 'LLM', http: httpOptions, context: ancestors} = options;
   const {intent, model = {}} = componentDef;
   // E4: real DOM mode
   const real = dom == 'real';
@@ -1511,6 +1531,7 @@ export function renderComponent(
   if (!active++) {
     savedConfig = _getDiagnosticsConfig();
     savedStrict = core.strict;
+    savedAudit = core.timingAudit;
     // G-051: forget the checks' report dedupe (once()), so a finding from an earlier test is
     // reported again. Only that set: resetChecks() would also drop inspect()'s records of
     // other live instances / apps.
@@ -1518,6 +1539,8 @@ export function renderComponent(
   }
   configureDiagnostics({mode: diagnostics || (prevMode == 'off' ? 'collect' : prevMode)});
   if (strict !== undefined) core.strict = strict;
+  // 7.0 timing audit (SYG257, 'sygnal/diagnostics'): same bridge flag as configureTimingAudit()
+  if (timingAudit !== undefined) core.timingAudit = timingAudit;
   // PLAN-4 GS-2: element commands run on the real DOM (jsdom gets the missing methods), and their
   // SYG640/SYG641 are reported without the dev entry too
   if (real && !domFakes) domFakes = fakeElementMethods(document.defaultView || globalThis);
@@ -1683,6 +1706,7 @@ export function renderComponent(
     if (!--active) {
       configureDiagnostics(savedConfig);
       core.strict = savedStrict;
+      core.timingAudit = savedAudit;
       domFakes?.();
       domFakes = undefined;
     }
@@ -1716,7 +1740,8 @@ export function renderComponent(
   // value: what t.requests lists (normalised); req: the request the driver got; res: the resource;
   // pf: a { prefetch } fetch (5-5: answered into the cache, no reply)
   // llm: the in-memory stream handle of an LLM fake request (PLAN-6 L-4)
-  type Pending = {value: any; req: any; category: any; res?: string; pf?: any; live: boolean; settle: (ok: boolean, v: any) => void; llm?: any};
+  // step: PLAN-11 U-2, the driver's progress callback of a request sent with `progress` (t.progress)
+  type Pending = {value: any; req: any; category: any; res?: string; pf?: any; live: boolean; settle: (ok: boolean, v: any) => void; llm?: any; step?: (phase: string, loaded: number, total: number) => void};
   type Fake = {select: any; errors: any; subs: Set<FakeSub>; at: (ns: any[]) => any; pending: Pending[]; in$: any; http: any; ws: Sock; llm?: any};
   const fakes = new Map<string, Fake>();
   // 5-3: the fake drivers' focus / online listeners (t.focus, t.online)
@@ -1749,14 +1774,22 @@ export function renderComponent(
         const lin$ = xs.create();
         llm = {in$: lin$, src: makeChatDriver({transport: tr, _frame: (f: () => void) => { frames.push(f); }})(lin$)};
       }
+      let memFetch: any;
       const http = makeFetchDriver({
         ...httpOptions,
+        // PLAN-11 U-2: a progress request is answered like any other (t.respond / t.fail); its
+        // pending entry keeps the driver's progress callback for t.progress
+        _progress: (url: string, init: any, step: any) => {
+          const r = memFetch(url, init);
+          pending[pending.length - 1].step = step;
+          return r;
+        },
         // 5-3: focus / online come from t.focus() / t.online() only
         _on: (f: any) => { signals.add(f); return () => signals.delete(f); },
         _tap: (req: any, res?: string, pf?: any) => { tapped = [req, res, pf]; },
         // D472: a batch / split request (a large decide()) is one fetch here, answered as one
         _whole: true,
-        fetch: (url: string, init: any) => new Promise((resolve, reject) => {
+        fetch: memFetch = (url: string, init: any) => new Promise((resolve, reject) => {
           const [req, res, pf] = tapped || [{url}];
           tapped = undefined;
           // G-171(1): a resource fetch is listed as { url, ...request, resource: name }; 5-5: a
@@ -1788,6 +1821,7 @@ export function renderComponent(
         return {
           select: (sel?: any) => xs.merge(hs.select(sel), own(false)(sel), sock.select(sel)),
           errors: (sel?: any) => xs.merge(hs.errors(sel), own(true)(sel)),
+          progress: (sel?: any) => hs.progress(sel),
           subs, at, pending, in$, http, ws, llm,
           // 5-3: the driver's matcher / inspection (the dev checks' SYG632, t.cache)
           __matches: http.__matches, __inspect: http.__inspect,
@@ -2473,7 +2507,7 @@ export function renderComponent(
     if (tg === undefined) return {match: cat, desc: catDesc, o};
     if (typeof tg == 'string') {
       // an ok/error action name, key, category, resource name or URL
-      return {match: r => { const v = r.value || {}; return cat(r) && [v.ok, v.error, v.key, v.category, r.res, v.url].includes(tg); }, desc: ` matching '${tg}'${catDesc}`, o};
+      return {match: r => { const v = r.value || {}; return cat(r) && [v.ok, v.error, v.progress, v.key, v.category, r.res, v.url].includes(tg); }, desc: ` matching '${tg}'${catDesc}`, o};
     }
     if (typeof tg == 'function') {
       return {match: r => { try { return cat(r) && !!tg(r.value); } catch (_) { return false; } }, desc: ` matching the predicate${catDesc}`, o};
@@ -2706,6 +2740,23 @@ export function renderComponent(
         return {error: err, category, request: e?.req, status: status ?? x?.status, body};
       });
 
+  // PLAN-11 U-2: t.progress. One progress step of a pending request sent with `progress` (its
+  // reply action, or progress() for `progress: true`); the request stays pending. Targets as
+  // t.respond's; the phase defaults to 'upload' for a request with a body, else 'download'
+  const progress = (name: string, step: any, opts?: FakeReplyTarget) => {
+    throwFailure();
+    if (drivers[name]) throw new Error(`[Sygnal] t.progress('${name}'): ${name} has a real driver (passed in drivers), so there is nothing to script`);
+    if (!step || typeof step != 'object' || typeof step.loaded != 'number') throw new Error(`[Sygnal] t.progress('${name}', step): step is { loaded, total?, phase? } (got ${brief(step)})`);
+    const tg = targetOf(opts);
+    const what = `t.progress('${name}'${typeof opts == 'string' ? `, …, '${opts}'` : ''})`;
+    const now = isReady && !inputs.length ? pick(name, tg) : undefined;
+    if (now && !now.step) throw new Error(`[Sygnal] ${what}: the request ${brief(now.value)} has no progress: send it with progress: 'UPLOADING' (a reply action) or progress: true`);
+    return scripted(() => pick(name, tg), w => noPending(what, name, tg, w), (e: Pending) => {
+      if (!e.step) return new Error(`[Sygnal] ${what}: the request ${brief(e.value)} has no progress: send it with progress: 'UPLOADING' (a reply action) or progress: true`);
+      const r = e.req || {};
+      e.step(step.phase || (r.body !== undefined || r.json !== undefined || r.multipart !== undefined ? 'upload' : 'download'), step.loaded, step.total ?? 0);
+    }, sendDue);
+  };
   // PLAN-6 L-4: t.stream. Targets as t.respond's (an action name or key, a partial request, a
   // predicate, { request, nth }); `end: false` (the last argument, or in the target options)
   // leaves the stream open. Chunks become ChatEvents pushed into the in-memory stream; the fake's
@@ -2904,11 +2955,11 @@ export function renderComponent(
   };
   // 6-B (G-185): on the mock DOM, MockElement snapshots of the latest rendered tree
   const mockAll = (s: string): any[] => findAll(vtree, parse(norm(s)), [], []).map(c => mockOf(c, htmlOf));
-  const queryAll = (s: string): Element[] => {
+  const queryAll = <E extends Element = Element>(s: string): E[] => {
     s = selOf(s);
     notYet(`t.queryAll('${s}')`);
     if (!real) return mockAll(s);
-    return roots().flatMap(r => Array.from(r.querySelectorAll(s)));
+    return roots().flatMap(r => Array.from(r.querySelectorAll<E>(s)));
   };
   const queryIn = (s: string): Element | null => {
     for (const r of roots()) {
@@ -2917,11 +2968,11 @@ export function renderComponent(
     }
     return null;
   };
-  const query = (s: string): Element | null => {
+  const query = <E extends Element = Element>(s: string): E | null => {
     s = selOf(s);
     notYet(`t.query('${s}')`);
     if (!real) return mockAll(s)[0] ?? null;
-    return queryIn(s);
+    return queryIn(s) as E | null;
   };
 
   // PLAN-5 W-1: a widget host (selector or control): the props it was rendered with (the mock
@@ -3134,7 +3185,12 @@ export function renderComponent(
         let msg = `${name} timed out after ${timeoutMs}ms.`;
         const [why, pending] = explainNext(start);
         msg += why;
-        if (pending) msg += ` Wait longer: t.${name}(pred, ms), or the renderComponent timeoutMs option (default for every wait).`;
+        if (inputs.length) msg += ` ${inputs.length} simulated input(s) still pending.`;
+        // PLAN-11 Q-3: on the fake clock a state a timer (TIMER driver, periodic, delay) brings
+        // later than the timeout can't arrive in time: name the next pending timer
+        const later = pending ? 0 : nextFakeTimer();
+        if (later) msg += ` A timer is still pending on the fake clock (it fires ${later}ms after this timeout): if the state comes from it, this wait ended first.`;
+        if (pending || later) msg += ` Wait longer: t.${name}(pred, ms), or the renderComponent timeoutMs option (default for every wait).`;
         // G-065: a state from before the call matched; next() only looks at new ones
         for (let i = from - 1; i >= 0; i--) {
           if (test(i)) {
@@ -3317,6 +3373,7 @@ export function renderComponent(
     requests,
     respond,
     fail,
+    progress,
     stream,
     connections,
     cache,

package/src/index.d.ts

@@ -53,9 +53,12 @@ type ComponentProps<STATE, PROPS, CONTEXT> = (
  */
 export type UidFunction = (name?: string) => string
 
-/** The first argument of a component's view: its props plus `state`, `context`, `children`, `slots` and `uid`. */
+/**
+ * The first argument of a component's view: its props plus `state`, `context`, `children`, `slots` and `uid`.
+ * PLAN-11 Q-1: PROPS = `any` is read as "any other props" (`any & X` would make `state` `any` too).
+ */
 export type ViewProps<STATE = any, PROPS = {}, CONTEXT = {}> =
-  PROPS & { state: STATE; context: CONTEXT; children?: JSX.Element | JSX.Element[]; slots?: Record<string, JSX.Element[]>; uid: UidFunction }
+  (0 extends (1 & PROPS) ? { [prop: string]: any } : PROPS) & { state: STATE; context: CONTEXT; children?: JSX.Element | JSX.Element[]; slots?: Record<string, JSX.Element[]>; uid: UidFunction }
 
 /**
  * The `state` prop a parent passes to a sub-component in JSX: the name of a field of the
@@ -90,13 +93,19 @@ type NextFunction<ACTIONS = any> = ACTIONS extends object
     ) => void
   : (action: string, data?: any, delay?: number) => void
 
-type ReducerExtras<PROPS, CONTEXT> = PROPS & { context: CONTEXT; children?: JSX.Element | JSX.Element[]; slots?: Record<string, JSX.Element[]>; uid: UidFunction }
+
+/**
+ * A reducer's 4th argument. 7.0: STATE runs first; every other sink gets the committed state as
+ * `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 }
 
 type Reducer<STATE, PROPS, ACTIONS = any, DATA = any, RETURN = any, CONTEXT = {}> = (
   state: STATE,
   args: DATA,
   next: NextFunction<ACTIONS>,
-  props: ReducerExtras<PROPS, CONTEXT>
+  props: ReducerExtras<PROPS, CONTEXT, STATE>
 ) => RETURN | ABORT | undefined
 
 export type ExactShape<EXPECTED, ACTUAL extends EXPECTED> = ACTUAL &
@@ -232,7 +241,7 @@ type AnySinkConstant =
  * `props.signal` aborts on DISPOSE (undefined where AbortController is missing).
  */
 type EffectReducer<STATE, PROPS, ACTIONS, DATA, CALCULATED, CONTEXT = {}> =
-  | ((state: STATE & CALCULATED, args: DATA, next: NextFunction<ACTIONS>, props: ReducerExtras<PROPS, CONTEXT> & { signal?: AbortSignal }) => void)
+  | ((state: STATE & CALCULATED, args: DATA, next: NextFunction<ACTIONS>, props: ReducerExtras<PROPS, CONTEXT, STATE & CALCULATED> & { signal?: AbortSignal }) => void)
 
 type DefaultSinks<STATE, PROPS, ACTIONS, DATA, CALCULATED, SINK_RETURNS extends NonStateSinkReturns = {}, CONTEXT = {}> = {
   STATE?: SinkValue<STATE, PROPS, ACTIONS, DATA, STATE, CALCULATED, CONTEXT>;
@@ -902,10 +911,11 @@ export function pager(options?: PagerOptions): Behavior<PagerState, PagerActions
 export type FieldErrors = Record<string, string>
 
 /** One field of a `form` slice: `state.form.fields.email`, `state.form.fields['addresses.7.city']`. */
-export interface FormField {
+export interface FormField<T = any> {
   /** The field name, for `name={f.name}` (the path in `values`; rows of an array by id) */
   name: string;
-  value: any;
+  /** The field's value: typed for a top-level field of a typed form (`fields.email.value: string`) */
+  value: T;
   /** What to show: a server or check error at once, a schema error once the field is touched (per `show`) or after a submit; '' when none */
   error: string;
   /** `!!error`, for `aria-invalid={f.email.invalid}` */
@@ -942,12 +952,36 @@ export interface FormState<V = any> {
   validating: boolean;
   /** The schema has answered at least once since the start (or the last `form.RESET`) */
   validated: boolean;
+  /**
+   * PLAN-11 (6.7): the submit request's last progress step, when it is sent with
+   * `progress: 'form.PROGRESS'`; null otherwise and after `form.DONE` / `form.ERRORS` / `form.RESET`
+   */
+  progress: { phase: 'upload' | 'download'; loaded: number; total: number | null; fraction: number | null } | null;
+  /**
+   * PLAN-11 (6.7): how many times the form started over (`form.RESET`, `resetOnShow`). A file
+   * input can't be cleared through state: key it with this, `key={'avatar' + state.form.resets}`
+   */
+  resets: number;
 }
 
+type FormIsAny<T> = 0 extends (1 & T) ? true : false
+
+/**
+ * A form's `fields` (PLAN-11 F-1): the top-level fields of `values` by name, typed
+ * (`fields.email.value: string`), and nested paths ('addresses.7.city', 'addresses.7') with any
+ * value. A top-level name that isn't in `values` is a type error (a typo). Untyped values (any):
+ * `Record<string, FormField>`.
+ */
+export type FormFields<V = any> = FormIsAny<V> extends true
+  ? Record<string, FormField>
+  : V extends object
+    ? { [K in keyof V & string]-?: FormField<V[K]> } & { [path: `${string}.${string}`]: FormField }
+    : Record<string, FormField>
+
 /** A `form` slice's calculated fields. */
-export interface FormCalculated {
+export interface FormCalculated<V = any> {
   /** Every field of `values` by name (leaves, arrays, and array rows' fields by row id) */
-  fields: Record<string, FormField>;
+  fields: FormFields<V>;
   /** No schema error and no failed check, as of the schema's last answer (false until its first; an async re-validation keeps the previous value) */
   valid: boolean;
   dirty: boolean;
@@ -963,15 +997,38 @@ export interface FormFieldCheck {
   error?: (body: any) => string | false | null | undefined;
 }
 
-export interface FormOptions<V = any> {
+/** Types only: the key of `FormOptions`' phantom output type (not exported, never set) */
+declare const formOutput: unique symbol
+
+/** PLAN-11: the `request` option of form(): a request without reply actions (the form names them), or a function of the submit data and the host state */
+type FormRequestObject = Exclude<FetchRequest, string> & { url: string; ok?: never; error?: never }
+export type FormRequest<OUT = any> =
+  | FormRequestObject
+  | ((data: OUT, state: any) => FormRequestObject | typeof ABORT | null | undefined | false)
+
+export interface FormOptions<V = any, OUT = any> {
+  /** Phantom, types only: the schema's output (`FormOutput<typeof uses.form>`); never set */
+  readonly [formOutput]?: OUT;
   /**
    * The start values; field names are paths in it (rows of an array of objects need an `id`, SYG236).
    * Or a function of the host component's state, for start values that come from state (a default
    * from the settings): called when the form starts, and each time it starts over (`resetOnShow`)
    */
   values: V | ((state: any) => V);
-  /** The host action a valid submit dispatches with the schema's output (SYG234 when it has no model entry). With an `http` sink in its entry the submit is pending until `form.DONE` / `form.ERRORS`; otherwise it is done at once */
-  submit: string;
+  /**
+   * The host action a valid submit dispatches with the schema's output (SYG234 when it has no model entry). With an `http` sink in its entry the submit is pending until `form.DONE` / `form.ERRORS`; otherwise it is done at once.
+   * Optional with `request` (then dispatched too, for state; its entry should send no request)
+   */
+  submit?: string;
+  /**
+   * PLAN-11 (6.7): the form sends a valid submit itself on the `http` sink: a request, or a
+   * 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
+   * `ok: 'form.DONE'`, `error: 'form.ERRORS'`
+   */
+  request?: FormRequest<OUT>;
   /** Async checks by field name: run on blur and before a submit, which waits for them */
   check?: Record<string, FormFieldCheck>;
   /** When a schema error shows: after the field's blur (default), on input, or only after a submit */
@@ -1001,9 +1058,19 @@ export interface FormOptions<V = any> {
   tool?: import('./ai.d').FormToolHandle;
 }
 
-export interface FormActions {
-  /** 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) */
-  CHANGE: { name: string; value: any; item?: any };
+/**
+ * What `form.ERRORS` takes (the runtime's `replyErrors`): an error reply (a driver's
+ * `{ error, status?, body?, request }` or `{ status, body }`, the body `{ errors }` or the map
+ * itself), a map `{ name: message | messages }`, or a list of issues `[{ path, message }]`
+ */
+export type FormServerErrors =
+  | Record<string, string | ReadonlyArray<string>>
+  | ReadonlyArray<{ message: string; path?: ReadonlyArray<any> }>
+  | { status?: number; body?: any; error?: any; request?: any }
+
+export 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 };
   /**
    * 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
@@ -1012,20 +1079,49 @@ export interface FormActions {
   SET: { values: Record<string, any> };
   /** A field lost focus (focusout): its name */
   BLUR: string;
-  /** The form element's submit (default prevented) */
-  SUBMIT: any;
+  /** The form element's submit (default prevented); its data is ignored (a host may dispatch it from a button) */
+  SUBMIT: unknown;
   /** Adds a row to an array field (with the next id): `{ field: 'addresses', value: { street: '' } }` */
   ADD: { field: string; value?: Record<string, any> };
   /** Removes a row by id: `{ field: 'addresses', id }` */
   REMOVE: { field: string; id: any };
-  /** Server errors: an error reply (`{ status, body: { errors } }`) or a map `{ name: message }`; focuses the first */
-  ERRORS: any;
-  /** The submit was saved: `initial` becomes `values` */
-  DONE: any;
-  /** Back to `initial` (or to the values given) */
-  RESET: any;
+  /** Server errors: an error reply (`{ status, body: { errors } }`), a map `{ name: message }` or a list of issues; focuses the first */
+  ERRORS: FormServerErrors;
+  /** The submit was saved: `initial` becomes `values`. Its data (the reply) is ignored */
+  DONE: unknown;
+  /** PLAN-11: a progress step of the submit request (`progress: 'form.PROGRESS'` on it): kept as `progress` while submitting */
+  PROGRESS: FetchProgress;
+  /** Back to `initial`, or to the values given (whole values, not merged; anything but a plain object, such as a click event, means `initial`) */
+  RESET: V | null | undefined;
 }
 
+/**
+ * The schema's input type (Standard Schema `~standard.types.input`; zod, valibot and arktype declare
+ * it); `any` for a schema that doesn't declare `types`
+ */
+export type SchemaInput<S> = S extends { readonly '~standard': { readonly types?: infer T } }
+  ? [NonNullable<T>] extends [{ readonly input: infer I }] ? I : any
+  : any
+
+type FormSchemaOutput<S> = S extends { readonly '~standard': { readonly types?: infer T } }
+  ? [NonNullable<T>] extends [{ readonly output: infer O }] ? O : any
+  : any
+
+/** The values type of `form(schema, { values })`: the schema's input when it declares one, else what `values` gives */
+type FormValuesOf<V, S> = FormIsAny<SchemaInput<S>> extends true ? V : SchemaInput<S>
+
+/** What `form()` returns: a behavior whose types carry the values (V) and the schema's output (OUT, the submit payload) */
+export type FormBehavior<V = any, OUT = any> = Behavior<FormState<V>, FormActions<V>, FormCalculated<V>, FormOptions<V, OUT>>
+
+/**
+ * The data the host's submit action gets (the schema's output) from a `form()` use:
+ * `SIGN_UP: { HTTP: (state, data: FormOutput<typeof uses.form>) => ... }`. Or from the schema:
+ * `SchemaOutput<typeof signupSchema>`. `any` for a schema that doesn't declare `types`.
+ */
+export type FormOutput<F> = F extends Behavior<any, any, any, infer OPTIONS>
+  ? OPTIONS extends { readonly [formOutput]?: infer O } ? (unknown extends O ? any : O) : any
+  : any
+
 /**
  * A form with validation (PLAN-5 F-1), any Standard Schema validator (zod, valibot, arktype, a
  * hand-written object):
@@ -1040,7 +1136,11 @@ export interface FormActions {
  * that sends nothing (STATE, PARENT, EVENTS) is done at once. Throws SYG231 when
  * `schema` isn't a Standard Schema.
  */
-export function form<V = any>(schema: StandardSchemaLike, options: FormOptions<V>): Behavior<FormState<V>, FormActions, FormCalculated, FormOptions<V>>
+export function form<V = any, S extends StandardSchemaLike = StandardSchemaLike>(
+  schema: S,
+  options: FormOptions<V, FormSchemaOutput<S>> & { values: FormIsAny<SchemaInput<S>> extends true ? unknown : SchemaInput<S> | ((state: any) => SchemaInput<S>) }
+    & ({ submit: string } | { request: FormRequest<FormSchemaOutput<S>> })
+): FormBehavior<FormValuesOf<V, S>, FormSchemaOutput<S>>
 
 /** A Standard Schema's result for `values`: errors by field name, and the output when there are none. A Promise for an async schema. */
 export function checkForm(schema: StandardSchemaLike, values: any): { errors: FieldErrors; value: any } | Promise<{ errors: FieldErrors; value: any }>
@@ -1811,6 +1911,8 @@ export type {
   InspectRecentAction,
   InspectCommand,
   InspectTimer,
+  InspectLocation,
+  InspectChildSelect,
 } from './extra/diagnostics/checks/public'
 
 /**
@@ -2290,6 +2392,9 @@ export type FetchInit = {
  * descendants'): two instances, or Collection items, using the same category never see or
  * cancel each other's requests. The root component sees every reply.
  */
+/** PLAN-11: one value of a request's `multipart` body */
+export type MultipartValue = Blob | string | number | boolean | null | undefined | Record<string, any>
+
 export type FetchRequest = string | {
   /** Request URL (prefixed with the driver's `baseUrl`) */
   url: string;
@@ -2315,8 +2420,24 @@ export type FetchRequest = string | {
   query?: Record<string, string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined>>;
   /** Sent as JSON.stringify(json), with `Content-Type: application/json` unless set */
   json?: any;
+  /**
+   * PLAN-11 (6.7): a multipart/form-data body, written as data: `{ file: state.file, title: state.title }`.
+   * A File or Blob is a file part, an array repeats the name (`files: [a, b]`), null/undefined are
+   * skipped, an object is sent as JSON text, anything else as a string. The browser sets the
+   * content-type (with its boundary); a `content-type` header is dropped. POST by default
+   */
+  multipart?: Record<string, MultipartValue | ReadonlyArray<MultipartValue>>;
   /** Raw body (string, FormData, Blob, ...) */
   body?: any;
+  /**
+   * PLAN-11 (6.7): report upload and download progress. An action name: each step arrives as that
+   * action of the sending instance (`UPLOADING: (state, { phase, fraction }) => ...`); `true`: on
+   * `HTTP.progress(category?)`. Data: FetchProgress. The request then goes over XMLHttpRequest
+   * (the only way to see upload progress in every browser); fetch-only `init` options
+   * (`keepalive`, `priority`, `cache`, `redirect`, `integrity`, `mode`, `referrerPolicy`) don't
+   * apply (SYG636). Not for resources or `batch`. Without XMLHttpRequest (Node): no steps
+   */
+  progress?: string | true;
   /**
    * Latest only: sending this request aborts this component's requests still in flight in the
    * same category; their responses and errors are never delivered. Default: the driver's `latest`
@@ -2431,10 +2552,15 @@ export type FetchRetry = SocketReconnect & {
   count?: number;
 }
 
-/** Any Standard Schema (https://standardschema.dev): an object with `~standard.validate` */
-export type StandardSchemaLike = {
+/**
+ * Any Standard Schema (https://standardschema.dev): an object with `~standard.validate`. `IN` / `OUT`
+ * are its declared `~standard.types` (input / output; zod, valibot, arktype declare them), read by
+ * `form()`, `SchemaInput` and `SchemaOutput`; a schema without `types` is `StandardSchemaLike<any>`.
+ */
+export type StandardSchemaLike<IN = any, OUT = IN> = {
   readonly '~standard': {
     validate: (value: unknown) => {value?: any; issues?: ReadonlyArray<{message: string; path?: ReadonlyArray<any>}>} | Promise<{value?: any; issues?: ReadonlyArray<{message: string; path?: ReadonlyArray<any>}>}>;
+    readonly types?: { readonly input: IN; readonly output: OUT } | undefined;
     [key: string]: any;
   };
 }
@@ -2561,11 +2687,30 @@ export type FetchError<REQUEST = any> = {
   body?: any;
 }
 
+/**
+ * PLAN-11 (6.7): one progress step of a request sent with `progress`. Steps come at most every
+ * 50 ms per phase, always including the first and the last (`fraction: 1`). A request with a
+ * body reports 'upload' then 'download'; a GET only 'download'. A retry starts again at 0.
+ */
+export type FetchProgress<REQUEST = any> = {
+  phase: 'upload' | 'download';
+  /** Bytes sent ('upload') or received ('download') so far */
+  loaded: number;
+  /** Total bytes, or null when unknown (a download without Content-Length) */
+  total: number | null;
+  /** loaded / total (0..1), or null when the total is unknown */
+  fraction: number | null;
+  category: string | undefined;
+  request: REQUEST;
+}
+
 export type FetchSource<VALUE = any> = {
   /** 2xx responses: all of them, one category, or those a predicate accepts */
   select: (category?: string | ((response: FetchResponse<VALUE>) => boolean)) => Stream<FetchResponse<VALUE>>
   /** Failures. Filters like select(). While nothing listens, failures are console.error'd */
   errors: (category?: string | ((failure: FetchError) => boolean)) => Stream<FetchError>
+  /** PLAN-11: progress steps of requests sent with `progress: true`. Filters like select() */
+  progress: (category?: string | ((step: FetchProgress) => boolean)) => Stream<FetchProgress>
 }
 
 export type FetchDriverOptions = {
@@ -2584,8 +2729,10 @@ export type FetchDriverOptions = {
   timeoutMs?: number;
   /** Default `parse` for every request. Default 'auto' */
   parse?: 'auto' | 'json' | 'text' | 'response' | ((response: Response) => any);
-  /** The fetch implementation. Default: `globalThis.fetch`, read at each request (so test stubs apply) */
+  /** The fetch implementation. Default: `globalThis.fetch`, read at each request (so test stubs apply). Not used for `progress` requests */
   fetch?: (input: string, init?: any) => Promise<any>;
+  /** PLAN-11: the XMLHttpRequest class for `progress` requests. Default: the global one, read at each request */
+  XMLHttpRequest?: any;
   /**
    * PLAN-3 D88: the query cache, off by default: `cache: queryCache({ staleTime })`. On:
    * resources' GET/HEAD replies are cached (stale-while-revalidate: cached data shows at once,
@@ -2668,6 +2815,12 @@ export type SseConnection = SocketActions & {
   /** URL (after `baseUrl`) */
   sse: string;
   withCredentials?: boolean;
+  /**
+   * PLAN-11 (6.7): request headers, e.g. `{ authorization: 'Bearer ' + state.token }`. The native
+   * EventSource can't send headers, so a connection with them is read with `fetch` (same events,
+   * reconnects with `Last-Event-ID`). A changed header (a new token in state) reconnects
+   */
+  headers?: Record<string, string>;
   /** Named events → actions: `{ 'price-update': 'PRICE' }` (data JSON-parsed when it parses) */
   events?: Record<string, string>;
 }
@@ -2720,8 +2873,10 @@ export type SocketDriverOptions = {
   queueLimit?: number;
   /** The WebSocket class. Default: `globalThis.WebSocket`, read at connect time (so test stubs apply) */
   WebSocket?: any;
-  /** The EventSource class. Default: `globalThis.EventSource`, read at connect time */
+  /** The EventSource class. Default: `globalThis.EventSource`, read at connect time (an `sse` connection with `headers`: a fetch-based one, unless this is given) */
   EventSource?: any;
+  /** PLAN-11: the fetch for `sse` connections with `headers`. Default: `globalThis.fetch` */
+  fetch?: (input: string, init?: any) => Promise<any>;
 }
 
 /**
@@ -3145,6 +3300,12 @@ export type FakeCacheEntry = {
 }
 
 export interface RenderOptions {
+  /**
+   * 7.0 timing audit (SYG257, info): report each output sink that reads a top-level state field
+   * its action's STATE changed (it gets the new value since 7.0; 6.x gave it the old one). For
+   * migrating 6.x code; default off (configureTimingAudit() from 'sygnal/diagnostics' sets it for all)
+   */
+  timingAudit?: boolean;
   /** Override initial state (defaults to component's .initialState) */
   initialState?: any;
   /**
@@ -3470,6 +3631,14 @@ export interface RenderResult<STATE = any> {
    * throws (the driver would only log it, SYG678).
    */
   fail: (sinkName: string, error: any, target?: string | FakeReplyOptions | Record<string, any> | ((request: any) => boolean)) => Promise<void>;
+  /**
+   * PLAN-11 (6.7): one progress step of a pending request sent with `progress` (chosen as in
+   * respond; `'UPLOADING'` matches its progress action too): `t.progress('HTTP', { loaded: 50, total: 100 }, 'UPLOADING')`.
+   * The component gets FetchProgress (`fraction: 0.5`) as that action, or on `HTTP.progress()`
+   * for `progress: true`. `phase` defaults to 'upload' for a request with a body, else
+   * 'download'. The request stays pending until respond()/fail(). Resolves once reduced and rendered.
+   */
+  progress: (sinkName: string, step: { loaded: number; total?: number; phase?: 'upload' | 'download' }, target?: string | FakeReplyOptions | Record<string, any> | ((request: any) => boolean)) => Promise<void>;
   /**
    * PLAN-6 L-4: stream into a pending request of the LLM fake (the sink named by `llmSink`,
    * default 'LLM': the real makeChatDriver over an in-memory transport). Chunks: strings (text),
@@ -3601,13 +3770,13 @@ export interface RenderResult<STATE = any> {
    * `await t.next(pred)` / `waitForState` / `settle()` / `ready()` it shows the state the wait resolved with.
    */
   query: {
-    (selector: string): Element | null;
+    <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() */
   queryAll: {
-    (selector: string): Element[];
+    <E extends Element = Element>(selector: string): E[];
     <CONTROL extends AnyControl>(control: CONTROL): Array<ControlElementOf<CONTROL>>;
   };
   /**

package/src/index.ts

@@ -86,3 +86,4 @@ export * from './cycle/dom/index'
 // and ESM classes tree-shake when an app does not use them.
 export { concat, debounce, throttle, delay, dropRepeats, sampleCombine } from './extra/xstreamExtras'
 export { flattenConcurrently, flattenSequentially } from './extra/flatten'
+

package/src/shared.ts

@@ -55,3 +55,6 @@ export const NOT_SINK = /^(__|(props|children|dispose|commands)\$$|(CHILD|PARENT
  */
 export const abortReason: {r?: string} = {}
 export const abort = (reason?: string): typeof ABORT => (abortReason.r = reason, ABORT)
+
+/** Private semantic binding identity, shared by built-in helpers and the runtime. */
+export const BINDING = /*#__PURE__*/ Symbol.for('sygnal.binding')

package/src/ui/dialog.ts

@@ -110,9 +110,10 @@ const base = /*#__PURE__*/ defineBehavior({
     TOGGLED: (s: any, open: boolean) => (open && !s.open ? {...s, open, returnValue: ''} : ABORT),
     CLOSED: {
       STATE: (s: any, returnValue: string) => (!s.open && s.returnValue === returnValue ? ABORT : {...s, open: false, returnValue}),
-      ELEMENT: (s: any, _d: any, _n: any, _p: any, o: any) => {
+      ELEMENT: (s: any, _d: any, _n: any, p: any, o: any, k: string) => {
         const f = o.returnFocus ?? true, sel = f === true ? o.trigger : f
-        if (!s.open || !sel) return ABORT
+        // only a dialog that was open before this close returns the focus
+        if (!(p?.previousState ? p.previousState[k] : s).open || !sel) return ABORT
         // true: the element that opened it (OPEN's close listener, G-430), else the trigger; a
         // selector: that element (each only when the focus was lost)
         return {focus: refocus(sel)}