sygnal 6.6.0 → 7.0.0

package/src/core/runtime.ts

@@ -96,6 +96,8 @@ export class App {
   /** run()'s hooks, then each addHooks() layer (G-297) */
   layers: Hooks[]
   born: Inst[] = []
+  /** Last state version delivered to stream listeners and binding owners. */
+  nv?: number
   watchers = new Set<Inst>()
   /** streams the disposed instances left without listeners, stopped when the drain / flush ends */
   dq: any[] = []
@@ -185,6 +187,8 @@ export class App {
   }
   /** STATE.stream: the instances whose state changed emit it */
   notify() {
+    if (this.nv === this.ver) return
+    this.nv = this.ver
     for (const i of this.watchers) i.notify()
   }
 
@@ -280,7 +284,7 @@ export class App {
         this.ran = false
         this.last = v
         this.hooks.onPatch?.(v)
-        this.vdomL?.next(v)
+        this.vdomL?.next(v ?? null)
       }
       if (this.dq.length) this.stopLater()
     } finally {

package/src/extra/ai/chat/behavior.ts

@@ -92,7 +92,7 @@
  * closed as not run, an app confirm dropped (a server approval stays answerable), and a card that
  * was composing composed again; open client calls stay answerable.
  */
-import {defineBehavior} from '../../behaviors'
+import {defineBehavior, fromPrevious} from '../../behaviors'
 import {ABORT} from '../../../shared'
 import {report} from '../../diagnostics/index'
 import xs from '../../xstreamCompat'
@@ -529,7 +529,7 @@ export const chat = (options: any = {}): any => {
         ...(c.ask?.controls && DOM && {CONTROL: DOM.select('[data-compose-control]').events('click').map(controlOf).filter((x: any) => !!x)}),
       }
     },
-    model: {
+    model: fromPrevious({
       PROMPT: (s: any, p: any) => typeof p == 'string' && p !== s.prompt ? {...s, prompt: p} : ABORT,
       SEND: {
         STATE: (s: any, d: any) => sendStep(s, d) || ABORT,
@@ -609,7 +609,7 @@ export const chat = (options: any = {}): any => {
         ANSWER: {STATE: stateOf(S.answerCard), ...sinks(S.answerCard)},
         CONTROL: (s: any, d: any) => S.controlStep(s, d) || ABORT,
       }),
-    },
+    }),
   })(options)
   // the `prompt` option is a selector, not the slice's start value (defineBehavior's option override)
   b.state = {...b.state, prompt: ''}

package/src/extra/ai/commandBar.ts

@@ -48,7 +48,7 @@
  * It reaches the runtime through the shared link (./link.ts, D283), as `chat` does.
  */
 import xs from 'xstream'
-import {defineBehavior} from '../behaviors'
+import {defineBehavior, fromPrevious} from '../behaviors'
 import {ABORT} from '../../shared'
 import {agentTools, labelsUntrusted} from './agent/index'
 import {decide as decideRequest} from './decide'
@@ -242,7 +242,7 @@ export const commandBar = (options: any = {}): any => {
         ...(deny && {DENY: on(DOM, deny)}),
       }
     },
-    model: {
+    model: fromPrevious({
       INPUT: (s: any, v: any) => typeof v == 'string' && v !== s.text ? {...s, text: v} : ABORT,
       RUN: {
         STATE: (s: any, d: any, _n: any, p: any, o: any, k: string) => runStep(s, d, E(p, k, o))?.s || ABORT,
@@ -275,7 +275,7 @@ export const commandBar = (options: any = {}): any => {
       // a command ran (or was refused): the result; the input is cleared when it was this command
       DONE: (s: any, d: any) => s.status != 'running' ? ABORT
         : {...s, status: 'ready', command: null, pending: null, result: d, text: d?.ok && s.text.trim() === d.command ? '' : s.text},
-    },
+    }),
   })(options)
   return linked(b)
 }

package/src/extra/ai/compose/behavior.ts

@@ -34,7 +34,7 @@
  * reads it as `props.state` (the pre-action state), and one memo per behavior value makes STATE,
  * the sink and EFFECT of one action compute the same step.
  */
-import {defineBehavior} from '../../behaviors'
+import {defineBehavior, fromPrevious} from '../../behaviors'
 import {ABORT} from '../../../shared'
 import {fail} from '../../diagnostics/legacy'
 import {finish, fromTree, removeNode, toTree} from './layout'
@@ -144,7 +144,7 @@ export function composeBehavior(catalog: Catalog, options: any = {}): any {
           .map(({key, name, value}: any) => ({key, name, value}))}),
       }
     },
-    model: {
+    model: fromPrevious({
       PROMPT: (s: any, p: any) => typeof p == 'string' && p !== s.prompt ? {...s, prompt: p} : ABORT,
       COMPOSE: {HOST: host(start), [S]: sink(start)},
       REPLY: {
@@ -178,6 +178,6 @@ export function composeBehavior(catalog: Catalog, options: any = {}): any {
       CONTROL: (s: any, c: any) => c && typeof c.key == 'string' && typeof c.name == 'string'
         ? {...s, ui: {...s.ui, [c.key]: {...s.ui?.[c.key], [c.name]: c.value}}} : ABORT,
       DONE: () => ABORT,
-    },
+    }),
   })(rest)
 }

package/src/extra/ai/transports/shared.ts

@@ -60,8 +60,12 @@ export async function post(url: string, body: any, req: any, signal: AbortSignal
   return res;
 }
 
-/** the SSE frames of a response body: `{ event, data }` (data: the joined data lines) */
-export async function* sse(res: any): AsyncGenerator<{event: string; data: string}> {
+/**
+ * the SSE frames of a response body: `{ event, data }` (data: the joined data lines). PLAN-11
+ * E-1: `meta` (optional) follows the stream's `id` (the last event id, kept across frames) and
+ * `retry` (ms) fields, as EventSource does, for a reconnect
+ */
+export async function* sse(res: any, meta?: {id?: string; retry?: number}): AsyncGenerator<{event: string; data: string}> {
   const reader = res.body.getReader(), dec = new TextDecoder();
   let buf = '', cr = '', done = false;
   try {
@@ -84,6 +88,8 @@ export async function* sse(res: any): AsyncGenerator<{event: string; data: strin
           const v = c < 0 ? '' : line.slice(c + 1).replace(/^ /, '');
           if (field == 'event') event = v;
           else if (field == 'data') data.push(v);
+          else if (meta && field == 'id' && !v.includes('\0')) meta.id = v;
+          else if (meta && field == 'retry' && /^\d+$/.test(v)) meta.retry = +v;
         }
         if (data.length) yield {event, data: data.join('\n')};
       }

package/src/extra/behaviors.ts

@@ -45,6 +45,27 @@
  */
 import xs from './xstreamCompat'
 import {isAbort} from '../shared'
+/** A behavior output's slice from before the action (outputs get the updated one): for a transition shared with STATE */
+export const was = (s: any, p: any, k: string) => p?.previousState ? p.previousState[k] : s
+/**
+ * A behavior model whose outputs compute from the state before the action (its slice and
+ * `props.state`), for behaviors whose STATE and outputs share one transition; STATE / HOST as is
+ */
+export const fromPrevious = (model: any) => {
+  const out: any = {}
+  for (const a in model) {
+    const e = model[a]
+    if (!e || typeof e != 'object') { out[a] = e; continue }
+    const m: any = {}
+    for (const s in e) {
+      const f = e[s]
+      m[s] = s == 'STATE' || s == 'HOST' || typeof f != 'function' ? f
+        : (x: any, d: any, n: any, p: any, o: any, k: string) => f(was(x, p, k), d, n, p?.previousState ? {...p, state: p.previousState} : p, o, k)
+    }
+    out[a] = m
+  }
+  return out
+}
 // a model entry as { sink: fn }: a constant is sent as is, `true` sends the action's data, an
 // EFFECT constant does nothing (as the core treats them)
 const sinksOf = (e: any, S: string): any => {

package/src/extra/diagnostics/checks/fetch.ts

@@ -12,6 +12,9 @@
  * SYG635 — `cache: true` / `staleTime` / `{ prefetch }` sent to a driver without a
  *          `queryCache()` (D88): nothing is cached (warn). The source's `__inspect().cache`
  *          is undefined without one
+ * SYG636 — PLAN-11 U-1: `progress` that can't be reported as asked: on a resource or a
+ *          `batch` request (ignored), or with fetch-only `init` options that XMLHttpRequest
+ *          doesn't support (ignored for that request) (warn)
  *
  * Mechanism: onModel wraps the component's own model stream for every sink whose source
  * takes the `resources` static (makeFetchDriver and renderComponent's HTTP fake) and checks
@@ -24,6 +27,12 @@ import {devReport, once, nameOf} from './shared'
 import {isStandardSchema} from '../../standardSchema'
 
 const IDEMPOTENT = /^(GET|HEAD)$/i
+// PLAN-11 U-1: fetch() init options a progress request (XMLHttpRequest) can't honour
+const XHR_IGNORES = ['keepalive', 'priority', 'cache', 'redirect', 'integrity', 'mode', 'referrer', 'referrerPolicy', 'window', 'duplex']
+const reportProgress = (component: any, sink: string, url: string, why: string, fix: string) => {
+  if (!once(`SYG636:${nameOf(component)}:${url}:${why}`)) return
+  devReport('SYG636', {component, message: `${sink} ${url ? url + ' ' : ''}has progress, but ${why}`, fix, data: {sink, url}})
+}
 
 /** instance → reply key lanes it has sent, and ok name → the other key it was sent under */
 const lanes = new WeakMap<object, {used: Set<string>; keyed: Map<string, string>}>()
@@ -48,7 +57,7 @@ function checkOne(component: any, sink: string, req: any, where: string) {
   if (!req || typeof req !== 'object') return
   const name = nameOf(component)
   const url = typeof req.url === 'string' ? req.url : ''
-  const method = String(req.method || (req.json !== undefined || req.body !== undefined ? 'POST' : 'GET')).toUpperCase()
+  const method = String(req.method || (req.json !== undefined || req.body !== undefined || req.multipart !== undefined ? 'POST' : 'GET')).toUpperCase()
   if ((req.cache === true || req.staleTime != null) && !IDEMPOTENT.test(method) && once(`SYG630:${name}:${method}:${url}`)) {
     devReport('SYG630', {
       component,
@@ -58,6 +67,17 @@ function checkOne(component: any, sink: string, req: any, where: string) {
     })
   }
   if (req.cache === true || req.staleTime != null) reportNoCache(component, sink, req.cache === true ? 'cache: true' : 'staleTime', url)
+  if (req.progress) {
+    if (where.includes('.resources.'))
+      reportProgress(component, sink, url, 'resources report no progress (it is ignored)', 'Send the download as a request with progress and reply actions instead of a resource, or remove progress')
+    else if (req.batch)
+      reportProgress(component, sink, url, 'a batch request reports no progress (it is ignored)', 'Send the parts as separate requests with progress, or remove progress')
+    else {
+      const bad = XHR_IGNORES.filter(k => req.init && req.init[k] !== undefined)
+      if (bad.length) reportProgress(component, sink, url, `it goes over XMLHttpRequest, which ignores init.${bad.join(', init.')}`,
+        `Remove ${bad.join(', ')} from init for this request, or drop progress if the request needs ${bad.length > 1 ? 'them' : 'it'}`)
+    }
+  }
   if ('validate' in req && !isStandardSchema(req.validate) && once(`SYG631:${name}:${url}`)) {
     devReport('SYG631', {
       component,

package/src/extra/diagnostics/checks/forms.ts

@@ -133,14 +133,15 @@ export const formsCheck: DiagnosticCheck = {
       })
       const model = Object.keys(view.model || {}).map(a => a.split('|')[0].trim()), own = ownActions(b)
       const clash = own.includes(o.submit)
-      if (typeof o.submit != 'string' || !model.includes(o.submit) || clash) {
+      // PLAN-11 F-3: with `request`, the form sends the submit itself and `submit` is optional
+      if (o.request ? o.submit !== undefined && (typeof o.submit != 'string' || !model.includes(o.submit) || clash) : typeof o.submit != 'string' || !model.includes(o.submit) || clash) {
         devReport('SYG234', {
           component,
-          message: typeof o.submit != 'string' ? `${name}'s form '${key}' has no submit action, so a valid submit dispatches nothing`
+          message: typeof o.submit != 'string' ? `${name}'s form '${key}' has no submit action and no request, so a valid submit dispatches nothing`
             : clash ? `${name}'s form '${key}' names submit: '${o.submit}', one of the form's own actions; a valid submit dispatches the form's '${key}.${o.submit}'${model.includes(o.submit) ? `, never ${name}'s '${o.submit}' entry` : ''}`
             : `${name}'s form '${key}' dispatches '${o.submit}' on a valid submit, but ${name} has no model entry '${o.submit}'`,
           fix: clash ? SUBMIT_FIX(key, o.submit, own)
-            : `Name a host action and add it to the model: submit: 'SIGN_UP', model: { SIGN_UP: { HTTP: (state, values) => ({ url, json: values, ok: '${key}.DONE', error: '${key}.ERRORS' }) } }`,
+            : `Give the form a request, form(schema, { values, request: { url: '/api/signup' } }) (it sends the valid submit itself), or name a host action and add it to the model: submit: 'SIGN_UP', model: { SIGN_UP: { HTTP: (state, values) => ({ url, json: values, ok: '${key}.DONE', error: '${key}.ERRORS' }) } }`,
           data: {key, submit: o.submit},
         })
       }

package/src/extra/diagnostics/checks/index.ts

@@ -107,6 +107,7 @@ import {nextHooks} from './next'
 
 export {checkEventBus} from './events'
 export {configureStrict, isStrictEnabled} from './strict'
+export {configureTimingAudit, isTimingAuditEnabled} from './timingAudit'
 export type {EventBusSummary} from './events'
 export {RXJS_HINTS} from './rxjsHints'
 export {inspect} from './inspect'

package/src/extra/diagnostics/checks/next.ts

@@ -28,6 +28,7 @@ import {watchMutation} from './state'
 import {checkRequest} from './replies'
 import {check as checkFetch} from './fetch'
 import {checkSentCommand} from './elementCommands'
+import {audited} from './timingAudit'
 import {checkCollection} from './collections'
 import {eventEmitted, actionListener as recentActions} from './inspect'
 import {actionHooks} from './actionLog'
@@ -444,6 +445,8 @@ export function nextHooks(_api: any): any {
     onAction(iv: any, a: any) { log.onAction(iv, a) },
     wrapHandler(iv: any, type: string, sink: string, fn: any) {
       let h = log.wrapHandler(iv, type, sink, fn) || fn
+      // 7.0 timing audit (SYG257, opt-in; checks/timingAudit.ts): checked per call, so turning it on later counts
+      if (on() && sink != 'STATE' && typeof h == 'function') h = audited(fac(iv), type, sink, h)
       // SYG222: the STATE reducers, wrapped (today the check rewrote the instance's model)
       if (on() && sink == 'STATE' && typeof fn == 'function') h = watchMutation(fac(iv), type, h)
       return h === fn ? undefined : h

package/src/extra/diagnostics/checks/public.d.ts

@@ -40,6 +40,18 @@ export interface DiagnosticCheck {
  */
 export function configureStrict(on?: boolean): void
 
+/**
+ * 7.0 timing audit (SYG257, info), for migrating 6.x code: report each output sink that reads a
+ * top-level state field its action's STATE changed (since 7.0 it gets the new value; 6.x gave it
+ * the old one; read props.previousState for the old one). true / false, or undefined for the
+ * default (globalThis.__SYGNAL_TIMING_AUDIT__ === true). Also renderComponent(C, { timingAudit })
+ * and sygnal({ diagnostics: { timingAudit: true } }). Diagnostics must be on.
+ */
+export function configureTimingAudit(on?: boolean): void
+
+/** Whether the timing audit is on. */
+export function isTimingAuditEnabled(): boolean
+
 /** Whether the runtime strict checks are on. */
 export function isStrictEnabled(): boolean
 

package/src/extra/diagnostics/checks/timingAudit.ts

@@ -0,0 +1,47 @@
+/**
+ * The 7.0 timing audit (SYG257, info): since 7.0 a model entry's STATE runs first and every other
+ * sink gets the state it committed (6.x gave them the state from before the action). For code
+ * written for 6.x, this reports each output sink that reads a top-level state field its action's
+ * STATE changed: it gets the new value now. Fix: read `props.previousState.<field>` where the old
+ * value is meant; a read meant to see the new value needs nothing. Opt-in, because in 7.0-native
+ * code reading the new value is the intent. Turn it on with any of:
+ *   - configureTimingAudit(true)                 (this entry)
+ *   - renderComponent(C, { timingAudit: true })  (tests)
+ *   - sygnal({ diagnostics: { timingAudit: true } })  (sygnal/vite, dev)
+ *   - globalThis.__SYGNAL_TIMING_AUDIT__ = true
+ * The flag lives on the core bridge (shared by every copy of this entry and renderComponent).
+ * Mechanism: the dev hook layer's wrapHandler (checks/next.ts) wraps each non-STATE handler and
+ * gives it the state through a Proxy that notes reads of changed top-level fields. Top-level
+ * fields only (a nested change shows as its top-level field changing); once per component name,
+ * action, sink and field. Nothing in production builds.
+ */
+import {bridge, devReport, once} from './shared'
+
+/** Turn the timing audit on (true), off (false), or back to the default (globalThis.__SYGNAL_TIMING_AUDIT__). */
+export function configureTimingAudit(on?: boolean): void {
+  const core = bridge()
+  if (core) core.timingAudit = on
+}
+
+/** Whether the timing audit is on. */
+export function isTimingAuditEnabled(): boolean {
+  const flag = bridge()?.timingAudit
+  return flag === undefined ? (globalThis as any).__SYGNAL_TIMING_AUDIT__ === true : flag === true
+}
+
+/** handler `h` of `f`'s action `type`, sink `sink`, audited (f: the checks' instance facade) */
+export const audited = (f: any, type: string, sink: string, h: any) => (s: any, d: any, nx: any, p: any, ...r: any[]) => {
+  const was = p?.previousState
+  if (!isTimingAuditEnabled() || !was || was === s || !s || typeof s != 'object' || typeof was != 'object' || Array.isArray(s)) return h(s, d, nx, p, ...r)
+  const view = new Proxy(s, {get(t: any, k: any, rcv: any) {
+    if (typeof k == 'string' && k in was && was[k] !== t[k] && once(`SYG257:${f.name}:${type}:${sink}:${k}`))
+      devReport('SYG257', {
+        component: f,
+        message: `${f.name}'s '${type}' ${sink} read state.${k}, which the same action's STATE changed: since 7.0 it gets the new value (6.x gave it the old one)`,
+        fix: `If it meant the value from before the action, read props.previousState.${k} (the 4th argument); if it meant the new value, nothing to change`,
+        data: {action: type, sink, field: k},
+      })
+    return Reflect.get(t, k, rcv)
+  }})
+  return h(view, d, nx, p, ...r)
+}

package/src/extra/diagnostics/codes.ts

@@ -310,6 +310,8 @@ export const CODE_TITLES: Record<string, string> = {
   SYG634: 'latest: true with a computed key',
   // PLAN-3 5-5 (D88)
   SYG635: 'Caching asked for without a queryCache',
+  // PLAN-11 U-1: progress requests (dev entry, fetch.ts)
+  SYG636: "progress that can't be reported as asked",
   // PLAN-4 GS-2: element commands (reported by the dev entry, checks/elementCommands.ts)
   SYG640: 'Element command target not found',
   SYG641: 'Unknown element command',
@@ -369,6 +371,9 @@ export const CODE_TITLES: Record<string, string> = {
   // PLAN-9 X-2: static only (sygnal-check rules/syg253-catalog.js)
   SYG253: 'Misspelled catalog declaration key',
   SYG254: 'Catalog descriptions or options overlap',
+  SYG256: 'Output guard rejects the updated state',
+  SYG257: 'Output reads a field its action changed (7.0 timing audit)',
+  SYG454: 'State binding changed without a new component identity',
   // PLAN-9 H: chat client tools and ask (src/extra/ai/chat/behavior.ts, compose/ask.ts, compose/render.ts)
   SYG160: 'Result part rendered outside a card',
   SYG684: 'Client tool shadows an agent tool',
@@ -481,6 +486,8 @@ export const DEV_CODE_SEVERITY: Record<string, DiagnosticSeverity> = {
   SYG634: 'info',
   // PLAN-3 5-5 (fetch.ts)
   SYG635: 'warn',
+  // PLAN-11 U-1 (fetch.ts)
+  SYG636: 'warn',
   // PLAN-4 GS-2 (checks/elementCommands.ts, through the core bridge; renderComponent too)
   SYG640: 'warn',
   SYG641: 'error',
@@ -597,6 +604,12 @@ export const DEV_CODE_SEVERITY: Record<string, DiagnosticSeverity> = {
   // PLAN-9 X-2: static only (sygnal-check); listed so the entry knows their titles
   SYG253: 'warn',
   SYG254: 'info',
+  // PLAN-12: static only; proven after-state output guard contradiction.
+  SYG256: 'warn',
+  // 7.0: the opt-in timing audit (checks/next.ts; configureTimingAudit)
+  SYG257: 'info',
+  // PLAN-12: static only for legacy (6.x) binding contracts. Sygnal 7 remounts known targets.
+  SYG454: 'warn',
 }
 
 export function getCodeInfo(code: string): DiagnosticCodeInfo | undefined {

package/src/extra/fetchDriver.ts

@@ -9,8 +9,11 @@ import {validateWith} from './standardSchema';
  * declarations in src/index.d.ts and docs/guide/drivers.md. Summary:
  *
  * - Request (sink value): `{ url, ok?, error?, key?, category?, method?, headers?, query?, json?,
- *   body?, latest?, timeoutMs?, parse?, init? }` or a URL string. `json` is stringified with a JSON
- *   content-type; method defaults to POST with a body/json, else GET. `query` is appended as a
+ *   multipart?, body?, latest?, timeoutMs?, parse?, init? }` or a URL string. `json` is stringified
+ *   with a JSON content-type; PLAN-11 U-5: `multipart` (an object) becomes a FormData body (a
+ *   File / Blob a file part, an array repeats the name, null / undefined skipped, an object JSON,
+ *   anything else a string), the content-type left to the browser (its boundary); method defaults
+ *   to POST with a body/json/multipart, else GET. `query` is appended as a
  *   query string (null/undefined values skipped, arrays repeat the key, before any #fragment).
  *   Other fetch options (credentials, mode, cache, ...) go under `init` (R4-5); other top-level
  *   keys are the app's own: not sent, but returned on `request`.
@@ -87,6 +90,15 @@ import {validateWith} from './standardSchema';
  *   the request itself) into requests sent again in parallel and combined, at most 3 deep. One
  *   failure fails the request once (`error.status` / `error.body`). No cache entry sharing, no
  *   per-part retry. The test fake (`_whole`) sends and answers it as one request. decide() uses it.
+ * - PLAN-11 U-1 (D555): `progress: 'ACTION'` replies to the sender with each progress step,
+ *   `progress: true` (or a string with no sender) sends it down `progress(category?)`:
+ *   `{ phase: 'upload' | 'download', loaded, total, fraction, category, request }` (`total` /
+ *   `fraction` null when the length is unknown). Such a request goes over XMLHttpRequest (the
+ *   only transport with upload progress in every engine; S-1), turned back into a Response so
+ *   parsing, status, retry and timeouts are the same. Steps are throttled to one per 50 ms per
+ *   phase, keeping the first and the last. Not for resources or `batch`; never shares a fetch.
+ *   No XMLHttpRequest (Node, a service worker): plain fetch, no steps. The transport is
+ *   `options.XMLHttpRequest`, else the global one, read at request time.
  * - dispose / sink completion aborts everything in flight.
  * - `fetch` is read at request time (options.fetch, else globalThis.fetch), so test stubs work.
  * - PLAN-3 5-1 (H-9): renderComponent's HTTP fake runs this driver over an in-memory fetch;
@@ -177,6 +189,70 @@ const mergeHeaders = (...all: any[]) => {
   return out;
 };
 
+// PLAN-11 U-1: statuses whose Response must have a null body
+const NULL_BODY = [101, 103, 204, 205, 304];
+const abortError = () => typeof DOMException == 'function'
+  ? new DOMException('The operation was aborted.', 'AbortError')
+  : Object.assign(new Error('The operation was aborted.'), {name: 'AbortError'});
+/**
+ * PLAN-11 U-1 (S-1): a fetch-shaped call over XMLHttpRequest that reports progress:
+ * `on(phase, loaded, total)` (total 0 when unknown), at most every 50 ms per phase, always the
+ * first and the final step. Resolves with a real Response (blob body, parsed headers); network
+ * errors and timeouts reject with a TypeError, an abort with an AbortError, like fetch.
+ */
+export const xhrFetch = (X: any, url: string, init: any, on: (phase: string, loaded: number, total: number) => void) => new Promise<any>((res, rej) => {
+  const x = new X();
+  const last: any = {};
+  const step = (phase: string, loaded: number, total: number, final?: any) => {
+    const l = last[phase], now = Date.now();
+    if (l && (l.loaded === loaded || (!final && now - l.at < 50 && !(total && loaded >= total)))) return;
+    last[phase] = {loaded, at: now};
+    on(phase, loaded, total);
+  };
+  const ev = (phase: string) => (e: any) => step(phase, e.loaded, e.lengthComputable ? e.total : 0);
+  x.open(init.method || 'GET', url);
+  x.responseType = 'blob';
+  const h = init.headers || {};
+  Object.keys(h).forEach(k => x.setRequestHeader(k, h[k]));
+  if (init.credentials == 'include') x.withCredentials = true;
+  const sig = init.signal;
+  if (sig) {
+    if (sig.aborted) return rej(abortError());
+    sig.addEventListener?.('abort', () => x.abort(), {once: true});
+  }
+  if (init.body != null && x.upload) {
+    x.upload.onprogress = ev('upload');
+    x.upload.onload = (e: any) => step('upload', e.loaded, e.lengthComputable ? e.total : e.loaded, 1);
+  }
+  x.onprogress = ev('download');
+  x.onload = () => {
+    const size = x.response?.size ?? last.download?.loaded ?? 0;
+    step('download', size, size, 1);
+    const headers: any = typeof Headers == 'function' ? new Headers() : undefined;
+    String(x.getAllResponseHeaders?.() || '').trim().split(/[\r\n]+/).forEach((line: string) => {
+      const i = line.indexOf(':');
+      if (i > 0) try { headers?.append(line.slice(0, i).trim(), line.slice(i + 1).trim()); } catch (_) {}
+    });
+    try {
+      res(new Response(NULL_BODY.includes(x.status) ? null : x.response, {status: x.status, statusText: x.statusText, headers}));
+    } catch (e) { rej(e); }
+  };
+  x.onerror = x.ontimeout = () => rej(new TypeError(`Network request failed: ${url}`));
+  x.onabort = () => rej(abortError());
+  x.send(init.body ?? null);
+});
+
+/** PLAN-11 U-5: a request's `multipart` object as FormData (see the header) */
+export const toFormData = (parts: any) => {
+  const fd = new FormData();
+  Object.keys(parts || {}).forEach(k => [].concat(parts[k]).forEach((v: any) => {
+    if (v == null) return;
+    if (typeof Blob != 'undefined' && v instanceof Blob) fd.append(k, v, (v as any).name ?? 'blob');
+    else fd.append(k, typeof v == 'object' ? JSON.stringify(v) : String(v));
+  }));
+  return fd;
+};
+
 const IDEMPOTENT = /^(GET|HEAD)$/i;
 // D80: an invalidate value matches a request by tag, URL prefix ('/…') or predicate
 export const hit = (x: any, q: any) => {
@@ -199,6 +275,13 @@ export function makeFetchDriver(options: any = {}) {
     // q (the request), timer, f (the fetch it waits on), ok / ko (its outcomes) }
     const inflight = new Map<number, any>();
     const subs = new Set<{l: any; sel: any; err: boolean; ns: any[]}>();
+    // PLAN-11 U-1: progress(category?) listeners (not held while nobody listens)
+    const psubs = new Set<{l: any; sel: any; ns: any[]}>();
+    const emitProgress = (v: any) => psubs.forEach(s => {
+      let m = false;
+      try { m = matches(s, v); } catch (_) {}
+      if (m) try { s.l.next(v); } catch (e) { console.error('[Sygnal] makeFetchDriver: a listener threw', e); }
+    });
     // R4-4: replies held until the first select() listener, failures until the first errors()
     // listener (or the next macrotask, when they're logged if nothing listens)
     const started = [false, false];
@@ -246,6 +329,10 @@ export function makeFetchDriver(options: any = {}) {
       return {
         select: make(false),
         errors: make(true),
+        progress: (sel?: any) => {
+          let sub: any;
+          return xs.create<any>({start: l => { psubs.add((sub = {l, sel, ns})); }, stop: () => { psubs.delete(sub); }});
+        },
         isolateSource: (_: any, scope: any) => source(ns.concat(scope)),
         isolateSink: (sink$: any, scope: any) => sink$.map((req: any) => tagRequest(req, scope)),
         // PLAN-4.6: the same per value (the core scopes a request without a stream per instance)
@@ -351,7 +438,7 @@ export function makeFetchDriver(options: any = {}) {
     const send = (req: any, sender = senderOf(req), rn?: string, after = -1, R?: any, pf?: any): any => {
       if (typeof req == 'string') req = {url: req};
       if (!req || typeof req != 'object' || disposed || !allowed(req, 'makeFetchDriver')) return;
-      const {url, category, method, headers, query, json, body, latest, timeoutMs, parse, abort, init, ok, error, key, resources, refresh, invalidates, updates, retry, validate, prefetch} = req;
+      const {url, category, method, headers, query, json, body, latest, timeoutMs, parse, abort, init, ok, error, key, resources, refresh, invalidates, updates, retry, validate, prefetch, progress} = req;
       if ('invalidate' in req) return inval(req.invalidate);
       if (prefetch) return C && send(prefetch, 0, rn, -1, R, 1);
       if (resources || refresh) {
@@ -389,7 +476,9 @@ export function makeFetchDriver(options: any = {}) {
       }
       const scope = scopeKey(req);
       // reply actions: keyed per (sender, key ?? ok ?? error); a resource per (sender, '\0' + name)
-      const rk = rn !== undefined ? '\0' + rn : !pf && sender !== undefined && (ok || error) ? key ?? ok ?? error : undefined;
+      // PLAN-11 U-1: a progress action is a reply action too (abort on dispose, its own lane)
+      const pr = !pf && rn === undefined && !req.batch && progress;
+      const rk = rn !== undefined ? '\0' + rn : !pf && sender !== undefined && (ok || error || typeof pr == 'string') ? key ?? ok ?? error ?? pr : undefined;
       if (sender !== undefined && (typeof abort == 'string' || (abort && key !== undefined)))
         return cancel(r => r.sender === sender && r.rk === (key ?? abort));
       // per (scope, category): another component's requests are never cancelled
@@ -398,12 +487,16 @@ export function makeFetchDriver(options: any = {}) {
 
       const base = options.init;
       // a request's URL and fetch() init (the batch's sub-requests inherit the request's fields)
-      const prep = ({url, method, headers, query, json, body, init: own}: any) => {
+      const prep = ({url, method, headers, query, json, multipart, body, init: own}: any) => {
         const h = mergeHeaders(options.headers, base?.headers, own?.headers, headers);
         let b = body ?? own?.body;
         if (json !== undefined) {
           b = JSON.stringify(json);
           if (!Object.keys(h).some(k => k.toLowerCase() == 'content-type')) h['content-type'] = 'application/json';
+        } else if (multipart !== undefined) {
+          b = toFormData(multipart);
+          // the browser writes multipart/form-data with its boundary; a content-type set here would break it
+          Object.keys(h).forEach(k => { if (k.toLowerCase() == 'content-type') delete h[k]; });
         }
         return [withQuery((options.baseUrl || '') + (url ?? ''), query), {...pickInit(base), ...pickInit(own), method: method || own?.method || base?.method || (b !== undefined ? 'POST' : 'GET'), headers: h, body: b}];
       };
@@ -413,7 +506,8 @@ export function makeFetchDriver(options: any = {}) {
       // parts, at most 3 deep), their parsed bodies merged by `combine` into one reply. The test
       // fake (_whole) answers such a request as one
       const {batch, split, combine = (x: any) => x} = options._whole ? {} as any : req;
-      const k = C?.key(req, rn !== undefined || pf);
+      // PLAN-11 U-1: a progress request never shares a fetch (each sender gets its own steps)
+      const k = pr ? undefined : C?.key(req, rn !== undefined || pf);
       const id = ++seq;
       const r: any = {category, scope, sender, rk};
       inflight.set(id, r);
@@ -449,7 +543,18 @@ export function makeFetchDriver(options: any = {}) {
         const parser = parserOf(parse || options.parse);
         // the global fetch is called as a method: a detached window.fetch throws "Illegal invocation"
         const g: any = globalThis;
-        const doFetch = options.fetch || (typeof g.fetch == 'function' && ((u: string, i: any) => g.fetch(u, i)));
+        let doFetch = options.fetch || (typeof g.fetch == 'function' && ((u: string, i: any) => g.fetch(u, i)));
+        // PLAN-11 U-1: a progress request over XMLHttpRequest (renderComponent's fake: `_progress`)
+        const X = options.XMLHttpRequest ?? g.XMLHttpRequest;
+        if (pr && (options._progress || typeof X == 'function')) {
+          const step = (phase: string, loaded: number, total: number) => {
+            if (!inflight.has(id) || disposed) return;
+            const t = total > 0 ? total : null;
+            const v = {phase, loaded, total: t, fraction: t ? Math.min(1, loaded / t) : null, category, request: req};
+            typeof pr == 'string' && sender !== undefined ? reply(sender, pr, v) : emitProgress(v);
+          };
+          doFetch = options._progress ? (u: string, i: any) => options._progress(u, i, step, req) : (u: string, i: any) => xhrFetch(X, u, i, step);
+        }
         // the outcome, to every request waiting on this fetch (the failure once, after the last attempt)
         const end = (e: any, x?: any, status?: number) => {
           done(F);