sygnal 5.3.7 → 6.0.0

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

package/src/extra/browserSources.ts

@@ -0,0 +1,326 @@
+import {makeReplies} from './replies';
+import {defHooks} from '../core/registry';
+
+/*
+ * PLAN-5 B-3: browser sources, in the timers declaration shape (GS-7, S-8). A component declares
+ * what it watches as a function of its state; each entry's events come back as its own actions:
+ *
+ *   Card.browser = (state) => ({
+ *     seen:  !state.seen && { intersection: '.cover', action: 'SEEN' },
+ *     dark:  { media: '(prefers-color-scheme: dark)', action: 'DARK' },
+ *   })
+ *   run(App, { BROWSER: makeBrowserDriver() })
+ *
+ * - Declaration: `C.browser = (state) => ({ [name]: spec | falsy })` (or an object of such
+ *   functions), the spec's kind being the source key it has (the first of KINDS): `intersection` / `resize` (a selector in
+ *   the component's own DOM, or `true` for its root element), `media` (a query), `storage` (a key;
+ *   `area: 'session'`, `json: true`), `visibility: true`, `online: true`, `geolocation` (true or
+ *   PositionOptions). `action` names the action; `error` (geolocation, storage) the failure one.
+ * - Diffed per (instance, name), comparing specs structurally, as timers: a new name starts, a
+ *   removed or falsy one stops, a changed spec restarts. The core sends only `background: true`
+ *   entries while the instance is on a hidden Switchable page (they restart when it's shown);
+ *   dispose stops them, app dispose stops all; SSR runs no drivers.
+ * - Sources that have a current value (media, storage, visibility, online) send it when they
+ *   start; intersection / resize send what their observer reports (each element once at first).
+ * - Commands, sent on the driver's sink from a model entry (the method: a key the driver knows):
+ *   `{ copy: text, ok?, error? }` and `{ paste: true, ok, error? }` (the clipboard, data
+ *   `{ text }`), `{ setItem: key, value, area?, json? }` / `{ removeItem: key, area? }` (storage;
+ *   this page's `storage` declarations hear a change; an unchanged value is silent, G-384).
+ * - The core has no code for any of it (0 B): the driver's source is marked `__sygnalStatic:
+ *   'browser'` (statics.ts) and answers with reply actions (replies.ts). A component's DOM
+ *   (intersection, resize) reaches the driver through a definition hook registered by the first
+ *   driver made (renderComponent's fake too): it binds each declaring instance's DOM source at
+ *   its creation (G-383: a definition cached before the hook existed is made again, define.ts).
+ * - Unused sources cost nothing with makeBrowserDriverWith(intersectionSource, ...);
+ *   makeBrowserDriver() has them all.
+ * - Diagnostics (dev entry, through the `browserSource` hook): SYG663 an invalid spec or command,
+ *   SYG664 a kind the driver wasn't made with, SYG665 a failure with no `error` action, SYG668
+ *   an intersection / resize declaration with nothing to observe (no DOM source bound). A
+ *   component declaring `browser` with no driver is SYG643, as timers.
+ */
+
+const g: any = globalThis;
+const noop = () => {};
+const KINDS = ['intersection', 'resize', 'media', 'storage', 'visibility', 'online', 'geolocation'];
+const diag = (...a: any[]) => g.__SYGNAL_DIAGNOSTICS__?.browserSource?.(...a);
+
+/** What a declared source gets: the instance's DOM source, its action, its failure */
+export interface BrowserCtx {
+  dom: any;
+  send: (data: any) => void;
+  fail: (data: any) => void;
+  /** G-383: a DOM-backed source that has nothing to observe reports it (SYG668; dev entry) */
+  miss: (why: string) => void;
+  /** G-390: the driver's shared observers, by kind and options */
+  obs: Map<string, any>;
+}
+/** A browser source: the declaration kinds (`d`) and sink commands (`c`) it adds to the driver */
+export interface BrowserSource {
+  d?: Record<string, (spec: any, ctx: BrowserCtx) => (() => void) | void>;
+  c?: Record<string, (cmd: any, ok: (data: any) => void, fail: (data: any) => void) => void>;
+}
+
+// the driver names in use (the definition hook looks each up in a declaring instance's sources)
+const names = new Set<string>();
+let hooked: any;
+const hook = () => hooked ||= defHooks.push((src: any, view: any) => view.browser == null ? undefined : {
+  ...src,
+  intent: (so: any) => {
+    for (const n of names) if (n in so) so[n]?.__b?.(so.DOM);
+    return src.intent ? src.intent(so) : {};
+  },
+});
+
+/** `{ ...el.dataset }` and its place among the target's elements */
+const where = (els: any[], el: any) => ({index: els.indexOf(el), dataset: {...el.dataset}});
+
+/**
+ * G-390: one observer per driver for each kind and options (`key`), shared by every declaration
+ * of them: it maps each element to the declarations' handlers. A declaration that starts on an
+ * element already observed gets its last report (a microtask later), as its own observer's first
+ * one; the observer is disconnected when nothing is left to observe.
+ */
+const shared = (c: BrowserCtx, key: string, Obs: any, opts: any) => {
+  let r = c.obs.get(key);
+  if (!r) {
+    const h = new Map<any, Set<any>>(), last = new Map<any, any>();
+    const o = new Obs((es: any[]) => es.forEach(e => { last.set(e.target, e); h.get(e.target)?.forEach(f => f(e)); }), opts);
+    c.obs.set(key, r = {
+      add: (el: any, f: any) => {
+        let s = h.get(el);
+        if (!s) h.set(el, s = new Set()), o.observe(el);
+        else if (last.has(el)) Promise.resolve().then(() => s!.has(f) && f(last.get(el)));
+        s.add(f);
+      },
+      del: (el: any, f: any) => {
+        const s = h.get(el);
+        if (!s?.delete(f) || s.size) return;
+        h.delete(el); last.delete(el); o.unobserve(el);
+        if (!h.size) { o.disconnect(); c.obs.delete(key); }
+      },
+    });
+  }
+  return r;
+};
+// G-390: a DOM source's elements() stream per target, shared by its declarations (one query a patch)
+const found = new WeakMap<any, Record<string, any>>();
+const elementsOf = (dom: any, target: any) => {
+  let m = found.get(dom);
+  if (!m) found.set(dom, m = {});
+  const t = target === true ? '' : '' + target;
+  return m[t] ||= dom.select(t).elements();
+};
+
+/**
+ * Observe the elements `target` selects in the instance's DOM (`true`: its root element) with the
+ * driver's shared observer of `kind` (IntersectionObserver, ResizeObserver) and options: new ones
+ * are observed and gone ones let go after every patch. Nothing without a DOM source (SYG668) or
+ * the observer.
+ */
+const track = (c: BrowserCtx, kind: string, target: any, Obs: any, opts: any, data: (e: any) => any) => {
+  if (!c.dom) return c.miss('dom');
+  if (!Obs) return;
+  let els: any[] = [];
+  const o = shared(c, kind + JSON.stringify(opts), Obs, opts), f = (e: any) => c.send({...data(e), ...where(els, e.target)});
+  const $ = elementsOf(c.dom, target);
+  const l = {next: (now: any[]) => {
+    for (const e of now) els.includes(e) || o.add(e, f);
+    for (const e of els) now.includes(e) || o.del(e, f);
+    els = [...now];
+  }};
+  $.addListener(l);
+  return () => { $.removeListener(l); els.forEach(e => o.del(e, f)); };
+};
+
+/** Element visibility: `{ intersection: '.cover' | true, action, threshold?, rootMargin? }`, data `{ visible, ratio, index, dataset }` */
+export const intersectionSource: BrowserSource = {d: {
+  intersection: (s, c) => track(c, 'i', s.intersection, g.IntersectionObserver, {threshold: s.threshold, rootMargin: s.rootMargin},
+    (e) => ({visible: e.isIntersecting, ratio: e.intersectionRatio})),
+}};
+
+/** Element size: `{ resize: '.chart' | true, action }`, data `{ width, height, index, dataset }` (the content box) */
+export const resizeSource: BrowserSource = {d: {
+  resize: (s, c) => track(c, 'r', s.resize, g.ResizeObserver, undefined,
+    (e) => ({width: e.contentRect.width, height: e.contentRect.height})),
+}};
+
+/** A media query: `{ media: '(prefers-color-scheme: dark)', action }`, data `{ matches, media }` */
+export const mediaSource: BrowserSource = {d: {
+  media: (s, c) => {
+    const m = g.matchMedia?.(s.media);
+    if (!m) return;
+    const f = () => c.send({matches: m.matches, media: s.media});
+    f();
+    m.addEventListener('change', f);
+    return () => m.removeEventListener('change', f);
+  },
+}};
+
+const area = (s: any) => g[s.area == 'session' ? 'sessionStorage' : 'localStorage'];
+const failed = (e: any) => ({name: e?.name, message: e?.message});
+
+/**
+ * A storage key (read and observed, other tabs' writes included): `{ storage: 'theme', action,
+ * area?: 'session', json?: true, error? }`, data `{ key, value }` (null when absent; parsed with
+ * `json`). Commands `{ setItem: key, value, area?, json? }`, `{ removeItem: key, area? }`.
+ * For a component's state that should survive a reload, use persist() instead.
+ */
+// this page's storage declarations (every driver's): a write here reaches them directly
+const watching = new Set<(e: any) => void>();
+export const storageSource: BrowserSource = {
+  d: {storage: (s, c) => {
+    const key = s.storage;
+    const f = (e?: any) => {
+      try {
+        const a = area(s);
+        if (e && (e.storageArea != a || e.key != null && e.key != key)) return;
+        let v = a.getItem(key);
+        if (s.json && v != null) v = JSON.parse(v);
+        c.send({key, value: v});
+      } catch (x) { c.fail(failed(x)); }
+    };
+    f();
+    watching.add(f);
+    g.addEventListener?.('storage', f);
+    return () => { watching.delete(f); g.removeEventListener?.('storage', f); };
+  }},
+  c: (() => {
+    const write = (v: any, value: any, ok: any, fail: any) => {
+      try {
+        const a = area(v), key = v.setItem ?? v.removeItem, old = a.getItem(key);
+        value == null ? a.removeItem(key) : a.setItem(key, value);
+        // G-384: this page's declarations hear a change (the browser fires `storage` in the other
+        // tabs only), and only a change: a model that writes back what it read settles. Not
+        // dispatched on window, so other `storage` listeners see other tabs' writes only.
+        if (old !== (value ?? null)) [...watching].forEach(f => f({key, storageArea: a}));
+        ok({key});
+      } catch (x) { fail(failed(x)); }
+    };
+    return {
+      setItem: (v, ok, fail) => write(v, v.json ? JSON.stringify(v.value) : '' + v.value, ok, fail),
+      removeItem: (v, ok, fail) => write(v, null, ok, fail),
+    };
+  })(),
+};
+
+/** The document's visibility: `{ visibility: true, action }`, data `{ visible }` */
+export const visibilitySource: BrowserSource = {d: {
+  visibility: (_, c) => {
+    const d = g.document;
+    if (!d) return;
+    const f = () => c.send({visible: d.visibilityState != 'hidden'});
+    f();
+    d.addEventListener('visibilitychange', f);
+    return () => d.removeEventListener('visibilitychange', f);
+  },
+}};
+
+/** The network: `{ online: true, action }`, data `{ online }` */
+export const onlineSource: BrowserSource = {d: {
+  online: (_, c) => {
+    if (!g.navigator || !g.addEventListener) return;
+    const f = () => c.send({online: g.navigator.onLine});
+    f();
+    g.addEventListener('online', f);
+    g.addEventListener('offline', f);
+    return () => { g.removeEventListener('online', f); g.removeEventListener('offline', f); };
+  },
+}};
+
+/**
+ * The position (permission-gated): `{ geolocation: true | PositionOptions, action, error? }`,
+ * data `{ latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp }`;
+ * a failure (denied, unavailable, timeout) `{ code, message }` to `error`.
+ */
+export const geolocationSource: BrowserSource = {d: {
+  geolocation: (s, c) => {
+    const geo = g.navigator?.geolocation;
+    if (!geo) return c.fail({code: 2, message: 'Geolocation is not available'});
+    const id = geo.watchPosition((p: any) => {
+      const {latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed} = p.coords;
+      c.send({latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed, timestamp: p.timestamp});
+    }, (e: any) => c.fail({code: e.code, message: e.message}), s.geolocation === true ? undefined : s.geolocation);
+    return () => geo.clearWatch(id);
+  },
+}};
+
+/**
+ * The clipboard (permission-gated), as commands: `{ copy: text, ok?, error? }` and
+ * `{ paste: true, ok, error? }`, data `{ text }`; a failure `{ name, message }` to `error`.
+ */
+export const clipboardSource: BrowserSource = {c: {
+  copy: (v, ok, fail) => {
+    const text = '' + v.copy, cb = g.navigator?.clipboard;
+    cb ? cb.writeText(text).then(() => ok({text}), (e: any) => fail(failed(e))) : fail({name: 'NotSupportedError', message: 'Clipboard is not available'});
+  },
+  paste: (_, ok, fail) => {
+    const cb = g.navigator?.clipboard;
+    cb ? cb.readText().then((text: string) => ok({text}), (e: any) => fail(failed(e))) : fail({name: 'NotSupportedError', message: 'Clipboard is not available'});
+  },
+}};
+
+/**
+ * The driver over `sources` and `runners` (sender → { c: component name, on: { [name]: entry } },
+ * an entry being { k: the spec's JSON, s: the spec, x: stop }). renderComponent's fake passes its
+ * own sources and map.
+ */
+export const browserDriver = (sources: BrowserSource[], runners: Map<any, any>) => (sink$: any, name?: string) => {
+  const d: any = {}, cmd: any = {}, doms = new Map<any, any>(), obs = new Map<string, any>();
+  for (const s of sources) { Object.assign(d, s.d); Object.assign(cmd, s.c); }
+  const update = (id: any, decl: any, comp?: any) => {
+    let r = runners.get(id);
+    if (!r) runners.set(id, r = {c: comp, on: {}});
+    const on = r.on;
+    for (const n in on) if (on[n].k != JSON.stringify(decl?.[n])) on[n].x(), delete on[n];
+    for (const n in decl) {
+      const s = decl[n];
+      if (!s || on[n]) continue;
+      const e: any = on[n] = {k: JSON.stringify(s), s, x: noop};
+      const k = typeof s == 'object' && KINDS.find(k => k in s);
+      if (!k || !s.action || typeof s.action != 'string' || (k == 'intersection' || k == 'resize') && s[k] !== true && (typeof s[k] != 'string' || !s[k])) diag('SYG663', n, s, comp);
+      else if (!d[k]) diag('SYG664', n, s, comp, k);
+      else e.x = d[k](s, {
+        dom: doms.get(id),
+        send: (v: any) => reply(id, s.action, v),
+        fail: (v: any) => s.error ? reply(id, s.error, v) : diag('SYG665', n, s, comp, v),
+        miss: (why: string) => diag('SYG668', n, s, comp, why),
+        obs,
+      }) || noop;
+    }
+    if (!decl) runners.delete(id);
+  };
+  const stopAll = () => runners.forEach((_, id) => update(id, 0));
+  const {replies, reply} = makeReplies(id => { update(id, 0); doms.delete(id); });
+  hook();
+  if (name) names.add(name);
+  sink$.addListener({
+    next: (v: any) => {
+      if (!v || typeof v != 'object') return;
+      const id = v.__emitterId;
+      if ('browser' in v && id !== undefined) return update(id, v.browser, v.__emitterName);
+      // G-388: the method is any key the driver knows ({ ok, copy } too); G-389: a handler that
+      // throws (a value JSON can't encode, a clipboard without the method) fails like a rejection
+      const k = Object.keys(v), m = k.find(k => k in cmd) || k[0], f = cmd[m];
+      if (!f) return diag('SYG663', m, v, v.__emitterName, 0, Object.keys(cmd));
+      const fail = (x: any) => v.error ? reply(id, v.error, x) : diag('SYG665', m, v, v.__emitterName, x);
+      try { f(v, (x: any) => v.ok && reply(id, v.ok, x), fail); } catch (x) { fail(failed(x)); }
+    },
+    error: noop,
+    complete: stopAll,
+  });
+  // a declaring instance's own source (its DOM bound by the definition hook)
+  const src = (): any => {
+    const o: any = {...replies, __sygnalStatic: 'browser', replies: (id: any) => (o.i = id, replies.replies(id)), isolateSource: src, __b: (dom: any) => doms.set(o.i, dom)};
+    return o;
+  };
+  return {...src(), dispose: stopAll};
+};
+
+/**
+ * A driver for the components' `browser` declarations and the BROWSER sink commands, with only
+ * the given sources: `run(App, { BROWSER: makeBrowserDriverWith(intersectionSource, mediaSource) })`.
+ */
+export const makeBrowserDriverWith = (...sources: BrowserSource[]) => browserDriver(sources, new Map());
+
+/** Every browser source: `run(App, { BROWSER: makeBrowserDriver() })` */
+export const makeBrowserDriver = () => makeBrowserDriverWith(intersectionSource, resizeSource, mediaSource, storageSource, visibilitySource, onlineSource, geolocationSource, clipboardSource);

package/src/extra/command.ts

@@ -14,11 +14,11 @@ export interface Command {
   send(type: string, data?: any): void;
   /** @internal — raw stream used by component wiring */
   _stream: Stream<CommandMessage>;
-  /** @internal — marker for component.ts detection */
+  /** @internal — marker for the core's detection */
   __sygnalCommand: true;
-  /** @internal — stamped by component.ts when wired to a child */
+  /** @internal — stamped by the core when wired to a child */
   _targetComponentId?: number;
-  /** @internal — stamped by component.ts when wired to a child */
+  /** @internal — stamped by the core when wired to a child */
   _targetComponentName?: string;
 }
 

package/src/extra/controls.ts

@@ -0,0 +1,47 @@
+/**
+ * controls(spec) (PLAN-4 CT-1): element tokens that link a view to its intent by identifier.
+ *
+ *   const { Draft, Add } = controls({ Draft: 'input', Add: 'button' })
+ *   <Draft value={state.draft} /><Add>Add</Add>
+ *   App.intent = ({ DOM }) => ({ DRAFT: DOM.input(Draft).value(), ADD: DOM.click(Add) })
+ *
+ * Each key becomes a control: a JSX tag that renders its spec's element with every prop passed
+ * through plus data-control="<Key>" (merged into data.attrs), and that stringifies to
+ * [data-control="<Key>"], so it is accepted wherever a selector string is (DOM.select and the
+ * DOM.<event> shorthands through MainDOMSource.select, simulateEvent, query, template strings).
+ *
+ * A control is not a component: the pragma recognises it by its `__sygnalControl` render hook
+ * (src/pragma/index.ts) and calls it with the props, the children and its own createElement.
+ * The JSX runtime entries use the core's pragma (D188), so the `h` passed in is the core
+ * createElement; the hook keeps it a parameter (spec.vnode's contract, D101/D116).
+ *
+ * A spec is an intrinsic tag name or a spec object { kind, vnode(props, children, h), commands? }
+ * (the frozen contract D101/D116, PLAN-5 widgets build on it). vnode() must return one element
+ * vnode; the stamp keeps its key, hooks and other data, and the props' key is copied onto it
+ * when it has none. `kind` ('element' for a tag) and `spec` stay on the control (inspect(),
+ * element commands).
+ *
+ * In dev, the 'sygnal/diagnostics' entry publishes `control(control, vnode)` on the core bridge:
+ * SYG125 (component statics on a control, or a vnode() that isn't one element vnode) and the
+ * controls listed by inspect(). Without it (production) the call is skipped.
+ */
+export function controls(spec: Record<string, any>): Record<string, any> {
+  const out: Record<string, any> = {}
+  for (const key in spec) {
+    const s = spec[key]
+    const control: any = () => {}
+    control.__sygnalControl = (data: any, children: any[], h: any) => {
+      const v = typeof s == 'string' ? h(s, data, ...children) : s.vnode(data || {}, children, h)
+      ;(globalThis as any).__SYGNAL_DIAGNOSTICS__?.control?.(control, v)
+      const d = v.data ||= {}
+      d.attrs = {...d.attrs, 'data-control': key}
+      if (v.key === undefined && data) v.key = data.key
+      return v
+    }
+    control.toString = () => `[data-control="${key}"]`
+    control.kind = typeof s == 'string' ? 'element' : s.kind
+    control.spec = s
+    out[key] = control
+  }
+  return out
+}