sygnal 5.4.0 → 6.1.0

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

@@ -0,0 +1,107 @@
+import {post, sse, json, partsOf, toolName} from './shared';
+import type {HttpOptions} from './shared';
+import {outputJsonSchema} from '../chat/output';
+
+/*
+ * PLAN-6 L-2: uiMessageStream(url, { headers?, fetch?, body?, dangerouslyAllowBrowser? }), a chat
+ * transport for an AI SDK server (the production default, D243): a route that answers with
+ * `result.toUIMessageStreamResponse()` / `createUIMessageStreamResponse()` (AI SDK 7's UI message
+ * stream protocol v1: SSE, header `x-vercel-ai-ui-message-stream: v1`, `data: [DONE]` at the end).
+ *
+ * Request: the body DefaultChatTransport sends (`{ id, messages, trigger: 'submit-message',
+ * messageId }`; `messageId` when the request continues the last message, `continue: true`, G-628, so `convertToModelMessages(messages)` works on the server as is: the messages
+ * are UIMessages, D252; their ids as given, G-640: the chat behavior and driver give every message a
+ * stable one; `m<index>` only for a message written without one), plus what the server may use: `instructions`, `model`, `tools` (name ->
+ * { description, inputSchema }: client tools the server can declare without `execute`) and
+ * `output` (`{ schema }`); `body` merged in.
+ *
+ * Response: a version other than v1 in the header fails the request with a clear Error (a
+ * missing header is accepted: proxies strip headers). Chunks:
+ * - `start` -> start (the message id); text-delta / reasoning-delta -> text / reasoning;
+ * - `tool-input-available` -> a tool call, held until the step ends: a call the server answers
+ *   (tool-output-available / -error / -denied, tool-approval-request) is yielded `executed: true`
+ *   (the app doesn't run it; no `tool` reply), a call still open when the step or stream ends is
+ *   a client tool call (the `tool` reply); `tool-input-error` -> an executed call + tool-error;
+ * - `tool-approval-request` -> tool-approval (the part goes to `approval-requested`; the app
+ *   answers by setting the part to `approval-responded` and sending the messages again, as with
+ *   the AI SDK's addToolApprovalResponse); `tool-output-denied` -> tool-denied; the output of an
+ *   approved call (the next request: only `tool-output-available` comes back) is yielded as
+ *   that call (name and input from the request's messages) + its result, in the new message;
+ * - `data-*` parts -> data events (a transient one is skipped: it isn't part of the message);
+ *   `file`, `source-url`, `source-document` -> as is;
+ * - `finish` -> finish (finishReason); `abort` -> finish ('abort'); `error` -> a thrown Error;
+ * - everything else (text-start/end, tool-input-start/delta, start-step, message-metadata, ...)
+ *   is ignored.
+ */
+
+export interface UIMessageStreamOptions extends HttpOptions {}
+
+const VERSION = 'v1';
+const ONE = /^(start-step|finish-step|finish)$/;
+
+export function uiMessageStream(url: string, options: UIMessageStreamOptions = {}) {
+  return {
+    async *stream(req: any, signal: AbortSignal): AsyncGenerator<any, void, any> {
+      const o = req.output !== undefined ? outputJsonSchema(req.output) : undefined;
+      const messages = req.messages.map((m: any, i: number) => ({id: m.id ?? `m${i}`, role: m.role, parts: partsOf(m), ...(m.metadata !== undefined && {metadata: m.metadata})}));
+      const last = messages[messages.length - 1];
+      const res = await post(url, {
+        ...(req.instructions && {instructions: req.instructions}),
+        ...(req.model && {model: req.model}),
+        ...(req.tools && {tools: req.tools}),
+        ...(o && {output: o}),
+      }, req, signal, options, 'uiMessageStream', {
+        // the protocol fields: merged after `body`, which can't override them (G-654)
+        ...(req.chatId != null && {id: req.chatId}),
+        messages,
+        trigger: 'submit-message',
+        // G-628: a continued assistant message (DefaultChatTransport's messageId)
+        ...(req.continue === true && last?.role == 'assistant' && {messageId: last.id}),
+      });
+      const v = res.headers?.get?.('x-vercel-ai-ui-message-stream');
+      if (v && v != VERSION) {
+        res.body.cancel?.().catch?.(() => {});
+        throw Object.assign(new Error(`uiMessageStream: the server speaks UI message stream ${v}; this transport speaks ${VERSION} (AI SDK 7). Update sygnal, or pin the server's ai package to a version that sends ${VERSION}`), {version: v});
+      }
+      // client tool calls not yet answered by the server, in order
+      let open: any[] = [];
+      // the call `id` as an executed call: an open one, or one from the request's messages (the
+      // server runs an approved call on the next request and sends only its output); [] once yielded
+      const yielded = new Set<string>();
+      const take = (id: string) => {
+        if (yielded.has(id)) return [];
+        yielded.add(id);
+        const i = open.findIndex(c => c.id === id);
+        if (i >= 0) return [{...open.splice(i, 1)[0], executed: true}];
+        for (const m of req.messages) for (const p of partsOf(m)) {
+          const name = toolName(p);
+          if (name && p.toolCallId === id) return [{type: 'tool-call', id, name, input: p.input, executed: true}];
+        }
+        return [];
+      };
+      for await (const {data} of sse(res)) {
+        if (data == '[DONE]') break;
+        const c = json(data), t = c?.type;
+        if (typeof t != 'string') continue;
+        if (ONE.test(t)) { for (const o of open) yielded.add(o.id); yield* open; open = []; }
+        if (t == 'text-delta' || t == 'reasoning-delta') yield {type: t.slice(0, -6), delta: c.delta};
+        else if (t == 'start') { if (c.messageId != null) yield {type: 'start', id: c.messageId}; }
+        else if (t == 'tool-input-available') open.push({type: 'tool-call', id: c.toolCallId, name: c.toolName, input: c.input, ...(c.providerExecuted && {executed: true, providerExecuted: true})});
+        else if (t == 'tool-input-error') yield* [{type: 'tool-call', id: c.toolCallId, name: c.toolName, input: c.input, executed: true}, {type: 'tool-error', id: c.toolCallId, error: c.errorText}];
+        else if (t == 'tool-output-available') yield* [...take(c.toolCallId), {type: 'tool-result', id: c.toolCallId, output: c.output}];
+        else if (t == 'tool-output-error') yield* [...take(c.toolCallId), {type: 'tool-error', id: c.toolCallId, error: c.errorText}];
+        else if (t == 'tool-output-denied') yield* [...take(c.toolCallId), {type: 'tool-denied', id: c.toolCallId}];
+        else if (t == 'tool-approval-request') {
+          yield* take(c.toolCallId);
+          yield {type: 'tool-approval', id: c.toolCallId, approval: {id: c.approvalId, ...(c.reason && {requestReason: c.reason}), ...(c.approvalDescriptor !== undefined && {descriptor: c.approvalDescriptor}), ...(c.isAutomatic && {isAutomatic: true}), ...(c.signature && {signature: c.signature})}};
+        }
+        else if (t.startsWith('data-')) { if (!c.transient) yield {type: t, ...(c.id != null && {id: c.id}), data: c.data}; }
+        else if (t == 'file' || t == 'source-url' || t == 'source-document') { const {providerMetadata, ...part} = c; yield part; }
+        else if (t == 'finish') yield {type: 'finish', ...(c.finishReason && {reason: c.finishReason})};
+        else if (t == 'abort') yield {type: 'finish', reason: 'abort'};
+        else if (t == 'error') throw new Error('uiMessageStream: ' + (c.errorText ?? 'the server failed'));
+      }
+      yield* open;
+    },
+  };
+}

package/src/extra/ai/webmcp.ts

@@ -0,0 +1,260 @@
+/*
+ * PLAN-6 A-2 (D241: experimental, outside semver until WebMCP's origin trial ends):
+ * `experimentalExposeWebMcp(app, { exposedTo?, confirm?, prefix?, modelContext? })` offers the
+ * A-1 tools of an app to the browser's agent through WebMCP (`document.modelContext`, Chrome 153
+ * with `--enable-features=WebMCP`, or a polyfill). Spike 0-S3 (`research/p6-spikes/0-S3.md`).
+ *
+ * - Feature detection: `modelContext` option ?? `document.modelContext` ?? `navigator.modelContext`
+ *   (the deprecated form); without one it does nothing and returns a `stop()` with
+ *   `available: false` (SYG674, info, dev).
+ * - One `registerTool(tool, { signal, exposedTo? })` per A-1 tool; a tool whose name, description,
+ *   schema or annotations changed (a `when`, the live Collection keys, the state summary) is
+ *   unregistered by aborting its signal and registered again. `registerTool` returns a Promise:
+ *   a rejection (a duplicate or invalid name) is SYG676, never thrown.
+ * - `execute` never throws and always resolves an object (strings and `undefined` differ between
+ *   Chrome and the polyfill, 0-S3 §3); A-1 validates the input.
+ * - Chrome's budgets, which neither Chrome 153 nor the polyfill enforce (G-601): name ≤ 30,
+ *   description ≤ 500, parameter description ≤ 150, result ≤ 1,500 characters of JSON. Over a
+ *   budget is SYG242 (dev, once per tool and part), then cut safely (a name keeps a hash of the
+ *   whole, so names stay unique; a result keeps `ok` / `error` and cuts `state`).
+ * - Annotations: A-1's `readOnlyHint` and `consequentialHint` (advisory: Chrome 153 drops it, so
+ *   `confirm` is the safeguard), and `untrustedContentHint` on the tools whose results carry a
+ *   projection with user strings: `untrusted: true` on the declaration, or (unless `untrusted:
+ *   false`) inferred from string values (A-1's `hasUserText`: not under `id` / `status` / `type` /
+ *   `kind` keys, not one of the declaration's input enum values; G-623), with SYG244 (dev).
+ * - Context (D250): A-1's read tool per declaration, plus a short summary of that declaration's
+ *   projection at the end of each of its tool descriptions, re-registered when it changes. An
+ *   untrusted projection gets no summary (D286, G-650): user text never goes into a description,
+ *   where an agent would read it as instructions, and a structure-only one misled small models.
+ * - Item tools whose key parameter lists ids without labels (`unlabel`, or no `label`) name the read
+ *   tool with the items' data: "Call board_read first to find the card's id." (G-650: small models
+ *   guessed ids otherwise).
+ * - Consequential calls: the `confirm` option, by default a native modal `<dialog>` appended to
+ *   `document.body` (outside the app's tree): labelled and described, the rest of the page inert
+ *   while it's open, "Deny" focused, Escape denies.
+ * Side-effect free: an app that doesn't import it pays 0 B.
+ */
+import {agentTools, hasUserText, labelsUntrusted, unlabel, lookUp, Confirm, ConfirmInfo, AgentTool, AgentResult} from './agent/index'
+import {report} from '../diagnostics/index'
+
+export interface ExposeWebMcpOptions {
+  /** origins the tools are exposed to (passed to `registerTool` where the API takes it) */
+  exposedTo?: string[]
+  /** consequential calls: `true` runs them, `false` declines, a function asks (default: a native `<dialog>`) */
+  confirm?: Confirm
+  /** prepended to every tool name (`shop_` → shop_todos_add) */
+  prefix?: string
+  /** the WebMCP context (default `document.modelContext ?? navigator.modelContext`) */
+  modelContext?: any
+}
+export type WebMcpHandle = (() => void) & {readonly available: boolean}
+
+const NAME = 30, DESC = 500, PARAM = 150, OUT = 1500, SUMMARY = 300
+
+const g: any = globalThis
+
+/** cut to n characters with an ellipsis, never inside a surrogate pair */
+const cut = (s: string, n: number) => {
+  if (s.length <= n) return s
+  let i = n - 1
+  if (/[\ud800-\udbff]/.test(s[i - 1] || '')) i--
+  return s.slice(0, i) + '…'
+}
+const hash = (s: string) => {
+  let h = 5381
+  for (let i = 0; i < s.length; i++) h = (h * 33 ^ s.charCodeAt(i)) >>> 0
+  return (h % 1679616).toString(36).padStart(4, '0')
+}
+
+export function experimentalExposeWebMcp(app: any, options: ExposeWebMcpOptions = {}): WebMcpHandle {
+  const mc = options.modelContext ?? g.document?.modelContext ?? g.navigator?.modelContext
+  const said = new Set<string>()
+  const dev = (code: string, key: string, message: string, severity: 'warn' | 'info' = 'warn') => {
+    if (said.has(code + key)) return
+    said.add(code + key)
+    try { report(code, {component: 'experimentalExposeWebMcp', message, severity}) } catch (e) { queueMicrotask(() => { throw e }) }
+  }
+  if (!mc || typeof mc.registerTool != 'function') {
+    dev('SYG674', '', 'no WebMCP here (document.modelContext is undefined): the agent tools are not exposed', 'info')
+    return Object.assign(() => {}, {available: false})
+  }
+
+  let closeDialog: (() => void) | undefined
+  const confirm: Confirm = options.confirm ?? (info => dialog(info, f => { closeDialog = f }))
+  const layer: any = agentTools(app, {confirm})
+  const prefix = options.prefix || ''
+  const reg = new Map<string, {sig: string; ac: AbortController}>()
+  let stopped = false
+
+  /** the WebMCP name of an A-1 tool: prefixed, legal characters, ≤ 30 (a hash keeps it unique) */
+  const nameOf = (n: string) => {
+    const full = (prefix + n).replace(/[^\w.-]/g, '_')
+    if (full.length <= NAME) return full
+    dev('SYG242', full + 'n', `the tool name '${full}' is longer than ${NAME} characters; it is offered as '${full.slice(0, NAME - 5)}_${hash(full)}'`)
+    return full.slice(0, NAME - 5) + '_' + hash(full)
+  }
+  /** parameter descriptions ≤ 150, in a copy of the schema */
+  const params = (s: any, tool: string, path: string): any => {
+    if (Array.isArray(s)) return s.map(x => params(x, tool, path))
+    if (!s || typeof s != 'object') return s
+    const o: any = {...s}
+    if (typeof s.description == 'string' && s.description.length > PARAM) {
+      dev('SYG242', tool + path, `the description of ${tool}'s parameter ${path || '(the input)'} is longer than ${PARAM} characters; it is cut`)
+      o.description = cut(s.description, PARAM)
+    }
+    for (const k of ['properties', '$defs', 'definitions', 'patternProperties']) if (s[k] && typeof s[k] == 'object') {
+      o[k] = {}
+      for (const p in s[k]) o[k][p] = params(s[k][p], tool, path ? path + '.' + p : p)
+    }
+    for (const k of ['items', 'prefixItems', 'anyOf', 'allOf', 'oneOf', 'additionalProperties', 'not']) if (s[k] && typeof s[k] == 'object') o[k] = params(s[k], tool, path)
+    return o
+  }
+  /** a result within 1,500 characters of JSON: `state` and long fields are cut first */
+  const fit = (r: any, tool: string): any => {
+    if (!r || typeof r != 'object') r = {ok: false, error: 'no result'}
+    let s = JSON.stringify(r)
+    if (s.length <= OUT) return r
+    dev('SYG242', tool + 'out', `a result of ${tool} is ${s.length} characters of JSON, over the budget of ${OUT}; its state is cut (make the agent.read projection smaller)`)
+    const {state, issues, keys, ...rest} = r
+    const o: any = {...rest, truncated: true}
+    if (typeof o.error == 'string') o.error = cut(o.error, 400)
+    if (issues) o.issues = issues.slice(0, 3)
+    for (let room = OUT; room > 20; room = room / 2 | 0) {
+      if (state !== undefined) o.state = cut(JSON.stringify(state), room)
+      if (JSON.stringify(o).length <= OUT) return o
+    }
+    delete o.state
+    delete o.issues
+    return o
+  }
+
+  function sync(tools: AgentTool[], context: Record<string, any>) {
+    if (stopped) return
+    // per A-1 tool: its declaration's summary and whether its results carry user strings
+    const summary = new Map<string, string>(), untrusted = new Set<string>()
+    let anyUntrusted = false
+    const groups = layer.groups()
+    for (const gr of groups) if (gr.read) {
+      const v = context[gr.name]
+      let u = gr.untrusted
+      if (u === undefined && hasUserText(v, gr.enums)) {
+        u = true
+        dev('SYG244', gr.name, `agent '${gr.name}': read returns strings, so its WebMCP tools get untrustedContentHint; declare untrusted: true (user-entered text) or untrusted: false (only the app's own text)`)
+      }
+      // D286 (G-622): descriptions are read as instructions and untrustedContentHint covers only
+      // results, so an untrusted projection gets no summary; the read tool returns the contents
+      // with the hint. G-650: the structure-only summary D286 had at first ("5 items (ids 1, 2, …)")
+      // read as the read tool's output to small models ("it has no titles"), which then guessed ids
+      const json = v === undefined || u ? '' : JSON.stringify(v)
+      for (const t of gr.tools) {
+        if (u) untrusted.add(t)
+        if (json) summary.set(t, '\n\nCurrent state: ' + cut(json, SUMMARY))
+      }
+      anyUntrusted ||= !!u
+    }
+    // a declaration with no read: its results carry an ancestor's projection
+    if (anyUntrusted) for (const gr of groups) if (!gr.read) for (const t of gr.tools) untrusted.add(t)
+    // G-644: user-entered labels leave the key parameter even when no projection is untrusted
+    const bare = new Set<string>(untrusted)
+    for (const gr of groups) if (labelsUntrusted(gr)) for (const t of gr.tools) bare.add(t)
+    // G-650: an item tool whose ids come without labels says which read tool to call first
+    const reader = new Map<string, {g: any; read: string}>()
+    for (const gr of groups) if (gr.reader) for (const t of gr.tools) if (!gr.labels || bare.has(t)) reader.set(t, {g: gr, read: nameOf(gr.reader)})
+
+    const want = new Map<string, any>()
+    for (const t of tools) {
+      const name = nameOf(t.name)
+      const look = reader.get(t.name), room = DESC - (look ? lookUp('', look.g, look.read).length + 2 : 0)
+      let d = t.description || t.name.replace(/_/g, ' ')
+      if (d.length > room) {
+        dev('SYG242', name + 'd', `the description of ${name} is longer than ${room} characters; it is cut`)
+        d = cut(d, room)
+      }
+      if (look) d = lookUp(d, look.g, look.read)
+      const sum = summary.get(t.name)
+      if (sum && DESC - d.length > 60) d += cut(sum, DESC - d.length)
+      const annotations = {...t.annotations, ...(untrusted.has(t.name) && {untrustedContentHint: true})}
+      const a1 = t.name
+      want.set(name, {
+        name, description: d, inputSchema: params(bare.has(t.name) ? unlabel(t.inputSchema, look ? `${look.read} has their contents` : groups.some((g: any) => g.read) ? 'the read tool has their contents' : 'their labels are user text, not shown') : t.inputSchema, name, ''),
+        ...(Object.keys(annotations).length && {annotations}),
+        // never throws, always an object (0-S3 §5)
+        execute: async (input: any) => {
+          let r: AgentResult
+          try { r = await layer.call(a1, typeof input == 'string' ? JSON.parse(input) : input ?? {}) } catch (e: any) { r = {ok: false, error: String(e?.message ?? e)} }
+          return fit(r, name)
+        },
+      })
+    }
+    for (const [name, r] of reg) {
+      const w = want.get(name)
+      if (!w || sig(w) !== r.sig) { r.ac.abort(); reg.delete(name) }
+    }
+    for (const [name, tool] of want) {
+      if (reg.has(name)) continue
+      const ac = new AbortController()
+      reg.set(name, {sig: sig(tool), ac})
+      const o: any = {signal: ac.signal}
+      if (options.exposedTo) o.exposedTo = options.exposedTo
+      const fail = (e: any) => dev('SYG676', name + sig(tool), `registerTool('${name}') was rejected: ${e?.name ? e.name + ': ' : ''}${e?.message ?? e}`)
+      try { Promise.resolve(mc.registerTool(tool, o)).catch(e => { if (!ac.signal.aborted) fail(e) }) } catch (e) { fail(e) }
+    }
+  }
+  const sig = (t: any) => JSON.stringify([t.description, t.inputSchema, t.annotations])
+
+  sync(layer.list(), layer.context())
+  const unsub = layer.subscribe((c: any) => sync(c.tools, c.context))
+
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    unsub()
+    layer.stop()
+    for (const r of reg.values()) r.ac.abort()
+    reg.clear()
+    closeDialog?.()
+  }
+  return Object.assign(stop, {available: true})
+}
+
+let n = 0
+/** the default confirmation: a native modal dialog outside the app's tree (Escape and "Deny" decline) */
+function dialog(info: ConfirmInfo, setClose: (f: () => void) => void): Promise<boolean> {
+  const doc = g.document
+  if (!doc?.createElement) return Promise.resolve(false)
+  return new Promise(resolve => {
+    const id = 'sygnal-webmcp-confirm-' + ++n, el = (tag: string, text?: string) => { const e = doc.createElement(tag); if (text) e.textContent = text; return e }
+    const dlg = el('dialog'), h = el('h2', 'Allow the AI agent to do this?'), p = el('p', info.description + (info.label ? ` (${info.label})` : '')), row = el('div')
+    const deny = el('button', 'Deny'), allow = el('button', 'Allow'), back = doc.activeElement
+    h.id = id + '-t'
+    p.id = id + '-d'
+    dlg.setAttribute('aria-labelledby', h.id)
+    dlg.setAttribute('aria-describedby', p.id)
+    dlg.setAttribute('data-sygnal-webmcp', '')
+    deny.type = allow.type = 'button'
+    deny.autofocus = true
+    dlg.append(h, p)
+    if (info.input !== undefined) dlg.append(el('pre', cut(JSON.stringify(info.input), 300)))
+    row.append(deny, allow)
+    dlg.append(row)
+    let open = true
+    const done = (v: boolean) => {
+      if (!open) return
+      open = false
+      try { dlg.close() } catch (_) {}
+      dlg.remove()
+      if (back?.isConnected && back.focus) try { back.focus() } catch (_) {}
+      resolve(v)
+    }
+    setClose(() => done(false))
+    deny.onclick = () => done(false)
+    allow.onclick = () => done(true)
+    // Escape: the modal dialog's cancel (and a keydown where showModal is missing)
+    dlg.addEventListener('cancel', (e: Event) => { e.preventDefault(); done(false) })
+    dlg.addEventListener('close', () => done(false))
+    dlg.addEventListener('keydown', (e: KeyboardEvent) => { if (e.key == 'Escape') { e.preventDefault(); done(false) } })
+    doc.body.append(dlg)
+    try { dlg.showModal() } catch (_) { dlg.setAttribute('open', '') }
+    deny.focus()
+  })
+}

package/src/extra/backoff.ts

@@ -0,0 +1,9 @@
+/*
+ * PLAN-3: the retry delay shared by makeSocketDriver's `reconnect` and makeFetchDriver's `retry`.
+ * Delay of retry n (from 0): `min(maxDelayMs, delayMs * 2^n)`, varied by ±`jitter` (a fraction;
+ * `false` = none). Defaults `{ delayMs: 500, maxDelayMs: 10000, jitter: 0.2 }`.
+ */
+export const backoff = (p: {delayMs?: number; maxDelayMs?: number; jitter?: number | boolean}, n: number) => {
+  const j = p.jitter === false ? 0 : p.jitter == null || p.jitter === true ? 0.2 : +p.jitter;
+  return Math.min(p.maxDelayMs ?? 10000, (p.delayMs ?? 500) * 2 ** n) * (1 + j * (2 * Math.random() - 1));
+};

package/src/extra/behaviors.ts

@@ -0,0 +1,169 @@
+/*
+ * PLAN-4 GS-1: reusable behaviors.
+ *
+ *   const pager = defineBehavior({ initialState, intent: (sources, options) => ..., model, calculated })
+ *   TaskList.uses = { pager: pager({ pageSize: 10, next: Newer, prev: Older }) }
+ *
+ * A behavior runs on state[key] (a lens). Its actions are '<key>.<ACTION>' (D109). Each value a
+ * factory returns carries its own `merge(component, key)`; the core only loops over `uses` and
+ * calls it (D114), so an app that never imports this module pays nothing.
+ *
+ * Merge rules (applied to the component instance, never to its statics):
+ * - initialState: state[key] = the behavior's initialState, with the options that name one of its
+ *   keys (pageSize) overriding it, plus its calculated fields. On a sub-component host (a
+ *   Collection item, a child with a `state` prop) the slice isn't written into initialState
+ *   (that would replace the parent's slice, SYG405): state[key] reads as that default until the
+ *   first write (the core's `_idle` defaults, as for resources).
+ * - calculated: fields of the slice, stored on it (state.pager.offset), recomputed after every
+ *   behavior reducer and after any host STATE reducer that changes state[key].
+ * - model: each entry gets the slice (STATE returns the new slice; ABORT and the slice itself
+ *   mean no change, GS-4), `next('ACTION')` names the behavior's own actions. A host entry for
+ *   the same action ('pager.NEXT') runs after the behavior's: a host STATE reducer gets the full
+ *   state with the behavior's update applied (its ABORT keeps that update), a host EFFECT runs
+ *   after the behavior's, and a host value sink (EVENTS, PARENT, a driver) replaces the
+ *   behavior's value for that sink.
+ * - intent: gets the host's sources (DOM is the host's isolated DOM source; CHILD, EVENTS and
+ *   drivers as they are) with STATE lensed to the slice, plus the options. A host intent action
+ *   with the same namespaced name overrides the behavior's trigger.
+ * - `instance._behaviorActions` maps each behavior-owned action to its key (t.actions, 2-C).
+ *   A host intent action of the same name makes it host-owned (removed from the map).
+ * - renderComponent marks the streams it adds for simulateAction (`__sygnalTestActions`); they
+ *   are merged with a behavior trigger of the same name instead of overriding it.
+ * - D197 (PLAN-5): every model handler gets `(slice, data, next, props, options, key)`: the
+ *   use's options and its key in `uses` (so a driver request can name a reply action
+ *   `key + '.LOADED'`); the intent gets `(sources, options, key)`.
+ * - D197: `HOST: (state, data, next, props, options, key) => state` in a model entry is a STATE
+ *   reducer on the host's whole state (sortable reorders the host's array); ABORT or the same
+ *   state is no change; the slice's calculated fields are recomputed when it changed. G-378:
+ *   with a STATE in the same entry, STATE runs first and HOST gets its result.
+ * - D197: `timers: (slice, options, key) => ({ name: spec })` declares timers (makeTimerDriver)
+ *   for the host: named '<key>.<name>', a spec's action / frame naming one of the behavior's
+ *   actions is namespaced as next() does. They join the host's own `timers` static through an
+ *   accessor on the component function (installed once; the host's own value is kept as is and
+ *   can still be assigned), which reads the host's current `uses`.
+ * - Limitations: a host intent must return an object (not one stream).
+ */
+import xs from './xstreamCompat'
+import {isAbort} from '../shared'
+// a model entry as { sink: fn }: a constant is sent as is, `true` sends the action's data, an
+// EFFECT constant does nothing (as the core treats them)
+const sinksOf = (e: any, S: string): any => {
+  const o: any = typeof e == 'function' ? {[S]: e} : {...e}
+  for (const s in o) {
+    const v = o[s]
+    if (typeof v != 'function') o[s] = s == 'EFFECT' ? () => {} : v === true || v === undefined ? (_: any, d: any) => d : () => v
+  }
+  return o
+}
+
+// two STATE reducers in turn: the second gets the first's state (the given one when it ABORTs);
+// an ABORT from the second keeps the first's
+const seq = (bf: any, hf: any) => (st: any, ...x: any[]) => {
+  const r = bf(st, ...x), q = hf(isAbort(r) ? st : r, ...x)
+  return isAbort(q) ? r : q
+}
+
+const calcOf = (calcs: any) => (r: any) => {
+  if (r && typeof r == 'object') for (const f in calcs) r = {...r, [f]: calcs[f](r)}
+  return r
+}
+
+// the hosts whose `timers` static is an accessor (D197); the accessor's getter: the host's own
+// timers plus each behavior's (from the host's current `uses`)
+const timed = new WeakSet<any>()
+const addTimers = (v: any): void => {
+  if (timed.has(v)) return
+  timed.add(v)
+  let own = v.timers
+  const all = (st: any) => {
+    const o: any = {}, f = own
+    if (typeof f == 'function') Object.assign(o, f(st))
+    else if (f && typeof f == 'object') for (const r in f) o[r] = f[r](st)
+    const u = v.uses
+    for (const k in u) {
+      const b = u[k], t = b?.timers?.(st?.[k] ?? b.state, b.options, k), rn = (a: any) => a in (b.model || {}) ? k + '.' + a : a
+      for (const n in t) {
+        const x = t[n]
+        o[k + '.' + n] = x && {...x, ...(x.action && {action: rn(x.action)}), ...(x.frame && {frame: rn(x.frame)})}
+      }
+    }
+    return o
+  }
+  Object.defineProperty(v, 'timers', {configurable: true, enumerable: true, get: () => all, set: (x: any) => { own = x }})
+}
+
+const mergeBehavior = (c: any, k: string, b: any): void => {
+  const S = c.stateSourceName, calcs = b.calculated, calc = calcOf(calcs), model = c.model = {...c.model}, slice = b.state
+  const owned = c._behaviorActions ||= {}, ns = (a: string) => k + '.' + a, opts = b.options
+  if (b.timers && c.view) addTimers(c.view)
+  if (c.isSubComponent && !c.isolatedState) c._idle = {...c._idle, [k]: slice}
+  else c.initialState = {...(typeof c.initialState == 'object' ? c.initialState : {}), [k]: slice}
+
+  // the slice's calculated fields stay fresh when a host reducer changes state[key]
+  const fresh = (f: any) => (st: any, ...x: any[]) => {
+    const r = f(st, ...x)
+    return r && typeof r == 'object' && st && r[k] !== st[k] ? {...r, [k]: calc(r[k])} : r
+  }
+  if (calcs) for (const a in model) {
+    const e = model[a]
+    if (typeof e == 'function') { if (!a.includes('|') || a.split('|')[1].trim() == S) model[a] = fresh(e) }
+    else if (e?.[S]) model[a] = {...e, [S]: fresh(e[S])}
+  }
+
+  for (const a in b.model) {
+    const e = sinksOf(b.model[a], S), m: any = {}, host = model[ns(a)]
+    for (const s in e) {
+      // HOST: a STATE reducer on the host's whole state (D197). G-378: with a STATE in the same
+      // entry, STATE runs first and HOST gets the state with its update (seq)
+      const whole = s == 'HOST', o = whole ? S : s
+      const f = (st: any, d: any, next: any, p: any) => {
+        const r = e[s](whole ? st : st?.[k], d, next && ((t: string, ...y: any[]) => next(t in b.model ? ns(t) : t, ...y)), p, opts, k)
+        return whole ? (isAbort(r) || r === st || !r || r[k] === st?.[k] ? r : {...r, [k]: calc(r[k])})
+          : s != S || isAbort(r) ? r : r === st[k] ? st : {...st, [k]: calc(r)}
+      }
+      m[o] = !m[o] ? f : whole ? seq(m[o], f) : seq(f, m[o])
+    }
+    if (host) {
+      const hs = sinksOf(host, S)
+      for (const s in hs) {
+        const bf = m[s], hf = hs[s]
+        m[s] = !bf ? hf
+          : s == S ? seq(bf, hf)
+          : s == 'EFFECT' ? (...x: any[]) => { bf(...x); hf(...x) }
+          : hf
+      }
+    }
+    model[ns(a)] = m
+    owned[ns(a)] = k
+  }
+
+  // one combined intent per instance: the behaviors' actions, then the host's own (which win)
+  if (!c._uses) {
+    const own = c.intent, list: any[] = c._uses = []
+    c.intent = (so: any) => {
+      const o: any = {}
+      for (const [k, b, slice] of list) {
+        const st = so[S], i = b.intent?.({...so, [S]: st?.select({get: (s: any) => s?.[k] ?? slice})}, b.options, k)
+        for (const a in i) o[k + '.' + a] = i[a], owned[k + '.' + a] = k
+      }
+      const h = own?.(so), test = h?.__sygnalTestActions || []
+      // renderComponent adds a stream for each static model action (simulateAction): merged in, not an override
+      for (const a in h) test.includes(a) && o[a] ? o[a] = xs.merge(o[a], h[a]) : (delete owned[a], o[a] = h[a])
+      return o
+    }
+  }
+  c._uses.push([k, b, slice])
+}
+
+/**
+ * defineBehavior({ initialState, intent?, model?, calculated?, timers? }) returns a factory; call
+ * it with the options for one use (`pager({ pageSize: 10, next: Newer })`) in a component's `uses`.
+ */
+export const defineBehavior = (def: any) => (options: any = {}): any => {
+  const init = {...def.initialState}, b: any = {...def, options}
+  for (const o in options) if (o in init) init[o] = options[o]
+  // the slice a host starts with: initialState, the options naming its keys, its calculated fields
+  b.state = calcOf(def.calculated)(init)
+  b.merge = (c: any, k: string) => mergeBehavior(c, k, b)
+  return b
+}

package/src/extra/browserSignals.ts

@@ -0,0 +1,23 @@
+/*
+ * Browser signals (PLAN-3 §1.6, H-6): window focus / the page becoming visible, and the network
+ * coming back online. makeFetchDriver's refetchOnFocus / refetchOnReconnect and refetchEvery use
+ * them; PLAN-4's browser sources reuse them. Safe without a DOM (SSR, Node): nothing fires.
+ */
+
+export type BrowserSignal = 'focus' | 'online';
+
+/** true while the document is hidden (a background tab); false without a DOM */
+export const isHidden = (): boolean => (globalThis as any).document?.visibilityState == 'hidden';
+
+/**
+ * Calls `fn('focus')` when the window gains focus or the document becomes visible, and
+ * `fn('online')` when the browser goes online. Returns the unsubscribe function.
+ */
+export const onBrowserSignals = (fn: (signal: BrowserSignal) => void): (() => void) => {
+  const w: any = (globalThis as any).window;
+  if (!w?.addEventListener) return () => {};
+  const focus = () => isHidden() || fn('focus'), online = () => fn('online');
+  const on: Array<[any, string, () => void]> = [[w, 'focus', focus], [w, 'online', online], [w.document, 'visibilitychange', focus]];
+  on.forEach(([t, e, f]) => t?.addEventListener(e, f));
+  return () => on.forEach(([t, e, f]) => t?.removeEventListener(e, f));
+};