sygnal 7.0.0 → 7.1.0

package/src/extra/ssr.ts

@@ -147,7 +147,7 @@ function withUses(def: any, state: any): any {
  * state reads from the cache ('success' with the cached data), else 'loading' ('idle' for a
  * falsy request), as the client's first paint does with the same (hydrated) cache
  */
-function withResources(def: any, state: any): any {
+function withResources(def: any, state: any, ctx?: any): any {
   state = withUses(def, state)
   const res = def && def.resources
   if (!res || !state || typeof state !== 'object' || Array.isArray(state)) return state
@@ -155,7 +155,7 @@ function withResources(def: any, state: any): any {
   for (const n of Object.keys(res)) {
     if (out[n] !== undefined) continue
     let q: any
-    try { q = typeof res[n] === 'function' ? res[n](state) : res[n] } catch (_) {}
+    try { q = typeof res[n] === 'function' ? res[n](state, ctx) : res[n] } catch (_) {}
     const E = q && ssrCache ? ssrCache.get(ssrCache.key(q, 1)) : undefined
     out[n] = E && E.at > 0 ? {status: 'success', data: E.v} : {status: q ? 'loading' : 'idle'}
   }
@@ -198,10 +198,26 @@ function viewFailed(def: any, err: any, name: string): any {
   return vnode
 }
 
-function collectHead(def: any, state: any): void {
+function collectHead(def: any, state: any, ctx?: any): void {
   const h = def && def.head
   if (!heads || !h) return
-  try { heads.push(typeof h === 'function' ? h(state) : h) } catch (_) {}
+  try { heads.push(typeof h === 'function' ? h(state, ctx) : h) } catch (_) {}
+}
+
+/**
+ * PLAN-13 F-1: the context a component sees (its parent's, plus its own entries computed on
+ * `state`). The statics get it as on the client; for `resources` it is computed on the state
+ * before the resources are filled in (a context entry can't read the component's own resource)
+ */
+function contextOf(def: any, state: any, parent: Record<string, any>): Record<string, any> {
+  const own = def.context || {}, out: Record<string, any> = {...parent}
+  for (const key of Object.keys(own)) {
+    const f = own[key]
+    if (typeof f === 'function' && state != null) {
+      try { out[key] = f(state) } catch (_) {}
+    }
+  }
+  return out
 }
 
 /**
@@ -245,20 +261,11 @@ function renderRoot(componentDef: any, options: RenderToStringOptions): string {
 
   const ownState = state !== undefined ? state : componentDef.initialState
   // 5-5: the view sees its resources; the hydration script keeps the state as it was given
-  const resolvedState = withResources(componentDef, ownState)
-  collectHead(componentDef, resolvedState)
+  const resolvedState = withResources(componentDef, ownState, contextOf(componentDef, ownState, context))
 
   // Build context: merge parent context with component's own context definitions
-  const componentContext = componentDef.context || {}
-  const mergedContext: Record<string, any> = {...context}
-  for (const key of Object.keys(componentContext)) {
-    const contextFn = componentContext[key]
-    if (typeof contextFn === 'function' && resolvedState != null) {
-      try {
-        mergedContext[key] = contextFn(resolvedState)
-      } catch (_) {}
-    }
-  }
+  const mergedContext = contextOf(componentDef, resolvedState, context)
+  collectHead(componentDef, resolvedState, mergedContext)
 
   // Call the view function
   let vnode: any
@@ -474,19 +481,10 @@ function renderSubComponent(vnode: any, context: Record<string, any>, parentStat
     // State passed directly
     childState = stateProp
   }
-  childState = withResources(componentDef, childState)
+  childState = withResources(componentDef, childState, contextOf(componentDef, childState, context))
 
   // Build child context
-  const childContext: Record<string, any> = {...context}
-  const componentContext = componentDef.context || {}
-  for (const key of Object.keys(componentContext)) {
-    const contextFn = componentContext[key]
-    if (typeof contextFn === 'function' && childState != null) {
-      try {
-        childContext[key] = contextFn(childState)
-      } catch (_) {}
-    }
-  }
+  const childContext = contextOf(componentDef, childState, context)
 
   // Extract slots from children
   const slots: Record<string, any[]> = {}
@@ -507,7 +505,7 @@ function renderSubComponent(vnode: any, context: Record<string, any>, parentStat
     slots.default.push(...defaultSlotChildren)
   }
 
-  collectHead(componentDef, childState)
+  collectHead(componentDef, childState, childContext)
 
   // Call the view function
   let result: any
@@ -713,20 +711,11 @@ function renderSwitchable(vnode: any, context: Record<string, any>, parentState:
  * Internal helper: render a component def to a VNode (not HTML string).
  */
 function renderToStringInternal(componentDef: any, state: any, context: Record<string, any>, uid: string): any {
-  const resolvedState = withResources(componentDef, state !== undefined ? state : componentDef.initialState)
-
-  const componentContext = componentDef.context || {}
-  const mergedContext: Record<string, any> = {...context}
-  for (const key of Object.keys(componentContext)) {
-    const contextFn = componentContext[key]
-    if (typeof contextFn === 'function' && resolvedState != null) {
-      try {
-        mergedContext[key] = contextFn(resolvedState)
-      } catch (_) {}
-    }
-  }
+  const own = state !== undefined ? state : componentDef.initialState
+  const resolvedState = withResources(componentDef, own, contextOf(componentDef, own, context))
+  const mergedContext = contextOf(componentDef, resolvedState, context)
 
-  collectHead(componentDef, resolvedState)
+  collectHead(componentDef, resolvedState, mergedContext)
   let vnode: any
   try {
     vnode = componentDef({

package/src/extra/testing.ts

@@ -5,6 +5,7 @@ import {enrichEventStream} from '../cycle/dom/enrichEventStream';
 import eventBusDriver from './eventDriver';
 import logDriver from './logDriver';
 import {ownedCopy} from './owned';
+import {isAbort} from '../shared';
 import {renderToInnerHtml} from './ssr';
 import {_getDiagnosticsConfig, configureDiagnostics, getDiagnosticsMode, isDiagnosticsEnabled, onDiagnostic, report} from './diagnostics/index';
 import xs from './xstreamCompat';
@@ -496,9 +497,10 @@ export interface RenderResult {
   open: (sinkName: string, target?: FakeConnectionTarget) => Promise<void>;
   /**
    * PLAN-3 2-C: the server sends `data` (objects as JSON text) on the open connection(s): `message`
-   * fires (the data JSON-parsed when it parses). `{ event, connection? }`: an SSE named event.
+   * fires (the data JSON-parsed when it parses). `{ event, connection? }`: an SSE named event;
+   * `{ id }` (PLAN-13 S-1): its SSE event id (`meta`, `resume`).
    */
-  push: (sinkName: string, data: any, target?: FakeConnectionTarget | {event?: string; connection?: FakeConnectionTarget}) => Promise<void>;
+  push: (sinkName: string, data: any, target?: FakeConnectionTarget | {event?: string; id?: string | number; connection?: FakeConnectionTarget}) => Promise<void>;
   /**
    * PLAN-3 2-C: the connection(s) close without the app closing them (a connecting one fails to
    * open: `error` first): `close` fires with `{ code, reason, willReconnect }` and the fake
@@ -1273,17 +1275,27 @@ const sockKey = (sse: boolean, url: string, arg: any) => (sse ? 'e' + !!(arg &&
  * PLAN-3 2-C: the in-memory WebSocket / EventSource the fake's makeSocketDriver opens. The
  * harness drives it (t.open / t.push / t.drop); the driver's own close() is the app's close.
  */
+/** `url` without its query parameter `name` (PLAN-13 S-1: a resumed reconnect's id parameter) */
+const withoutParam = (url: string, name: string) =>
+  url.replace(new RegExp('([?&])' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '=[^&#]*&?'), '$1').replace(/[?&](#|$)/, '$1');
 const fakeSocketClass = (sse: boolean, made: (s: any) => void) => class {
   readyState = 0;
   sse = sse;
   byApp = false;
   k: string;
+  rn?: string;
   url: string;
   ls: Record<string, any[]> = {};
   onopen: any; onmessage: any; onerror: any; onclose: any;
   constructor(url: string, arg?: any) {
     this.url = String(url);
-    this.k = sockKey(sse, this.url, arg);
+    // PLAN-13 S-1: a resumed SSE reconnect's URL has the id parameter (added, or replacing the
+    // declared one): its key leaves that parameter out (`rn`: its name; made() compares the
+    // connections' URLs without it too)
+    const id = sse && arg?.lastEventId;
+    const m = id && new RegExp('[?&]([^?&=]+)=' + encodeURIComponent(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?=&|#|$)').exec(this.url);
+    if (m) this.rn = m[1];
+    this.k = sockKey(sse, m ? withoutParam(this.url, m[1]) : this.url, arg);
     made(this);
   }
   send() {}
@@ -1851,7 +1863,7 @@ export function renderComponent(
     const w: Sock = {src: null, in$: xs.create(), conns: new Map(), sockets: [], sent: [], declaring: null};
     const made = (s: any) => {
       w.sockets.push(s);
-      const all = [...w.conns.values()].flatMap(m => [...m.values()]).filter(c => c.k == s.k);
+      const all = [...w.conns.values()].flatMap(m => [...m.values()]).filter(c => (s.rn ? sockKey(true, withoutParam(c.url, s.rn), c.spec) : c.k) == s.k);
       if (w.declaring) {
         // a declaration opened it: the first new connection with its key (and, shared, the
         // other new shared ones)
@@ -1952,7 +1964,7 @@ export function renderComponent(
   for (const k in uses) for (const a in uses[k]?.model || {}) names.push(k + '.' + a);
   // G-275: the caller's initialState is owned (the dev statics freeze leaves it alone). G-289: a
   // copy is marked, not the caller's object
-  const init = initialState !== undefined ? ownedCopy(initialState) : componentDef.initialState;
+  let init = initialState !== undefined ? ownedCopy(initialState) : componentDef.initialState;
   // G-028: with no intent, model or initialState nothing would ever emit state, so the view
   // never renders. Leave intent/model unset so the component falls back to the same no-op
   // model run() uses, and renders.
@@ -2213,6 +2225,17 @@ export function renderComponent(
       },
     };
   };
+  // PLAN-13 F-2: a root that declares `route` starts from the test URL's route: its initialState's
+  // router.current() ran at module load, before the test's URL existed. The route entry's STATE
+  // reducer is applied to the initial state (its other sinks, a guard's redirect, run once when the
+  // router answers the declaration), so the first render and the statics see the page the test
+  // starts on: no render of '/' and no request for it
+  const re = rt && typeof componentDef.route == 'string' && model[componentDef.route]
+  const seed = typeof re == 'function' ? re : re && typeof re == 'object' && typeof re.STATE == 'function' && re.STATE
+  if (seed && init !== undefined) {
+    const v = seed(init, rt!.r.current(), noop, {state: init, previousState: init})
+    if (v !== undefined && !isAbort(v)) init = v
+  }
   let sources: any, sinks: any;
   try {
     // the root runs with the test intent, model, initial state and name, and the drivers above.
@@ -2848,11 +2871,13 @@ export function renderComponent(
   };
   const open = (name: string, target?: FakeConnectionTarget) => sockCall('open', name, target, [0], sockOpen);
   const push = (name: string, data: any, target?: any) => {
-    const o = target && typeof target == 'object' && !Array.isArray(target) && Object.keys(target).length && Object.keys(target).every(k => k == 'event' || k == 'connection') ? target : {connection: target};
+    const o = target && typeof target == 'object' && !Array.isArray(target) && Object.keys(target).length && Object.keys(target).every(k => k == 'event' || k == 'connection' || k == 'id') ? target : {connection: target};
     const raw = typeof data == 'string' || (data && typeof data == 'object' && (data instanceof ArrayBuffer || ArrayBuffer.isView(data) || (typeof Blob != 'undefined' && data instanceof Blob))) ? data : JSON.stringify(data);
     const ev = o.event;
     return sockCall('push', name, o.connection, [1], s => {
-      const m = {type: ev || 'message', data: raw};
+      // PLAN-13 S-1: `id` sets the event id; as in EventSource, lastEventId keeps the last one
+      if (s.sse && o.id != null) s.lastId = String(o.id);
+      const m: any = {type: ev || 'message', data: raw, ...(s.sse && {lastEventId: s.lastId ?? ''})};
       if (!ev || ev == 'message') sockFire(s, 'message', m);
       if (s.sse) (s.ls[ev || 'message'] || []).forEach((f: any) => { try { f(m); } catch (e) { console.error(e); } });
     });

package/src/extra/timers.ts

@@ -13,7 +13,8 @@ import {makeReplies} from './replies';
  *   falsy one stops, a changed spec restarts (an equal one keeps running).
  * - `every`: drift-free; tick n is due at start + n * every (each delay is computed from the
  *   start, not chained). A late tick (a throttled background tab) coalesces the missed ones:
- *   n jumps. Data `{ n, t }`: the tick number from 1, `t` = Date.now().
+ *   n jumps. A delay is at most `every`, so a frozen Date.now() (a test clock that fixes the time
+ *   while timers run) ticks once per interval. Data `{ n, t }`: the tick number from 1, `t` = Date.now().
  * - `after`: fires once, data `{ t }`. It doesn't fire again while the same spec stays declared.
  * - `frame`: every animation frame (requestAnimationFrame; setTimeout 16 ms without it), data
  *   `{ t, dt }`: Date.now() and the ms since the previous frame (0 on the first).
@@ -47,7 +48,9 @@ const start = (s: any, send: (type: string, data: any) => void, e: any): (() =>
       last = ts;
     } else if (every) {
       n = Math.max(n + 1, Math.floor((t - t0) / every));
-      later(t0 + (n + 1) * every - t);
+      // never more than one interval: under a frozen Date.now() (Playwright's setFixedTime: Date is
+      // fixed, timers run) the drift-free delay grew by one interval per tick
+      later(Math.min(every, t0 + (n + 1) * every - t));
       send(s.action, {n, t});
     } else {
       e.d = 1;

package/src/index.d.ts

@@ -77,8 +77,11 @@ export type StateProp = string | Lense<any, any>
  */
 export type ElementProps<PROPS> =
   0 extends (1 & PROPS) ? PROPS
-  : 'state' extends keyof PROPS ? WithoutViewOnlyProps<PROPS> & { state?: StateProp; resetState?: boolean }
-  : PROPS
+  // PLAN-13 F-3: Switchable's own `state` (a per-page map too) is kept as it declares it
+  : PROPS extends { of: Record<string, any>; current: string } ? PROPS
+  : WithStateProp<PROPS>
+
+type WithStateProp<PROPS> = 'state' extends keyof PROPS ? WithoutViewOnlyProps<PROPS> & { state?: StateProp; resetState?: boolean } : PROPS
 
 /** PROPS without `state`, `context`, `slots` and `uid` (keeps optionality and index signatures, unlike Omit). */
 type WithoutViewOnlyProps<PROPS> = {
@@ -1568,10 +1571,12 @@ export type Component<
    * actions on this instance; send with `{ to: 'room', json }` from a model entry (a connection
    * the same action opens or changes is declared first). Dispose closes them.
    */
-  connections?: (state: STATE & CALCULATED) => Connections;
+  connections?: (state: STATE & CALCULATED, context: CONTEXT) => Connections;
   /**
    * PLAN-3: declarative reads (`makeFetchDriver()`). Each entry derives a
-   * request from state; falsy means idle:
+   * request from state (and, PLAN-13 F-1, the context as its second argument, as every
+   * declaration static: `(state, { route }) => '/api/items/' + route.params.id`; re-run when the
+   * context changes); falsy means idle:
    * `Quote.resources = { quote: (state) => state.id && '/api/quotes/' + state.id }`.
    * `state.quote` is a `Resource`: `{ status: 'idle' | 'loading' | 'success' | 'error', data,
    * error, refreshing }`, written by the built-in RESOURCE action (idle until the first request).
@@ -1581,7 +1586,7 @@ export type Component<
    * `data`, `error` and `status` and sets `refreshing: true` (D78). `ok` / `error` on the
    * request also dispatch those actions after the write.
    */
-  resources?: { [name: string]: (state: STATE & CALCULATED) => ResourceRequest | false | null | undefined | '' | 0 };
+  resources?: { [name: string]: (state: STATE & CALCULATED, context: CONTEXT) => ResourceRequest | false | null | undefined | '' | 0 };
   /**
    * The router's reply action (`makeRouter()`): `App.route = 'ROUTE'`. The driver sends this
    * instance ROUTE with the `Route` (`{ name, params, query, hash, path }`) once declared and on
@@ -1603,7 +1608,7 @@ export type Component<
    * `renderToString(App, { head: list })` for SSR (`renderHead(list)`). Like every declaration
    * static, it is sent with or without a model; a root needs `initialState` (SYG132).
    */
-  head?: (state: STATE & CALCULATED) => HeadValue | false | null | undefined;
+  head?: (state: STATE & CALCULATED, context: CONTEXT) => HeadValue | false | null | undefined;
   /**
    * PLAN-4 GS-1: behaviors this component uses, each under its state key:
    * `TaskList.uses = { pager: pager({ pageSize: 10, next: Newer, prev: Older }) }` gives
@@ -1620,7 +1625,7 @@ export type Component<
    * fires once (`{ t }`), `frame` runs every animation frame (`{ t, dt }`). A hidden Switchable
    * page's timers stop unless `background: true`; dispose stops them; nothing runs during SSR.
    */
-  timers?: (state: STATE & CALCULATED) => Timers<ActionNameOf<ACTIONS>>;
+  timers?: (state: STATE & CALCULATED, context: CONTEXT) => Timers<ActionNameOf<ACTIONS>>;
   /**
    * PLAN-5 B-3: browser sources derived from state, run by `makeBrowserDriver()` (registered:
    * `run(App, { BROWSER: makeBrowserDriver() })`; renderComponent provides a fake, `t.browser`)
@@ -1630,7 +1635,7 @@ export type Component<
    * restarts. A hidden Switchable page's sources stop unless `background: true`; dispose stops
    * them; nothing runs during SSR.
    */
-  browser?: (state: STATE & CALCULATED) => BrowserSources<ActionNameOf<ACTIONS>>;
+  browser?: (state: STATE & CALCULATED, context: CONTEXT) => BrowserSources<ActionNameOf<ACTIONS>>;
   /**
    * PLAN-4 GS-5: save this root component's state and restore it at startup:
    * `TodoApp.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'] })`. `pick` / `omit`
@@ -1753,8 +1758,8 @@ export type VirtualCollectionProps<PROPS = any, STATE = any> = {
 /** Where `scrollToIndex` / `scrollToId` put the row: 'auto' (default) scrolls only when it isn't in view */
 export type ScrollToAlign = 'auto' | 'start' | 'center' | 'end'
 
-export type SwitchableProps<PROPS = any> = {
-  of: Record<string, AnyComponent>;
+export type SwitchableProps<PROPS = any, OF extends Record<string, AnyComponent> = Record<string, AnyComponent>> = {
+  of: OF;
   current: string;
   /**
    * The current page's instance key. When it changes, the current page is disposed and created
@@ -1762,7 +1767,14 @@ export type SwitchableProps<PROPS = any> = {
    * show. Switching `current` alone keeps pages alive. Router recipe: `instance={state.route.path}`
    */
   instance?: string | number;
-  state?: string | Lense;
+  /**
+   * The pages' state: a key or path (`'pages'`), a lens, or (PLAN-13 F-3) a map from page names to
+   * those (`{ projects: 'pages.projects', settings: byId('teams', state.teamId) }`): each listed
+   * page binds its own target with a tag child's lifetime rules (another key or id makes that page
+   * again, a deleted target disposes it), and the pages not listed share the owner's state. A key
+   * that names no page is SYG429
+   */
+  state?: string | Lense | { [PAGE in keyof NoInfer<OF>]?: string | Lense };
 } & Omit<PROPS, 'of' | 'state' | 'current' | 'instance'>
 
 export type PortalProps = {
@@ -2261,7 +2273,7 @@ export function Collection<PROPS extends { [prop: string]: any }, STATE = any>(p
  *   <VirtualCollection of={Row} from="rows" className="rows" estimateSize={32} />
  */
 export function VirtualCollection<PROPS extends { [prop: string]: any }, STATE = any>(props: VirtualCollectionProps<PROPS, STATE>): JSX.Element
-export function Switchable<PROPS extends { [prop: string]: any }>(props: SwitchableProps<PROPS>): JSX.Element
+export function Switchable<PROPS extends { [prop: string]: any }, OF extends Record<string, AnyComponent> = Record<string, AnyComponent>>(props: SwitchableProps<PROPS, OF>): JSX.Element
 export function Portal(props: PortalProps): JSX.Element
 export function Transition(props: TransitionProps): JSX.Element
 export function Suspense(props: SuspenseProps): JSX.Element
@@ -2322,6 +2334,48 @@ export type ReplyRequest = {
   catch?: never;
 }
 
+declare const replySenderBrand: unique symbol
+/**
+ * The component instance that sent a request to a driver (opaque). `senderOf(request)` reads it;
+ * pass it to `reply()` to answer that instance with one of its actions.
+ */
+export type ReplySender = { readonly [replySenderBrand]: true }
+
+/** What makeReplies() returns: the source part that marks the driver, and the way to answer */
+export type ReplyChannel = {
+  /**
+   * Spread into the driver's source (`return { ...replies, select }`): the core then stamps each
+   * request a component sends with its sender and delivers `reply()`s as that instance's actions.
+   */
+  replies: { readonly __sygnalReplies: true; replies(sender: ReplySender): Stream<{ type: string; data: any }> };
+  /** Dispatch `type` with `data` on the sender (dropped when it is gone). Call it as often as needed */
+  reply(sender: ReplySender, type: string, data?: any): void;
+  /** Whether the sender is still mounted (a reply would reach it) */
+  listening(sender: ReplySender): boolean;
+}
+
+/**
+ * PLAN-13 D-1: reply actions for a driver you write (the protocol makeFetchDriver,
+ * driverFromAsync and the socket driver use). `onStop(sender)` runs when a sender is disposed:
+ * abort what it still has in flight.
+ *
+ *   const { replies, reply } = makeReplies((sender) => inflight.get(sender)?.abort())
+ *   sink$.addListener({ next: (req) => {
+ *     const sender = senderOf(req)
+ *     if (sender === undefined) return                    // not sent by a component
+ *     run(req, (f) => req.progress && reply(sender, req.progress, f))
+ *       .then((v) => req.ok && reply(sender, req.ok, v), (error) => req.error && reply(sender, req.error, { error, request: req }))
+ *   } })
+ *   return { ...replies }
+ *
+ * A name with no model entry on the sender is SYG112 in the dev entry (ok / error / progress
+ * statically). Guide: https://sygnal.js.org/guide/custom-drivers/
+ */
+export function makeReplies(onStop?: (sender: ReplySender) => void): ReplyChannel
+
+/** The component instance that sent `request` to a driver with reply actions, or undefined (not sent by a component) */
+export function senderOf(request: object): ReplySender | undefined
+
 /**
  * A request to a driverFromAsync() sink: your own fields (`value`, the args, ...) plus the
  * reply-action keys `ok` / `error`. Type the driver's sink with it: `{ QUOTE: { source:
@@ -2797,6 +2851,15 @@ export type SocketActions = {
    * hidden page's connections close, and open again as new ones when it is shown)
    */
   background?: boolean;
+  /**
+   * PLAN-13 S-1: a connection that stays silent this long (ms) is taken as dead (a half-open
+   * socket behind a proxy): it is closed as a drop, `close` gets `{ stale: true, willReconnect }`,
+   * and the reconnect policy applies. Every event counts; over fetch (an `sse` with `headers`)
+   * any bytes do, heartbeat comments (`: ping`) included, while the native EventSource needs a
+   * real event (a `message`, or a named event listed in `events`). Set it above the server's
+   * heartbeat interval
+   */
+  staleAfterMs?: number;
   /** Not allowed: a `then` key makes the value a thenable (SYG610). Use `message` / `open` */
   then?: never;
   catch?: never;
@@ -2823,6 +2886,29 @@ export type SseConnection = SocketActions & {
   headers?: Record<string, string>;
   /** Named events → actions: `{ 'price-update': 'PRICE' }` (data JSON-parsed when it parses) */
   events?: Record<string, string>;
+  /**
+   * PLAN-13 S-1: the `message` and `events` actions get `SseEvent` (`{ data, id, event }`: the
+   * event id and type) instead of the data alone
+   */
+  meta?: boolean;
+  /**
+   * PLAN-13 S-1: resume after a reconnect the driver makes (EventSource gave up: a proxy 502, a
+   * non-2xx on the `headers` path) from the last event id. Over fetch (`headers`) it is sent as
+   * `Last-Event-ID`; the native EventSource can't send it, so it goes on the URL:
+   * `?lastEventId=<id>` (`true`) or `?<name>=<id>` (a parameter name). EventSource's own retries
+   * send `Last-Event-ID` anyway
+   */
+  resume?: true | string;
+}
+
+/** PLAN-13 S-1: an SSE event as a `meta: true` connection's actions get it */
+export type SseEvent<DATA = any> = {
+  /** The data, JSON-parsed when it parses */
+  data: DATA;
+  /** The event's `id:` (the last one sent when this event has none; '' when there was none) */
+  id: string;
+  /** The event type: 'message', or the named event's name */
+  event: string;
 }
 
 /**
@@ -2848,7 +2934,7 @@ export type SocketRequest =
 /** Data of a connection's `open` action */
 export type SocketOpen = { reconnected: boolean }
 /** Data of a connection's `close` action (SSE: no code / reason) */
-export type SocketClose = { code?: number; reason?: string; willReconnect: boolean }
+export type SocketClose = { code?: number; reason?: string; willReconnect: boolean; /** PLAN-13 S-1: closed by staleAfterMs (nothing arrived) */ stale?: true }
 /** Data of a connection's `error` action: the error Event (or the constructor's exception) */
 export type SocketError = { error: any }
 
@@ -3670,9 +3756,10 @@ export interface RenderResult<STATE = any> {
   open: (sinkName: string, target?: FakeConnectionTarget) => Promise<void>;
   /**
    * The server sends `data` (objects as JSON text) on open connection(s): `message` fires with
-   * the data, JSON-parsed when it parses. `{ event, connection? }` sends an SSE named event.
+   * the data, JSON-parsed when it parses. `{ event, connection? }` sends an SSE named event;
+   * `{ id }` gives an SSE event its id (what `meta: true` reports and `resume` resumes from).
    */
-  push: (sinkName: string, data: any, target?: FakeConnectionTarget | { event?: string; connection?: FakeConnectionTarget }) => Promise<void>;
+  push: (sinkName: string, data: any, target?: FakeConnectionTarget | { event?: string; id?: string | number; connection?: FakeConnectionTarget }) => Promise<void>;
   /**
    * Connection(s) close without the app closing them: `close` fires with `{ code, reason,
    * willReconnect }` (default `{ code: 1006, reason: '' }`; a connecting one fails to open: `error`

package/src/index.ts

@@ -12,6 +12,8 @@ export { Suspense } from "./suspense"
 export { Slot } from "./slot"
 export { lazy } from "./lazy"
 export { driverFromAsync } from "./extra/driverFactories"
+// PLAN-13 D-1: the reply-action protocol, for drivers written by hand
+export { makeReplies, senderOf } from './extra/replies'
 export { makeFetchDriver } from "./extra/fetchDriver"
 export { queryCache } from "./extra/queryCache"
 export { makeSocketDriver } from "./extra/socketDriver"