babavoss 0.0.1 → 0.12.0

package/src/web/objects.tsx

@@ -0,0 +1,213 @@
+// Objects: OOUX read off the ECS. An object is a component with a key plus
+// whatever rides on the same entity; its attributes are their fields, its
+// relationships the entity fields and the co-location, its calls to action
+// the actions that take it. All of it is derived from the manifest and a
+// state, live or a film's frame: nothing is declared twice.
+import { useMemo, useState, type ReactNode } from "react";
+import type { Manifest, Call } from "../ecs/baba.ts";
+import type { Json } from "../kernel/schema.ts";
+import type { Replica } from "../ecs/replica.ts";
+import type { Hand } from "./app.tsx";
+import { Button, Input } from "./ui.tsx";
+import { collect, plan, type Field, type Plan } from "./form.ts";
+
+export interface ObjectRef { field: string; component: string; to: string }
+export interface ObjectAction { name: string; call: Call; arg: string; alone: boolean }
+/** One object of the baba: the keyed component that names it, and what the manifest says about it. */
+export interface ObjectType {
+  name: string;
+  owner: string;
+  /** The key field of the component; null for an object known by its entity alone, such as a window or a run. */
+  key: string | null;
+  fields: string[];
+  /** Entity fields on the key component, and on what rides with it, pointing at other objects. */
+  refs: ObjectRef[];
+  /** Actions that take this object: by an `s.entity(name)` arg, or by an arg named like the key from the same system. */
+  actions: ObjectAction[];
+}
+
+const props = (schema: Json): Record<string, Json> => (schema.properties as Record<string, Json> | undefined) ?? {};
+const keyOf = (schema: Json): string | undefined => Object.entries(props(schema)).find(([, p]) => p["x-key"] === true)?.[0];
+const required = (schema: Json): string[] => (schema.required as string[] | undefined) ?? [];
+
+/**
+ * The objects a manifest describes: every keyed component, with its relationships and calls to action. Given a state, also the
+ * objects known by their entity alone: the first component of each entity that carries no keyed one, a window, a run, an opening.
+ */
+export function objectsOf(m: Manifest, w?: Replica<any>): ObjectType[] {
+  const keyed: { name: string; owner: string; key: string | null; schema: Json }[] = Object.entries(m.components).flatMap(([name, c]) => { const k = keyOf(c.schema); return k === undefined ? [] : [{ name, owner: c.owner, key: k, schema: c.schema }]; });
+  const names = new Set(keyed.map((k) => k.name));
+  if (w) {
+    for (const e of w.all()) {
+      const parts = Object.keys(w.of(e));
+      if (parts.some((n) => names.has(n))) continue;
+      const first = parts.find((n) => n in m.components);
+      if (first && !names.has(first)) { names.add(first); keyed.push({ name: first, owner: m.components[first]!.owner, key: null, schema: m.components[first]!.schema }); }
+    }
+  }
+  return keyed.map((k) => {
+    const refs: ObjectRef[] = [];
+    for (const [cname, c] of Object.entries(m.components)) {
+      for (const [field, p] of Object.entries(props(c.schema))) {
+        const to = p["x-entity"] as string | undefined;
+        if (to && names.has(to) && (cname === k.name || !keyOf(c.schema))) refs.push({ field, component: cname, to });
+      }
+    }
+    const actions: ObjectAction[] = [];
+    for (const [name, call] of Object.entries(m.actions)) {
+      const ps = props(call.args);
+      const byEntity = Object.entries(ps).find(([, p]) => p["x-entity"] === k.name)?.[0];
+      // An arg named like the key, from the owning system, names the object too, unless the action already names an entity of some object.
+      const namesSome = Object.values(ps).some((p) => typeof p["x-entity"] === "string");
+      const byKey = !byEntity && !namesSome && k.key !== null && call.owner === k.owner && k.key in ps ? k.key : undefined;
+      const arg = byEntity ?? byKey;
+      if (!arg) continue;
+      actions.push({ name, call, arg, alone: required(call.args).every((r) => r === arg) });
+    }
+    return { name: k.name, owner: k.owner, key: k.key, fields: Object.keys(props(k.schema)), refs: refs.filter((r) => r.component === k.name || r.to !== k.name), actions };
+  }).sort((a, b) => a.owner.localeCompare(b.owner) || a.name.localeCompare(b.name));
+}
+
+/** The entities of a state that carry an object, with everything on them. */
+export function instancesOf(w: Replica<any>, type: ObjectType): { entity: number; parts: Record<string, unknown> }[] {
+  return w.all().map((e) => ({ entity: e, parts: w.of(e) })).filter((x) => type.name in x.parts);
+}
+/** The components seen beside an object in this state: what rides with it. */
+export function ridersOf(w: Replica<any>, type: ObjectType): string[] {
+  const seen = new Map<string, number>();
+  for (const i of instancesOf(w, type)) for (const n of Object.keys(i.parts)) if (n !== type.name) seen.set(n, (seen.get(n) ?? 0) + 1);
+  return [...seen.entries()].sort((a, b) => b[1] - a[1]).map(([n]) => n);
+}
+/** Entities carrying no object at all: worth seeing, usually a smell. */
+export function looseOf(w: Replica<any>, types: ObjectType[]): { entity: number; parts: Record<string, unknown> }[] {
+  const names = new Set(types.map((t) => t.name));
+  return w.all().map((e) => ({ entity: e, parts: w.of(e) })).filter((x) => !Object.keys(x.parts).some((n) => names.has(n)));
+}
+
+const short = (v: unknown, n = 60): string => { const s = typeof v === "string" ? v : JSON.stringify(v); return s.length > n ? s.slice(0, n - 1) + "…" : s; };
+const isPlain = (v: unknown) => v === null || ["string", "number", "boolean"].includes(typeof v);
+
+/** The object map as a rail: one row per object, its owner and how many there are; the sheet beside the pane says the rest. */
+export function ObjectMap({ types, w, picked, onPick }: { types: ObjectType[]; w?: Replica<any>; picked: string | null; onPick: (name: string) => void }) {
+  return (
+    <div className="bv-object-map">
+      {types.map((t) => (
+        <button key={t.name} className={`bv-object-col${picked === t.name ? " is-open" : ""}`} onClick={() => onPick(t.name)}>
+          <span className="bv-object-head"><b>{t.name}</b><span className="bv-muted">{t.owner}</span></span>
+          {w && <span className="bv-object-count">{instancesOf(w, t).length}</span>}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** What the manifest and this state say about an object, OOUX's four: key, attributes, what rides beside it and what it points to, calls to action. */
+export function ObjectSheet({ type, w }: { type: ObjectType; w: Replica<any> }) {
+  const riders = ridersOf(w, type);
+  const to = [...new Set(type.refs.map((r) => r.to))];
+  return (
+    <dl className="bv-object-sheet">
+      <dt>key</dt><dd>{type.key === null ? "the entity" : <code>{type.key}</code>}</dd>
+      <dt>attributes</dt><dd>{type.fields.filter((f) => f !== type.key).join(", ") || "—"}</dd>
+      {riders.length > 0 && <><dt>beside it</dt><dd>{riders.join(", ")}</dd></>}
+      {to.length > 0 && <><dt>points to</dt><dd>{to.join(", ")}</dd></>}
+      <dt>actions</dt><dd>{type.actions.length ? type.actions.map((a) => a.name).join(", ") : "—"}</dd>
+    </dl>
+  );
+}
+
+/** Every instance of an object in a state, as cards. */
+export function ObjectCards({ w, type, types, hand, onFollow }: { w: Replica<any>; type: ObjectType; types: ObjectType[]; hand?: Hand; onFollow?: (type: string, entity: number) => void }) {
+  const all = instancesOf(w, type);
+  if (all.length === 0) return <p className="bv-muted">No {type.name} in this state.</p>;
+  return <div className="bv-object-cards">{all.map((i) => <ObjectCard key={i.entity} w={w} entity={i.entity} parts={i.parts} type={type} types={types} hand={hand} onFollow={onFollow} />)}</div>;
+}
+
+/** One object: its key as the title, its attributes by component, its relationships as links, its calls to action as buttons when there is a hand. */
+export function ObjectCard({ w, entity, parts, type, types, hand, onFollow }: { w: Replica<any>; entity: number; parts: Record<string, unknown>; type: ObjectType; types: ObjectType[]; hand?: Hand; onFollow?: (type: string, entity: number) => void }) {
+  const [open, setOpen] = useState(false);
+  const [asking, setAsking] = useState<string | null>(null);
+  const own = parts[type.name] as Record<string, unknown>;
+  const key = type.key === null ? entity : own?.[type.key];
+  const byName = useMemo(() => new Map(types.map((t) => [t.name, t])), [types]);
+  const riders = Object.keys(parts).filter((n) => n !== type.name);
+  const refOf = (component: string, field: string) => type.refs.find((r) => r.component === component && r.field === field) ?? (byName.get(component)?.refs.find((r) => r.field === field));
+  const field = (component: string, name: string, value: unknown): ReactNode => {
+    const ref = refOf(component, name);
+    if (ref && typeof value === "number" && w.alive(value)) {
+      const target = byName.get(ref.to); const tp = w.of(value)[ref.to] as Record<string, unknown> | undefined;
+      return <button className="bv-object-ref" onClick={() => onFollow?.(ref.to, value)} title={`${ref.to} #${value}`}>→ {ref.to} {tp && target && target.key !== null ? short(tp[target.key], 24) : `#${value}`}</button>;
+    }
+    if (value === true) return <span className="bv-object-tag">yes</span>;
+    if (isPlain(value)) return <span className={typeof value === "string" ? "" : "bv-object-num"}>{value === null ? "—" : String(value) === "" ? "“”" : short(value)}</span>;
+    return <code title={JSON.stringify(value)}>{short(value, 40)}</code>;
+  };
+  const group = (component: string, value: unknown) => {
+    if (value === true) return <span className="bv-object-tag">tag</span>;
+    if (!value || typeof value !== "object") return field(component, "", value);
+    const entries = Object.entries(value as Record<string, unknown>).filter(([k]) => !(component === type.name && k === type.key));
+    const shown = open ? entries : entries.slice(0, 6);
+    return <dl className="bv-object-fields">{shown.map(([k, v]) => <div key={k}><dt>{k}</dt><dd>{field(component, k, v)}</dd></div>)}{entries.length > shown.length && <div><dt /><dd><button className="bv-object-more" onClick={() => setOpen(true)}>{entries.length - shown.length} more</button></dd></div>}</dl>;
+  };
+  return (
+    <article className="bv-object-card">
+      <header className="bv-object-card-head"><b>{type.name}</b>{type.key !== null && <span className="bv-object-key" title={String(key)}>{short(key, 48)}</span>}<span className="bv-muted">#{entity}</span></header>
+      {group(type.name, own)}
+      {riders.map((r) => <section key={r} className="bv-object-rider"><h4>{r}<span className="bv-muted">{types.find((t) => t.name === r) ? "object" : ""}</span></h4>{group(r, parts[r])}</section>)}
+      {type.actions.length > 0 && (
+        <footer className="bv-object-actions">
+          {type.actions.map((a) => a.alone
+            ? <Button key={a.name} variant="quiet" disabled={!hand} title={a.call.summary} onClick={() => hand?.fire(a.name, { [a.arg]: type.key === null ? entity : key })}>{a.name}</Button>
+            : <Button key={a.name} variant="quiet" className={asking === a.name ? "is-open" : "bv-object-needs"} disabled={!hand} title={`${a.call.summary} · needs ${required(a.call.args).filter((r) => r !== a.arg).join(", ")}`} onClick={() => setAsking(asking === a.name ? null : a.name)}>{a.name}…</Button>)}
+        </footer>
+      )}
+      {asking && hand && (() => { const a = type.actions.find((x) => x.name === asking)!; return <ArgsForm key={a.name} action={a} objectValue={type.key === null ? entity : key} onFire={(args) => { hand.fire(a.name, args); setAsking(null); }} onClose={() => setAsking(null)} />; })()}
+    </article>
+  );
+}
+
+/** Entities that carry no object, listed bare. */
+export function LooseList({ w, types }: { w: Replica<any>; types: ObjectType[] }) {
+  const loose = looseOf(w, types);
+  if (loose.length === 0) return null;
+  return (
+    <section className="bv-object-loose">
+      <h4>loose <span className="bv-muted">{loose.length} entit{loose.length === 1 ? "y" : "ies"} carrying no object</span></h4>
+      {loose.map((x) => <div key={x.entity} className="bv-state-entity"><code>#{x.entity}</code>{Object.entries(x.parts).map(([n, v]) => <span key={n} className="bv-state-part"><b>{n}</b>{v === true ? "" : <code>{short(v, 60)}</code>}</span>)}</div>)}
+    </section>
+  );
+}
+
+/** The rest of an action's arguments, asked on the card: the object's own arg is filled in; the others come from the action's schema, as the runner would ask them. */
+function ArgsForm({ action, objectValue, onFire, onClose }: { action: ObjectAction; objectValue: unknown; onFire: (args: unknown) => void; onClose: () => void }) {
+  const p: Plan = useMemo(() => plan(action.call.args), [action]);
+  const fields = p.fields.filter((f) => f.name !== action.arg);
+  const [values, setValues] = useState<Record<string, string | boolean>>({});
+  const [error, setError] = useState<string | null>(null);
+  const set = (f: Field, v: string | boolean) => setValues((x) => ({ ...x, [f.name]: v }));
+  const submit = () => {
+    try {
+      const rest = collect({ ...p, fields }, values) as Record<string, unknown>;
+      onFire({ ...rest, [action.arg]: objectValue });
+    } catch (e) { setError(e instanceof Error ? e.message : String(e)); }
+  };
+  return (
+    <form className="bv-object-form" onSubmit={(e) => { e.preventDefault(); submit(); }}>
+      <div className="bv-object-form-head"><b>{action.name}</b><span className="bv-muted">{action.call.summary}</span></div>
+      {fields.map((f) => (
+        <label key={f.name} className="bv-object-field">
+          <span>{f.name}{f.required ? "" : <em className="bv-muted"> optional</em>}</span>
+          {f.kind === "boolean"
+            ? <input type="checkbox" checked={values[f.name] === true} onChange={(e) => set(f, e.target.checked)} />
+            : f.kind === "enum"
+              ? <select value={String(values[f.name] ?? "")} onChange={(e) => set(f, e.target.value)}><option value="">—</option>{(f.options ?? []).map((o) => <option key={o} value={o}>{o}</option>)}</select>
+              : f.kind === "json" || f.kind === "list"
+                ? <textarea rows={2} value={String(values[f.name] ?? "")} placeholder={f.kind === "list" ? "one per line" : "JSON"} onChange={(e) => set(f, e.target.value)} />
+                : <Input value={String(values[f.name] ?? "")} placeholder={f.description ?? f.kind} onChange={(e) => set(f, e.target.value)} />}
+        </label>
+      ))}
+      {error && <p className="bv-error">{error}</p>}
+      <div className="bv-row"><Button variant="primary" type="submit">{action.name}</Button><Button variant="quiet" onClick={onClose}>cancel</Button></div>
+    </form>
+  );
+}

package/src/web/socket.ts

@@ -0,0 +1,84 @@
+// A window's socket to its baba: hello with the page token, the round held
+// and what it follows, then frames down and calls up, in order, on one
+// connection. Closed, it reconnects with a little patience and hellos again
+// from where it stands; refused for good, it stops and says so.
+import { ApiError, pageToken } from "./core.tsx";
+import { CLOSE, SOCKET_PROTOCOL, type Down, type Interest, type Up, type Welcome } from "../server/protocol.ts";
+export type { Welcome };
+
+export interface Hears {
+  welcome(w: Welcome): void;
+  frame(bytes: Uint8Array): void;
+  /** The connection came or went; gone for good, with why. */
+  connected(up: boolean, refused?: string): void;
+}
+
+/** An answer to a call: what it returned, and the round a fire or a raw write ran in. */
+export interface Answer { value: unknown; round?: number }
+
+/** Close codes after which another try would end the same way. */
+const FINAL = new Set<number>([CLOSE.unauthorized, CLOSE.badProtocol, CLOSE.unknown]);
+
+export class Link {
+  private ws: WebSocket | null = null;
+  private pending = new Map<number, { resolve: (a: Answer) => void; reject: (e: Error) => void }>();
+  private nextId = 1;
+  private patience = 250;
+  private gone = false;
+
+  constructor(private scope: string, private held: () => number, private interest: () => Interest, private hears: Hears) { this.connect(); }
+
+  private connect(): void {
+    if (this.gone) return;
+    const url = `${location.protocol === "https:" ? "wss" : "ws"}://${location.host}/ws/${encodeURIComponent(this.scope)}`;
+    const ws = new WebSocket(url);
+    ws.binaryType = "arraybuffer";
+    ws.onopen = () => { this.patience = 250; this.hello(); this.hears.connected(true); };
+    ws.onmessage = (e) => {
+      if (typeof e.data === "string") this.down(JSON.parse(e.data) as Down);
+      else this.hears.frame(new Uint8Array(e.data as ArrayBuffer));
+    };
+    ws.onclose = (e) => {
+      if (this.ws !== ws) return;
+      this.ws = null;
+      for (const p of this.pending.values()) p.reject(new ApiError("closed", "the connection closed", 0));
+      this.pending.clear();
+      if (FINAL.has(e.code)) { this.gone = true; this.hears.connected(false, e.reason || `closed with ${e.code}`); return; }
+      this.hears.connected(false);
+      if (!this.gone) setTimeout(() => this.connect(), this.patience);
+      this.patience = Math.min(this.patience * 2, 4000);
+    };
+    ws.onerror = () => { /* the close says it */ };
+    this.ws = ws;
+  }
+
+  private down(m: Down): void {
+    if (m.type === "welcome") { this.hears.welcome(m); return; }
+    if (m.type === "generation") { this.hello(); return; }
+    const p = this.pending.get(m.id);
+    if (!p) return;
+    this.pending.delete(m.id);
+    if (m.ok) p.resolve({ value: m.value, ...(m.round !== undefined ? { round: m.round } : {}) });
+    else p.reject(new ApiError(m.code, m.message, 0));
+  }
+
+  get up(): boolean { return this.ws?.readyState === WebSocket.OPEN; }
+
+  /** Says hello from the round held and with what the window follows: a welcome and the state since come back. */
+  hello(): void { this.send({ type: "hello", protocol: SOCKET_PROTOCOL, token: pageToken(), since: this.held(), interest: this.interest() }); }
+  /** What the window follows now, whole: the edge cuts every frame to it from here on. */
+  subscribe(interest: Interest): void { this.send({ type: "subscribe", interest }); }
+  /** Asks for the whole again: after a frame that did not apply. */
+  resync(): void { this.send({ type: "resync" }); }
+
+  private send(m: Up): void { if (this.up) this.ws!.send(JSON.stringify(m)); }
+
+  /** A fire, a read or a raw write over the socket; refused when it is down, so the caller may try the API. */
+  call(m: Extract<Up, { id: number }> extends infer U ? (U extends { id: number } ? Omit<U, "id"> : never) : never): Promise<Answer> {
+    if (!this.up) return Promise.reject(new ApiError("down", "the socket is not connected", 0));
+    const id = this.nextId++;
+    return new Promise<Answer>((resolve, reject) => { this.pending.set(id, { resolve, reject }); this.ws!.send(JSON.stringify({ ...m, id })); });
+  }
+
+  close(): void { this.gone = true; this.ws?.close(); this.ws = null; }
+}

package/src/web/state.tsx

@@ -0,0 +1,69 @@
+// The baba in a window: its calls and its state of connection, and, with
+// useBabaState, the whole state as a replica that every round replaces. The
+// targeted hooks beside it (useQuery, useComponent, …) read parts of the
+// state and wake only when those move; useBabaState wakes every round and asks
+// the socket for everything.
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { useLiveStore } from "./hooks.ts";
+import type { Replica } from "../ecs/replica.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { ActOf as ContractActs, ReadOf as ContractReads } from "../ecs/baba.ts";
+export type { FollowSample, Probe } from "./store.ts";
+
+type Calls = Record<string, { args: unknown; result: unknown }>;
+type ActOf<V> = [ContractActs<V>] extends [never] ? Calls : unknown extends ContractActs<V> ? Calls : ContractActs<V>;
+type ReadOf<V> = [ContractReads<V>] extends [never] ? Calls : unknown extends ContractReads<V> ? Calls : ContractReads<V>;
+type ArgsOf<D> = D extends { args: infer A } ? ({} extends A ? [args?: A] : [args: A]) : [];
+type ResultOf<D> = D extends { result: infer R } ? R : unknown;
+
+/** The baba from a window: what to call, and whether the window is connected. */
+export interface BabaView<V> {
+  /** Fires an action: what it returned. */
+  fire<K extends keyof ActOf<V> & string>(name: K, ...args: ArgsOf<ActOf<V>[K]>): Promise<ResultOf<ActOf<V>[K]>>;
+  /** Fires an action: what it returned, and the round it ran in, which the window reaches when its effect is in view (`useSettled`). */
+  fireIn<K extends keyof ActOf<V> & string>(name: K, ...args: ArgsOf<ActOf<V>[K]>): Promise<{ value: ResultOf<ActOf<V>[K]>; round: number | undefined }>;
+  /** Reads a query. */
+  read<K extends keyof ReadOf<V> & string>(name: K, ...args: ArgsOf<ReadOf<V>[K]>): Promise<ResultOf<ReadOf<V>[K]>>;
+  /** A write at layer zero: the inspector's, and a shell's. */
+  raw(op: Raw): Promise<unknown>;
+  /** A first frame has landed. */
+  ready: boolean;
+  /** The socket is up: frames come as rounds end. Down, calls go over the API and the state waits. */
+  connected: boolean;
+  /** Why the socket will not come back, when it will not. */
+  refused: string | null;
+}
+
+export interface BabaStateView<V> extends BabaView<V> {
+  /** The state at the latest round, read-only; every round replaces it. */
+  w: Replica<V>;
+  round: number;
+}
+
+/** The baba's calls and standing, without the state: for a view built on the targeted hooks. Wakes only when the connection changes. */
+export function useBaba<V = unknown>(_v?: V): BabaView<V> {
+  const st = useLiveStore();
+  const ready = useSyncExternalStore(st.subscribe, () => st.ready);
+  const connected = useSyncExternalStore(st.subscribe, () => st.connected);
+  const refused = useSyncExternalStore(st.subscribe, () => st.refused);
+  return useMemo(() => ({
+    ready, connected, refused,
+    fire: (name: string, args?: unknown) => st.fire(name, args),
+    fireIn: (name: string, args?: unknown) => st.fireIn(name, args),
+    read: (name: string, args?: unknown) => st.read(name, args),
+    raw: (op: Raw) => st.raw(op),
+  }) as BabaView<V>, [st, ready, connected, refused]);
+}
+
+/**
+ * `import baba from "./index"` in the view, then `const { w, fire } = useBabaState(baba)`:
+ * `w.query(tasks.task)` reads, `fire("refresh")` writes. Without `baba`, untyped.
+ * The whole state, every round: for a page that reads anything anywhere.
+ */
+export function useBabaState<V = unknown>(v?: V): BabaStateView<V> {
+  const st = useLiveStore();
+  const baba = useBaba(v);
+  useEffect(() => st.wantAll(), [st]);
+  const w = useSyncExternalStore(st.subscribe, () => st.replica) as Replica<V>;
+  return useMemo(() => ({ ...baba, w, round: w.round }), [baba, w]);
+}

package/src/web/store.ts

@@ -0,0 +1,221 @@
+// The state as one window holds it: a replica moved by the frames on the
+// window's socket, the hooks' subscriptions over it, what the hooks are
+// interested in, the calls, and the probe. One per baba per page, shared
+// by every hook and every useBabaState on it; opened when the first holder
+// mounts, closed a moment after the last one leaves.
+import { Replica } from "../ecs/replica.ts";
+import { isDelta, type StateAnswer } from "../ecs/snapshot.ts";
+import { codecOf, decodeFrame, type Codec } from "../ecs/codec.ts";
+import type { Component, Entity, Resource, Select, Term } from "../ecs/state.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { Interest } from "../server/protocol.ts";
+import { api } from "./core.tsx";
+import { Link, type Answer } from "./socket.ts";
+
+/** One round as the window received it. Times in ms. */
+export interface FollowSample {
+  round: number;
+  /** When it arrived: performance.now(). */
+  at: number;
+  /** The frame's size on the wire. */
+  bytes: number;
+  /** A whole, not a delta: first contact, a resync, or too far behind. */
+  whole: boolean;
+  /** The entities the frame carried. */
+  entities: number;
+  /** From the round's time to the arrival, on the machine's one clock: how far behind the state the window was. NaN when the frame carries no time. */
+  lagMs: number;
+  /** Decoding the frame and applying it to the replica. */
+  applyMs: number;
+  /** From the replica set to the page committed: the render of everything that reads the state. NaN until committed. */
+  renderMs: number;
+}
+/** What following has cost this window: the last rounds, oldest first. A new list every round; the last sample's render time is filled in after its commit. */
+export interface Probe { samples: FollowSample[] }
+const PROBE_KEEP = 300;
+/** How long a store outlives its last holder: a strict-mode remount, a page's panels swapping. */
+const LINGER_MS = 300;
+
+/** A count per name. */
+class Counts {
+  private n = new Map<string, number>();
+  add(k: string): void { this.n.set(k, (this.n.get(k) ?? 0) + 1); }
+  drop(k: string): void { const c = (this.n.get(k) ?? 0) - 1; if (c <= 0) this.n.delete(k); else this.n.set(k, c); }
+  keys(): string[] { return [...this.n.keys()]; }
+}
+
+export class StateStore {
+  replica = new Replica();
+  ready = false;
+  connected = false;
+  /** Why the socket will not come back, when it will not: a wrong token, another protocol, no such baba. */
+  refused: string | null = null;
+  probe: Probe = { samples: [] };
+  private readonly samples: FollowSample[] = [];
+  private pending: FollowSample | null = null;
+  private listeners = new Set<() => void>();
+  private link: Link | null = null;
+  private codec: Codec | null = null;
+  private holders = 0;
+  private linger: ReturnType<typeof setTimeout> | null = null;
+  // The interest, counted per hook; told as one when it changed, and what was let go of forgotten then.
+  private all = 0;
+  private presence = new Counts();
+  private values = new Counts();
+  private parts = new Map<string, Counts>();
+  private resources = new Counts();
+  private told: Interest = {};
+  private telling: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(readonly scope: string) {}
+
+  // ---- holders --------------------------------------------------------------
+
+  /** A hook mounted: the socket opens for the first; answers what to call when it unmounts. */
+  retain(): () => void {
+    this.holders++;
+    if (this.linger) { clearTimeout(this.linger); this.linger = null; }
+    if (!this.link) this.open();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.holders--;
+      if (this.holders > 0) return;
+      this.linger = setTimeout(() => { this.linger = null; if (this.holders === 0) this.close(); }, LINGER_MS);
+    };
+  }
+
+  private open(): void {
+    this.replica = new Replica(); this.ready = false; this.codec = null; this.refused = null;
+    this.link = new Link(this.scope, () => this.replica.round, () => { this.told = this.interest(); return this.told; }, {
+      welcome: (m) => { this.codec = codecOf(m.components, m.resources); },
+      connected: (up, refused) => { this.connected = up; if (refused) this.refused = refused; this.notify(); },
+      frame: (bytes) => this.frame(bytes),
+    });
+  }
+
+  private close(): void {
+    this.link?.close();
+    this.link = null;
+    this.replica = new Replica(); this.ready = false; this.connected = false; this.told = {};
+    this.notify();
+  }
+
+  private frame(bytes: Uint8Array): void {
+    const l = this.link;
+    if (!this.codec || !l) return;
+    const at = performance.now();
+    const held = this.replica;
+    let s: StateAnswer;
+    try { s = decodeFrame(this.codec, bytes); } catch { l.resync(); return; }
+    if (isDelta(s) && s.since !== held.round) { if (s.round > held.round) l.resync(); return; }
+    const next = held.apply(s);
+    const sample: FollowSample = {
+      round: s.round, at, bytes: bytes.byteLength, whole: !isDelta(s), entities: Object.keys(s.entities).length,
+      lagMs: s.now === undefined ? NaN : Date.now() - s.now, applyMs: performance.now() - at, renderMs: NaN,
+    };
+    this.samples.push(sample);
+    if (this.samples.length > PROBE_KEEP) this.samples.splice(0, this.samples.length - PROBE_KEEP);
+    this.probe = { samples: this.samples.slice() };
+    this.pending = sample;
+    this.replica = next; this.ready = true;
+    this.notify();
+  }
+
+  /** The page committed with the replica now held: the last frame's render is over. */
+  committed(): void {
+    const s = this.pending;
+    if (s) { s.renderMs = performance.now() - s.at - s.applyMs; this.pending = null; }
+  }
+
+  // ---- subscriptions ----------------------------------------------------------
+
+  subscribe = (fn: () => void): (() => void) => { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; };
+  private notify(): void { for (const fn of this.listeners) fn(); }
+
+  // ---- interest ---------------------------------------------------------------
+
+  /** What the window's hooks ask for, as one. */
+  interest(): Interest {
+    if (this.all > 0) return { all: true };
+    const parts: Record<string, number[]> = {};
+    for (const [name, c] of this.parts) { const ids = c.keys().map(Number); if (ids.length) parts[name] = ids; }
+    return { presence: this.presence.keys(), values: this.values.keys(), parts, resources: this.resources.keys() };
+  }
+
+  /** The interest changed: after this turn, so a commit's hooks speak together, tell the socket and let go of what nobody asks for any more. */
+  private tell(): void {
+    if (this.telling) return;
+    this.telling = setTimeout(() => { this.telling = null; this.tellNow(); }, 0);
+  }
+  private tellNow(): void {
+    const next = this.interest();
+    if (JSON.stringify(next) === JSON.stringify(this.told)) return;
+    this.forget(this.told, next);
+    this.told = next;
+    this.link?.subscribe(next);
+  }
+
+  /** Every component the interest `was` held that `now` holds less of: the values nobody asks for become held presences, or go. */
+  private forget(was: Interest, now: Interest): void {
+    if (now.all) return;
+    const names = was.all ? this.replica.components() : new Set([...(was.presence ?? []), ...(was.values ?? []), ...Object.keys(was.parts ?? {})]);
+    const presence = new Set(now.presence ?? []), values = new Set(now.values ?? []);
+    for (const name of names) {
+      if (values.has(name)) continue;
+      this.replica.forget(name, { presence: presence.has(name), values: new Set(now.parts?.[name] ?? []) });
+    }
+  }
+
+  wantAll(): () => void { this.all++; this.tell(); return () => { this.all--; this.tell(); }; }
+  wantPresence(c: Component): () => void { this.presence.add(c.name); this.tell(); return () => { this.presence.drop(c.name); this.tell(); }; }
+  wantValues(c: Component): () => void { this.values.add(c.name); this.tell(); return () => { this.values.drop(c.name); this.tell(); }; }
+  wantPart(e: Entity, c: Component): () => void {
+    let p = this.parts.get(c.name);
+    if (!p) { p = new Counts(); this.parts.set(c.name, p); }
+    p.add(String(e)); this.tell();
+    return () => { p!.drop(String(e)); this.tell(); };
+  }
+  wantResource(r: Resource): () => void { this.resources.add(r.name); this.tell(); return () => { this.resources.drop(r.name); this.tell(); }; }
+
+  /** What a select needs: the presence of every component it names, and their values when it has a predicate, an order or a change term. */
+  wantSelect(sel: Select<readonly Term[]>): () => void {
+    const comps: Component[] = [];
+    let sensitive = sel.pred !== null || sel.order !== null;
+    for (const t of sel.terms) {
+      if (t.kind === "component") comps.push(t);
+      else if (t.kind === "not") comps.push(...t.components);
+      else { comps.push(t.component); sensitive = true; }
+    }
+    const drops = comps.map((c) => (sensitive ? this.wantValues(c) : this.wantPresence(c)));
+    return () => { for (const d of drops) d(); };
+  }
+
+  // ---- calls ------------------------------------------------------------------
+
+  /** Over the socket when it is up, over the API when it is not. */
+  async fireIn(name: string, args?: unknown): Promise<Answer> {
+    const l = this.link;
+    if (l?.up) return l.call({ type: "fire", name, args: args ?? {} });
+    return { value: await api("fire", this.scope, name, args ?? {}) };
+  }
+  fire(name: string, args?: unknown): Promise<unknown> { return this.fireIn(name, args).then((a) => a.value); }
+  read(name: string, args?: unknown): Promise<unknown> {
+    const l = this.link;
+    return l?.up ? l.call({ type: "read", name, args: args ?? {} }).then((a) => a.value) : api("read", this.scope, name, args ?? {});
+  }
+  raw(op: Raw): Promise<unknown> {
+    const { op: kind, ...rest } = op;
+    const l = this.link;
+    return l?.up ? l.call({ type: "raw", op: kind, ...rest }).then((a) => a.value) : api("raw", this.scope, kind, rest);
+  }
+}
+
+const stores = new Map<string, StateStore>();
+/** The one store of a baba on this page. */
+export function storeFor(scope: string): StateStore {
+  let s = stores.get(scope);
+  if (!s) { s = new StateStore(scope); stores.set(scope, s); }
+  return s;
+}