sygnal 6.6.0 → 7.0.0

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