sygnal 6.5.0 → 7.0.0

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);

package/src/extra/fetchEventSource.ts

@@ -0,0 +1,113 @@
+import {sse} from './ai/transports/shared';
+
+/*
+ * PLAN-11 E-1: an EventSource over fetch, for server-sent events that need request headers
+ * (`Authorization`), which the native EventSource can't send. makeSocketDriver uses it for an
+ * `sse` connection with `headers`. It behaves as EventSource does where the driver relies on it:
+ *
+ * - connects on construction (a microtask later, so handlers can be set first); `readyState`
+ *   CONNECTING (0) → OPEN (1) on a 2xx `text/event-stream` response;
+ * - `onmessage` and `addEventListener(type)` get `{ type, data, lastEventId }`;
+ * - the stream ending or a network error: `error`, readyState CONNECTING, a reconnect after
+ *   `retry` ms (the stream's `retry:` field, default 3000) with `Last-Event-ID`;
+ * - a non-2xx status or another content type: `error` with readyState CLOSED (no retry; the
+ *   driver's reconnect policy decides);
+ * - `close()` aborts the request and stops retrying.
+ */
+
+const NAMES = ['CONNECTING', 'OPEN', 'CLOSED'];
+
+export class FetchEventSource {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSED = 2;
+  readyState = 0;
+  url: string;
+  withCredentials: boolean;
+  onopen: any = null;
+  onmessage: any = null;
+  onerror: any = null;
+  private ls = new Map<string, Set<(e: any) => void>>();
+  private meta: {id?: string; retry?: number} = {id: '', retry: 3000};
+  private ctl: any;
+  private timer: any;
+  private init: any;
+
+  constructor(url: string, init: {withCredentials?: boolean; headers?: Record<string, string>; fetch?: any} = {}) {
+    this.url = url;
+    this.withCredentials = !!init.withCredentials;
+    this.init = init;
+    queueMicrotask(() => this.connect());
+  }
+
+  addEventListener(type: string, f: (e: any) => void) {
+    let s = this.ls.get(type);
+    if (!s) this.ls.set(type, (s = new Set()));
+    s.add(f);
+  }
+  removeEventListener(type: string, f: (e: any) => void) { this.ls.get(type)?.delete(f); }
+
+  close() {
+    this.readyState = 2;
+    clearTimeout(this.timer);
+    try { this.ctl?.abort(); } catch (_) {}
+  }
+
+  private emit(type: string, ev: any) {
+    if (type == 'message') this.onmessage?.(ev);
+    else if (type == 'open') this.onopen?.(ev);
+    else if (type == 'error') this.onerror?.(ev);
+    this.ls.get(type)?.forEach(f => { try { f(ev); } catch (e) { console.error(e); } });
+  }
+
+  private async connect() {
+    if (this.readyState == 2) return;
+    const g: any = globalThis;
+    const f = this.init.fetch || (typeof g.fetch == 'function' && ((u: string, i: any) => g.fetch(u, i)));
+    if (typeof f != 'function') return this.fail(new Error('fetch is not available in this environment'));
+    const ctl: any = this.ctl = typeof AbortController == 'function' ? new AbortController() : {};
+    const headers: Record<string, string> = {accept: 'text/event-stream', ...this.init.headers};
+    if (this.meta.id) headers['last-event-id'] = this.meta.id;
+    let res: any;
+    try {
+      res = await f(this.url, {headers, credentials: this.withCredentials ? 'include' : 'same-origin', cache: 'no-store', signal: ctl.signal});
+    } catch (error) {
+      return this.retry(error);
+    }
+    if (this.readyState == 2 || this.ctl !== ctl) return;
+    const type = res.headers?.get?.('content-type') || '';
+    if (!(res.status >= 200 && res.status < 300) || !/^text\/event-stream/i.test(type) || !res.body) {
+      try { res.body?.cancel?.(); } catch (_) {}
+      return this.fail(Object.assign(new Error(`SSE ${res.status}${type ? ' ' + type : ''}: ${this.url}`), {status: res.status}));
+    }
+    this.readyState = 1;
+    this.emit('open', {type: 'open'});
+    try {
+      for await (const fr of sse(res, this.meta)) {
+        if (this.readyState == 2 || this.ctl !== ctl) return;
+        this.emit(fr.event, {type: fr.event, data: fr.data, lastEventId: this.meta.id});
+      }
+    } catch (error) {
+      if (this.readyState == 2 || this.ctl !== ctl) return;
+      return this.retry(error);
+    }
+    if (this.readyState != 2 && this.ctl === ctl) this.retry();
+  }
+
+  /** a drop: error, CONNECTING, try again after `retry` ms (unless the error handler closed it) */
+  private retry(error?: any) {
+    if (this.readyState == 2) return;
+    this.readyState = 0;
+    this.emit('error', {type: 'error', error});
+    if (this.readyState == 2) return;
+    this.timer = setTimeout(() => this.connect(), this.meta.retry);
+  }
+  /** a failed connection: error, CLOSED */
+  private fail(error: any) {
+    this.readyState = 2;
+    this.emit('error', {type: 'error', error});
+  }
+
+  /** the state's name (debugging) */
+  get state() { return NAMES[this.readyState]; }
+}

package/src/extra/form.ts

@@ -13,7 +13,12 @@
  * field.
  *
  * Options: `values` (the start values; D239: or a function of the host's state, called when the
- * form starts), `submit` (host action), `check` (async per-field checks through a driver: a
+ * form starts), `submit` (host action), `request` (PLAN-11 F-3: the form sends the valid submit
+ * itself on the `http` sink: a request, or `(data, hostState) => request`, completed with the
+ * body (`multipart: data` when a top-level value is a File / Blob or an array of them, else
+ * `json: data`, unless it sets json / multipart / body), `progress: '<key>.PROGRESS'` (unless set)
+ * and its own `ok: '<key>.DONE'`, `error: '<key>.ERRORS'`; with `submit` too, that host action is
+ * still dispatched (for state), and should send no request), `check` (async per-field checks through a driver: a
  * request with a reply action, `latest`), `show` ('blur' default: a schema error shows once its
  * field was blurred; 'input'; 'submit'), `form` (selector), `http` (the driver sink of the
  * checks, 'HTTP'), `resetOnShow` (D239), `tool` (PLAN-6 A-3, experimental: `formTool({ … })` from
@@ -32,6 +37,8 @@
  * before that (a child's first render) the fields come from calling it with a blank state.
  *
  * Slice (state.form): values, initial, errors (all current schema errors by name), touched,
+ * progress (PLAN-11 F-2: the submit's last progress step or null), resets (counts RESET and
+ * resetOnShow starts: key a file input with it, since a file input can't be cleared by state),
  * server (server errors), remote (async check results: '' passed), pending (name -> value being
  * checked), submitting, submitted, submitCount, queued (a submit waits for a check or an async
  * schema), validating (an async schema runs), validated (the schema has answered since the start
@@ -41,11 +48,14 @@
  *
  * Actions: form.CHANGE ({ name, value, item? }: G-376: a checkbox gives `checked`, and `item`, its
  * value, which toggles membership when the field is an array; <select multiple> an array of the
- * selected values; type=file is ignored), form.SET ({ values }: G-647, field name -> value, several
+ * selected values; PLAN-11 F-2: a file input its File, `multiple` an array of them, none null),
+ * form.SET ({ values }: G-647, field name -> value, several
  * fields changed at once as if typed: one validation, `touched` as for CHANGE, unknown names
  * skipped; e.g. an AI fill), form.BLUR (name), form.SUBMIT, form.ADD ({ field,
  * value }), form.REMOVE ({ field, id }), form.ERRORS (an error reply or a map: server errors),
- * form.DONE (saved), form.RESET (values?); internal: form.RESULT (an async schema's result),
+ * form.DONE (saved), form.RESET (values?), form.PROGRESS (PLAN-11 F-2: a progress step of the
+ * submit request, `progress: 'form.PROGRESS'`: kept as `progress` while submitting, cleared by
+ * DONE / ERRORS / RESET); internal: form.RESULT (an async schema's result),
  * form.CHECKED_<name> (a check's reply; a failed check passes: the server checks on submit),
  * form.VALIDATE (the first validation, when the host starts: G-375; `valid` is false until the
  * schema answered; with resetOnShow also each time the form element appears, D239).
@@ -70,13 +80,20 @@
  * run when the host is created.
  */
 import xs from './xstreamCompat'
-import {defineBehavior} from './behaviors'
+import {defineBehavior, was} from './behaviors'
 import {ABORT} from '../shared'
 import {isStandardSchema} from './standardSchema'
-import {checkForm, fieldNames, getField, hasField, setField, replyErrors, focusInvalid} from './formHelpers'
+import {checkForm, fieldNames, getField, hasField, setField, replyErrors, focusInvalid, isFile} from './formHelpers'
+
+// PLAN-11 F-3: a submit's data goes as multipart when a top-level value is a file (or files)
+const hasFile = (d: any) => !!d && typeof d == 'object' && Object.values(d).some(x => isFile(x) || Array.isArray(x) && x.some(isFile))
 
 const dev = (...a: any[]): any => (globalThis as any).__SYGNAL_DIAGNOSTICS__?.form?.(...a)
 const keys = (o: any) => Object.keys(o).filter(k => o[k])
+// PLAN-11 F-2: values compared as JSON, a File by identity-ish fields (JSON gives every File {})
+const fileIds = new WeakMap<object, number>()
+let fileSeq = 0
+const json = (v: any) => JSON.stringify(v, (_k, x) => isFile(x) ? `\0file:${fileIds.get(x) ?? (fileIds.set(x, ++fileSeq), fileSeq)}` : x)
 const drop = (o: any, p: string) => {
   const r: any = {}
   for (const k in o) if (k != p && !k.startsWith(p + '.')) r[k] = o[k]
@@ -85,7 +102,7 @@ const drop = (o: any, p: string) => {
 
 export const form = (schema: any, o: any = {}): any => {
   isStandardSchema(schema) || dev(231, schema)
-  const {values: vo = {}, submit, check: checks = {}, show = 'blur', http = 'HTTP', form: sel = 'form', resetOnShow: again} = o
+  const {values: vo = {}, submit, request: rq, check: checks = {}, show = 'blur', http = 'HTTP', form: sel = 'form', resetOnShow: again} = o
   // D239: `values` can be a function of the host's state, called when the form starts (and each
   // show, resetOnShow). Before that (the host's first render, before its first action) the
   // fields come from calling it with a blank state: every read gives '' in the result
@@ -137,10 +154,11 @@ export const form = (schema: any, o: any = {}): any => {
       : Object.keys(s.pending).length ? {s: {...s, queued: true}}
       : {s: req ? {...s, queued: false, submitting: true} : done({...s, queued: false}), send: 1}
   }
-  const base = (vals: any) => ({initial: vals, values: vals, touched: {}, server: {}, remote: {}, pending: {},
-    submitting: false, submitted: false, submitCount: 0, queued: false, errors: {}, validated: false})
-  const fresh = (vals: any) => edit(base(vals), vals)
-  const done = (s: any) => ({...s, submitting: false, submitted: true, initial: s.values, server: {}, touched: {}})
+  const base = (vals: any, resets = 0) => ({initial: vals, values: vals, touched: {}, server: {}, remote: {}, pending: {},
+    submitting: false, submitted: false, submitCount: 0, queued: false, errors: {}, validated: false, progress: null, resets})
+  // a start over (RESET, resetOnShow): `resets` counts them, so a file input keyed by it is made anew
+  const fresh = (vals: any, s?: any) => edit(base(vals, s ? (s.resets || 0) + 1 : 0), vals)
+  const done = (s: any) => ({...s, submitting: false, submitted: true, initial: s.values, server: {}, touched: {}, progress: null})
   const group = (cur: any, d: any) => {
     if (!Array.isArray(cur) || !('item' in d)) return d.value
     const r = cur.filter(x => x !== d.item)
@@ -149,9 +167,9 @@ export const form = (schema: any, o: any = {}): any => {
 
   // fields changed as typed ones ([name, value] pairs; unknown names skipped, SYG230): their
   // server errors, check results and running checks go, `touched` as show 'input' says; one validation
-  const put = (s: any, d: any[]) => {
+  const put = (s: any, d: any[], quiet?: any) => {
     let vals = s.values, server = drop(s.server, ''), remote = s.remote, pending = s.pending, touched = s.touched
-    for (const [n, y] of d) if (known(s, n)) {
+    for (const [n, y] of d) if (known(s, n, quiet)) {
       vals = setField(vals, n, y), server = drop(server, n), remote = drop(remote, n), pending = drop(pending, n)
       if (show == 'input') touched = {...touched, [n]: true}
     }
@@ -161,7 +179,9 @@ export const form = (schema: any, o: any = {}): any => {
   const steps: Record<string, (s: any, d: any, k: string, h?: any) => any> = {
     // G-376: a checkbox (`item`: its value) on an array field is one of a group: checked adds
     // its value, unchecked removes it
-    CHANGE: (s, d) => put(s, d?.name ? [[d.name, group(getField(s.values, d.name), d)]] : []),
+    // PLAN-11 F-2: a file input whose name isn't in values is left alone, quietly (an app that reads
+    // its files in its own intent, as before 6.7)
+    CHANGE: (s, d) => put(s, d?.name ? [[d.name, group(getField(s.values, d.name), d)]] : [], d?.file),
     BLUR: (s, n, k) => {
       if (!known(s, n, 1)) return null
       const t = show == 'submit' || s.touched[n] ? s.touched : {...s.touched, [n]: true}, x = {...s, touched: t}
@@ -192,16 +212,20 @@ export const form = (schema: any, o: any = {}): any => {
     SET: (s, d) => put(s, Object.entries(d?.values || {})),
     ERRORS: (s, d) => {
       const e = replyErrors(d, s.values)
-      return {s: {...s, server: e, submitting: false, queued: false}, focus: focusInvalid(e, sel)}
+      return {s: {...s, server: e, submitting: false, queued: false, progress: null}, focus: focusInvalid(e, sel)}
     },
     DONE: (s) => ({s: done(s)}),
-    RESET: (s, d) => fresh(d && typeof d == 'object' ? d : s.initial),
+    // PLAN-11 F-2: a progress step of the submit's request (`progress: 'form.PROGRESS'`), while it is pending
+    PROGRESS: (s, d) => s.submitting && d && typeof d == 'object'
+      ? {s: {...s, progress: {phase: d.phase, loaded: d.loaded, total: d.total ?? null, fraction: d.fraction ?? null}}} : null,
+    // PLAN-11: only a plain object is new values (a click event from `DOM.click('.reset')` is not)
+    RESET: (s, d) => fresh(d && typeof d == 'object' && [Object.prototype, null].includes(Object.getPrototypeOf(d)) ? d : s.initial, s),
     // G-375: the first validation, when the host starts (form() doesn't validate at module load).
     // G-575: a slice kept in parent state from a host that unmounted mid-submit starts unstuck.
     // D239: with resetOnShow (also each time the form element appears again), or a `values`
     // function not called yet, the slice starts over from the start values (h: the host state)
-    VALIDATE: (s, _, _k, h) => again || fn && s.values === values ? fresh(fn ? vo(h) : vo)
-      : edit({...s, submitting: false, queued: false, pending: {}}, s.values),
+    VALIDATE: (s, _, _k, h) => again || fn && s.values === values ? fresh(fn ? vo(h) : vo, again && s)
+      : edit({...s, submitting: false, queued: false, pending: {}, progress: null}, s.values),
   }
   // a check's reply (ok and error: an error reply carries an Error and passes)
   for (const f of checked) steps['CHECKED_' + f] = (s, d, k) => {
@@ -210,6 +234,14 @@ export const form = (schema: any, o: any = {}): any => {
     return s.queued ? attempt(n, k) : {s: n}
   }
 
+  // PLAN-11 F-3: the `request` option's request for a valid submit (data: the schema's output)
+  const send = (vals: any, h: any, k: string) => {
+    const data = v(vals).value, q = typeof rq == 'function' ? rq(data, h) : rq
+    if (!q || q === ABORT) return ABORT
+    const own = 'json' in q || 'multipart' in q || 'body' in q
+    return {...(!own && (hasFile(data) ? {multipart: data} : {json: data})), progress: `${k}.PROGRESS`, ...q, ok: `${k}.DONE`, error: `${k}.ERRORS`}
+  }
+
   const model: any = {}
   for (const a in steps) {
     let last: any[] = []
@@ -219,19 +251,27 @@ export const form = (schema: any, o: any = {}): any => {
       // VALIDATE: on the host's state (HOST), for a `values` function; the slice's own steps on it
       ...a == 'VALIDATE' ? {HOST: (h: any, d: any, _n: any, _p: any, _o: any, k: string) => { const x = out(h[k], d, k, h); return x ? {...h, [k]: x.s} : h }}
         : {STATE: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.s || ABORT},
-      EFFECT: (s: any, d: any, next: any, _p: any, _o: any, k: string) => {
+      // outputs share STATE's transition: computed from the slice before the action
+      EFFECT: (s: any, d: any, next: any, p: any, _o: any, k: string) => {
+        s = was(s, p, k)
         const x = out(s, d, k), w = x?.wait
         if (x?.send) {
           const r = v(x.s.values).value
           dev(233, s.values, r)
           // G-577: a submit named after one of the form's own actions goes to that one
           submit in steps && dev(234, submit, k, b)
-          next(submit, r, 0)
+          // PLAN-11 F-3: with `request`, `submit` is optional (dispatched for state when given)
+          if (submit !== undefined || !rq) next(submit, r, 0)
         }
         w && Promise.resolve(v(w.values)).then(() => next('RESULT', w, 0))
       },
-      ELEMENT: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.focus || ABORT,
-      ...(checked.length && {[http]: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.req || ABORT}),
+      ELEMENT: (s: any, d: any, _n: any, p: any, _o: any, k: string) => out(was(s, p, k), d, k)?.focus || ABORT,
+      // the checks' requests, and (PLAN-11 F-3) the `request` option's for a valid submit; the
+      // step from the slice before the action (7.0: outputs get the updated one), the host state as committed
+      ...((checked.length || rq) && {[http]: (s: any, d: any, _n: any, p: any, _o: any, k: string) => {
+        const x = out(was(s, p, k), d, k)
+        return x?.req || (x?.send && rq ? send(x.s.values, p?.state, k) : ABORT)
+      }}),
     }
   }
 
@@ -248,9 +288,11 @@ export const form = (schema: any, o: any = {}): any => {
         VALIDATE: again ? xs.merge(xs.of(0), f.elements().filter((e: any) => { const r = e.length && !on; on = e.length; return r })) : xs.of(0),
         // G-376: a checkbox (native, or a hyphenated tag with a boolean `checked`: a
         // form-associated custom checkbox / switch) gives `checked` and its value as `item`; a
-        // <select multiple> the selected values; type=file is left alone; others give `value`
-        CHANGE: f.events('input').filter(({target: t}: any) => t.type != 'file').map(({target: t}: any) =>
-          t.type == 'checkbox' || /-/.test(t.tagName) && typeof t.checked == 'boolean' ? {name: t.name, value: t.checked, item: t.value}
+        // <select multiple> the selected values; PLAN-11 F-2: a file input its File (`multiple`:
+        // an array of them; none: null); others give `value`
+        CHANGE: f.events('input').map(({target: t}: any) =>
+          t.type == 'file' ? {name: t.name, value: t.multiple || t.getAttribute?.('multiple') != null ? [...(t.files || [])] : t.files?.[0] ?? null, file: true}
+          : t.type == 'checkbox' || /-/.test(t.tagName) && typeof t.checked == 'boolean' ? {name: t.name, value: t.checked, item: t.value}
           : {name: t.name, value: t.type == 'select-multiple' ? [...t.selectedOptions].map((o: any) => o.value) : t.value}),
         BLUR: f.events('focusout').map((e: any) => e.target.name),
         SUBMIT: f.events('submit', {preventDefault: true}),
@@ -269,7 +311,7 @@ export const form = (schema: any, o: any = {}): any => {
       },
       // G-382: an async schema re-validating keeps the last answer's validity (no flicker)
       valid: (s: any) => s.validated && !keys(s.errors).length && !keys(s.remote).length,
-      dirty: (s: any) => JSON.stringify(s.values) != JSON.stringify(s.initial),
+      dirty: (s: any) => json(s.values) != json(s.initial),
       error: (s: any) => s.server[''] || (s.submitCount && s.errors['']) || '',
     },
   })({...o, values}), merge = b.merge
@@ -277,7 +319,7 @@ export const form = (schema: any, o: any = {}): any => {
   o.tool?.$?.(b, v)
   b.merge = (c: any, k: string) => {
     const e = c.model?.[submit]
-    req = !!e && typeof e == 'object' && http in e
+    req = !!rq || !!e && typeof e == 'object' && http in e
     merge(c, k)
   }
   return b

package/src/extra/formHelpers.ts

@@ -21,6 +21,8 @@ export type FieldErrors = Record<string, string>
 export type FormCheck = {errors: FieldErrors; value: any}
 
 const isRow = (r: any) => r?.id != null
+/** PLAN-11 F-2: a File / Blob is a field value (a leaf), not an object of fields */
+export const isFile = (v: any) => typeof Blob != 'undefined' && v instanceof Blob
 // the key of segment `s` in `v`: an array's row with that id, else the index unless the element
 // there is a row (G-380: a row is named by its id only; -1, no element), an object's key
 const key = (v: any, s: string): any => {
@@ -70,7 +72,7 @@ export const setField = (values: any, name: string, value: any): any => {
  * array-level error such as "at least one address"); a row's `id` is not a field
  */
 export const fieldNames = (v: any, at = '', row?: boolean): string[] => {
-  if (!v || typeof v != 'object') return at ? [at] : []
+  if (!v || typeof v != 'object' || isFile(v)) return at ? [at] : []
   const a = Array.isArray(v), out = a ? [at] : []
   for (const k in v) {
     const x = (v as any)[k]

package/src/extra/lens.ts

@@ -5,11 +5,12 @@
  * is gone); set: the array with that element replaced (the state unchanged when it is gone).
  * Side-effect free.
  */
-export const byId = (field: string, id: any, idKey = 'id') => ({
+import {BINDING} from '../shared'
+export const byId = (field: string, id: any, idKey = 'id') => Object.defineProperty({
   get: (s: any) => (Array.isArray(s?.[field]) ? s[field].find((x: any) => x?.[idKey] === id) : undefined),
   set: (s: any, v: any) => {
     const a = s?.[field]
     if (!Array.isArray(a) || !a.some((x: any) => x?.[idKey] === id)) return s
     return {...s, [field]: a.map((x: any) => (x?.[idKey] === id ? v : x))}
   },
-})
+}, BINDING, {value: [field, id, idKey]})

package/src/extra/queryCache.ts

@@ -43,9 +43,10 @@ export function queryCache(o: any = {}): any {
   // the key of a cacheable request (else undefined); `res`: a resource's
   const key = (q: any, res?: any) => {
     if (typeof q == 'string') q = {url: q};
-    const {method, json, body, parse, query} = q;
-    const m = (method || (json !== undefined || body !== undefined ? 'POST' : 'GET')).toUpperCase();
-    const b = json !== undefined ? JSON.stringify(json) : body ?? '';
+    const {method, json, body, parse, query, multipart} = q;
+    const m = (method || (json !== undefined || body !== undefined || multipart !== undefined ? 'POST' : 'GET')).toUpperCase();
+    // PLAN-11 U-5: a multipart request is never cached (its body isn't a string)
+    const b = json !== undefined ? JSON.stringify(json) : multipart !== undefined ? multipart : body ?? '';
     if (q.cache === false || typeof b != 'string' || typeof parse == 'function' || parse == 'response' ||
       !(q.cache || q.staleTime != null || (res && IDEMPOTENT.test(m)))) return;
     return [m, withQuery(q.url ?? '', query, 1), b, parse].join(' ').trim();

package/src/extra/socketDriver.ts

@@ -2,6 +2,7 @@ import xs, {Stream} from 'xstream';
 import {senderOf, keepSender, allowed, makeReplies} from './replies';
 import {error as logError} from './diagnostics/legacy';
 import {backoff} from './backoff';
+import {FetchEventSource} from './fetchEventSource';
 
 /*
  * makeSocketDriver(options?) (PLAN-3 §1.3): WebSocket and server-sent events, declared per
@@ -11,7 +12,7 @@ import {backoff} from './backoff';
  * - Sink values:
  *   - `{ connections: { [name]: spec | falsy } }`: the sender's whole set of connections. Diffed
  *     per (sender, name): a new name opens, a removed or falsy one closes, a changed URL /
- *     protocols / withCredentials / share closes and reopens, anything else (action names,
+ *     protocols / withCredentials / headers / share closes and reopens, anything else (action names,
  *     reconnect) only rebinds.
  *   - `{ to: name, json? | text? | binary? }`: send on the sender's connection `name` (json is
  *     stringified). Queued while (re)connecting, bounded (`queueLimit`, oldest dropped). A send
@@ -36,6 +37,10 @@ import {backoff} from './backoff';
  * - A disposed sender's connections close (and their retries stop); app dispose closes all.
  * - No WebSocket / EventSource (SSR): nothing opens, nothing is reported.
  * - `WebSocket` / `EventSource` are read at connect time: options.WebSocket ?? globalThis.WebSocket.
+ * - PLAN-11 E-1: an `sse` connection with `headers` (data: a token in it comes from state, and a
+ *   changed header reconnects) is read with FetchEventSource (fetch, `options.fetch` if given),
+ *   since EventSource can't send headers. An `options.EventSource` (a polyfill, the test fake)
+ *   still wins and gets the headers in its init.
  */
 
 const SCOPE = '__sygnalScope';
@@ -118,11 +123,12 @@ export function makeSocketDriver(options: any = {}) {
 
     const connect = (t: any) => {
       t.timer = 0;
-      const C = t.sse ? options.EventSource ?? g.EventSource : options.WebSocket ?? g.WebSocket;
+      const hdr = t.sse && t.spec.headers && typeof t.spec.headers == 'object' ? t.spec.headers : undefined;
+      const C = t.sse ? options.EventSource ?? (hdr && typeof g.fetch == 'function' ? FetchEventSource : g.EventSource) : options.WebSocket ?? g.WebSocket;
       if (typeof C != 'function') return;
       let s: any;
       try {
-        s = t.sse ? new C(t.url, {withCredentials: !!t.spec.withCredentials}) : new C(t.url, t.spec.protocols);
+        s = t.sse ? new C(t.url, {withCredentials: !!t.spec.withCredentials, ...(hdr && {headers: hdr, fetch: options.fetch})}) : new C(t.url, t.spec.protocols);
       } catch (error) {
         // a URL the constructor rejects never opens: no retry
         each(t, e => deliver(e, 'error', {error}));
@@ -201,7 +207,7 @@ export function makeSocketDriver(options: any = {}) {
         const sse = typeof spec.sse == 'string';
         const url = resolve(sse ? spec.sse : spec.socket, sse);
         // the connection's identity: a change reconnects, anything else only rebinds
-        const key = (spec.share === false ? 'u' : '') + (sse ? 'e' + !!spec.withCredentials : 's' + JSON.stringify(spec.protocols)) + url;
+        const key = (spec.share === false ? 'u' : '') + (sse ? 'e' + !!spec.withCredentials + (spec.headers ? JSON.stringify(spec.headers) : '') : 's' + JSON.stringify(spec.protocols)) + url;
         if (old && old.key === key) {
           old.spec = spec;
           if (old.t) listen(old.t);