@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/scene.js

@@ -0,0 +1,1531 @@
+// The scene (PLAN v0.24 §1, §5, §10), the JS spelling of the Rust client's `scene.rs`: the active
+// project's scene as this node sees it.
+//
+// `scene()` follows the incarnations the runtime announces under `runtime/scene/` (`@<epoch>`, one at
+// a time: the active project's) and reads both tracks of the one it binds to: `authored` (a snapshot
+// frame, then one diff frame per applied batch; a later group is a fresh snapshot that replaces the
+// copy) and `live` (each group starts with the whole live set, then one frame per runtime tick). The
+// copy this node keeps (the mirror) is authored ⊕ live: a live row replaces `xform.t/q`, `joints` and
+// `state` of the authored entity it names; a live entity is a row of its own. Nothing is kept across
+// incarnations.
+//
+// One task per node, the store's shape: every `scene()` on the node shares it; the task owns the
+// session it is told about (`Node.monitor`), the incarnation it reads, the mirror and the writes in
+// flight, and is driven by one mailbox, in order:
+// - `session` / `sessionEnded` / `nodeEnded`: what was bound on the previous session is over (the
+//   mirror empties, the handle is `detached`); the announcements are followed again on the new one;
+// - the incarnation's tracks are read by the task's reader (the only writer of the mirror), which
+//   tells the task of each authored frame applied (`applied`); the incarnation's end (its final frame,
+//   or the tracks ending) empties the mirror and the announcements are followed again (`followEnded`);
+// - `join`: a `scene()` call waiting for the scene to be in (attached, or no project active);
+// - `apply` / `applyDone`: an authoring batch (it names the bound incarnation's epoch) and the
+//   runtime's answer; the caller is answered once the mirror shows the version;
+// - `notice`: the runtime dropped some of this node's live rows (`not_owner` with `data.ids`);
+// - `close`: the last open handle left.
+//
+// States: `attached` (an incarnation's snapshot is in the mirror, and every frame of both tracks this
+// node already held when the first frame of each arrived has been applied), `detached` (none: no
+// active project, a session gap, between incarnations), `closed` (`close()` or the node ending). While
+// detached the entities are empty, every author verb fails `project_inactive` at once and `live()`
+// drops its batch and counts it. A closed handle's verbs fail `not_connected`.
+//
+// Known behaviour (as the Rust client's):
+// - live rows that disappear only through a keyframe (the ticks that removed them were missed) leave
+//   the entities but are not reported on `watchLiveRemovals`: a keyframe carries no reason;
+// - a node that closes its last scene handle and opens a new one on the same session announces a new
+//   live writer track; the runtime follows one writer per session, so while its follower of the old
+//   track is still ending, the new track may be ignored.
+//
+// The runtime decides every write: nothing is checked here, a refused batch is the caller's error and
+// never retried; a `conflict` naming a stale epoch makes the task let go of the incarnation it reads
+// and follow the announcements again.
+import * as Moq from "@moq/net";
+import { FLAGS, SynapseError, TYPES, decode as decodeBody, decodeHeader, encode as encodeBody, moqPriority, nowUs } from "@synapse-sdk/core";
+import { startOn } from "./calls.js";
+import { REFOLLOW_PACE_MS } from "./channel.js";
+import { CALL_GROUP_MAX_AGE_MS, StreamWriter, frameTooLarge, latestSubscription, waitActive } from "./session.js";
+import { AsyncQueue, deferred, replaceEqualDeep } from "./util.js";
+/** Where the runtime announces the scene's incarnations: `runtime/scene/@<epoch>`. */
+const SCENE_BASE = "runtime/scene";
+const AUTHORED_TRACK = "authored";
+const LIVE_TRACK = "live";
+/** What a closed handle's errors name when the node ended. */
+const ENDED_CONNECTION_LOST = "connection_lost";
+/** What they name after `close()`. */
+const ENDED_CLIENT = "client";
+/** How many batches a feed may fall behind before it is ended (the store's `STORE_FEED_CAP`). */
+export const SCENE_FEED_CAP = 256;
+/** Keys a `patch` may not set (the runtime refuses them); a txn never folds such a patch into a spawn. */
+export const PATCH_PROTECTED = ["id", "name", "parent", "order", "layer", "meta"];
+/** moq's cap on one frame. */
+const MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const EMPTY = Object.freeze({});
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v) && !(v instanceof Uint8Array);
+/** Deep equality of decoded values (structural sharing keeps `a` when equal). */
+const deepEqual = (a, b) => replaceEqualDeep(a, b) === a;
+const parentOf = (e) => (typeof e.parent === "string" ? e.parent : null);
+const orderOf = (e) => (typeof e.order === "string" ? e.order : undefined);
+const rethrowLater = (e) => { queueMicrotask(() => { throw e; }); };
+// ------------------------------------------------------------------------------------- helpers
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const RAND_BITS = 74n;
+let lastMs = 0;
+let lastRand = 0n;
+/**
+ * A fresh entity id: a ULID (26 Crockford base-32 characters) made from a UUIDv7 (48-bit ms, version,
+ * 74 random bits, variant), so ids sort by the time they were minted; within one millisecond the
+ * random part counts up, so ids minted here keep their order.
+ */
+export function ulid() {
+    let ms = Date.now();
+    let rand;
+    if (ms <= lastMs) {
+        ms = lastMs;
+        rand = (lastRand + 1n) & ((1n << RAND_BITS) - 1n);
+    }
+    else {
+        const b = new Uint8Array(10);
+        crypto.getRandomValues(b);
+        rand = b.reduce((n, x) => (n << 8n) | BigInt(x), 0n) & ((1n << RAND_BITS) - 1n);
+    }
+    lastMs = ms;
+    lastRand = rand;
+    const n = (BigInt(ms) << 80n) | (7n << 76n) | ((rand >> 62n) << 64n) | (2n << 62n) | (rand & ((1n << 62n) - 1n));
+    let out = "";
+    for (let i = 0; i < 26; i++)
+        out += CROCKFORD[Number((n >> BigInt(125 - 5 * i)) & 31n)];
+    return out;
+}
+// The fractional `order` (the runtime's `order.rs`, loro's family): an index is bytes ending with the
+// terminator 0x80, compared bytewise; on the wire lowercase hex (which keeps the byte order).
+const TERMINATOR = 0x80;
+const ORDER_MAX_BYTES = 512;
+function orderBytes(hex) {
+    const ok = hex.length > 0 && hex.length % 2 === 0 && /^[0-9a-f]+$/.test(hex);
+    const bytes = ok ? Array.from({ length: hex.length / 2 }, (_, i) => parseInt(hex.slice(2 * i, 2 * i + 2), 16)) : [];
+    if (!ok || bytes.length > ORDER_MAX_BYTES || bytes[bytes.length - 1] !== TERMINATOR)
+        throw new SynapseError("invalid_input", `order ${JSON.stringify(hex)} is not a canonical index (lowercase hex ending in 80)`);
+    return bytes;
+}
+const orderHex = (bytes) => bytes.map(b => b.toString(16).padStart(2, "0")).join("");
+function beforeBytes(bytes, i = 0) {
+    for (;; i++) {
+        const b = bytes[i];
+        if (b > TERMINATOR)
+            return bytes.slice(0, i);
+        if (b > 0)
+            return [...bytes.slice(0, i), b - 1];
+    }
+}
+function afterBytes(bytes, i = 0) {
+    for (;; i++) {
+        const b = bytes[i];
+        if (b < TERMINATOR)
+            return bytes.slice(0, i);
+        if (b < 0xff)
+            return [...bytes.slice(0, i), b + 1];
+    }
+}
+function betweenBytes(left, right) {
+    const shorter = Math.min(left.length, right.length) - 1;
+    for (let i = 0; i < shorter; i++) {
+        const lb = left[i], rb = right[i];
+        if (rb - lb > 1)
+            return [...left.slice(0, i), lb + Math.floor((rb - lb) / 2)];
+        if (rb - lb === 1)
+            return [...left.slice(0, i + 1), ...afterBytes(left.slice(i + 1))];
+        if (rb - lb < 0)
+            return undefined;
+    }
+    if (left.length < right.length) {
+        const prefix = right.slice(0, shorter + 1);
+        if (prefix[prefix.length - 1] < TERMINATOR)
+            return undefined;
+        return [...prefix, ...beforeBytes(right.slice(shorter + 1))];
+    }
+    if (left.length === right.length)
+        return undefined;
+    const prefix = left.slice(0, shorter + 1);
+    if (prefix[prefix.length - 1] >= TERMINATOR)
+        return undefined;
+    return [...prefix, ...afterBytes(left.slice(shorter + 1))];
+}
+/** An `order` strictly before `order`. */
+export function orderBefore(order) { return orderHex([...beforeBytes(orderBytes(order)), TERMINATOR]); }
+/** An `order` strictly after `order`. */
+export function orderAfter(order) { return orderHex([...afterBytes(orderBytes(order)), TERMINATOR]); }
+/** An `order` strictly between `left` and `right` (either may be open: `null`); `invalid_input` when `left >= right`. */
+export function orderBetween(left, right) {
+    if (left == null && right == null)
+        return orderHex([TERMINATOR]);
+    if (right == null)
+        return orderAfter(left);
+    if (left == null)
+        return orderBefore(right);
+    const b = betweenBytes(orderBytes(left), orderBytes(right));
+    if (!b)
+        throw new SynapseError("invalid_input", `no order between ${left} and ${right}: the bounds are equal or inverted`);
+    return orderHex([...b, TERMINATOR]);
+}
+/**
+ * The hierarchy of `entities`, as its roots: each node's children by `(order, id)` (an entity without
+ * an `order` after the ordered ones); an entity whose parent is not in the scene is a root (the
+ * prototype's rule). A cycle cannot come from the runtime; were one there, it is cut where it closes.
+ */
+export function treeOf(entities) {
+    const groups = new Map();
+    for (const [id, e] of Object.entries(entities)) {
+        let p = parentOf(e);
+        if (p !== null && !(p in entities))
+            p = null;
+        const o = orderOf(e);
+        let g = groups.get(p);
+        if (!g)
+            groups.set(p, (g = []));
+        g.push([o === undefined, o ?? "", id]);
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    const seen = new Set();
+    const build = (parent) => {
+        const kids = groups.get(parent);
+        if (!kids)
+            return [];
+        kids.sort((a, b) => (a[0] !== b[0] ? (a[0] ? 1 : -1) : cmp(a[1], b[1]) || cmp(a[2], b[2])));
+        const out = [];
+        for (const [, , id] of kids) {
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push({ id, children: build(id) });
+        }
+        return out;
+    };
+    return build(null);
+}
+// -------------------------------------------------------------------------------------------- txn
+/** One level of the runtime's patch merge: an object merges into an object key by key; anything else replaces. */
+function mergeSet(into, set) {
+    const out = { ...into };
+    for (const [k, v] of Object.entries(set)) {
+        if (v === undefined)
+            continue;
+        const old = out[k];
+        out[k] = isObject(old) && isObject(v) ? { ...old, ...v } : v;
+    }
+    return out;
+}
+/**
+ * One authoring batch being built (`txn`): the ops it sends as one atomic `apply`. Ops on an entity
+ * spawned in the same batch fold into its spawn: a patch (of keys a patch may set) or a rename merges
+ * into it, a despawn cancels it (with every entity spawned under it in the batch). Nothing else is
+ * checked here: the runtime decides.
+ */
+export class Txn {
+    #ops = [];
+    get ops() { return this.#ops; }
+    #spawnIndex(id) { return this.#ops.findIndex(op => op.op === "spawn" && op.entity.id === id); }
+    #spawnedUnder(parent) {
+        return this.#ops.flatMap(op => (op.op === "spawn" && op.entity.parent === parent ? [op.entity.id] : []));
+    }
+    /** Spawns an entity of `kind` under `opts.parent` (default the world root) with the components given (`layer` `authored` when not given); its id is minted here (or `opts.id`, a known one) and returned. No `order` is sent: the runtime appends it after its siblings. */
+    spawn(kind, opts) {
+        const { parent, id: given, ...components } = opts;
+        const id = given ?? ulid();
+        const entity = { ...components, id, kind, parent: parent ?? null };
+        entity.layer ??= "authored";
+        this.#ops.push({ op: "spawn", entity });
+        return id;
+    }
+    /** Sets components of `id` (one level deep: an object merges into an object). */
+    patch(id, set) {
+        // A protected key is the runtime's to refuse: such a patch is sent as it is.
+        const protectedKey = Object.keys(set).some(k => PATCH_PROTECTED.includes(k));
+        const i = protectedKey ? -1 : this.#spawnIndex(id);
+        if (i >= 0) {
+            const op = this.#ops[i];
+            this.#ops[i] = { op: "spawn", entity: mergeSet(op.entity, set) };
+            return;
+        }
+        this.#ops.push({ op: "patch", id, set });
+    }
+    rename(id, name) {
+        const i = this.#spawnIndex(id);
+        if (i >= 0) {
+            const op = this.#ops[i];
+            this.#ops[i] = { op: "spawn", entity: { ...op.entity, name } };
+            return;
+        }
+        this.#ops.push({ op: "rename", id, name });
+    }
+    /** Moves `id` under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
+    reparent(id, parent, place) {
+        const op = { op: "reparent", id, parent };
+        if (place && "before" in place)
+            op.before = place.before;
+        else if (place && "after" in place)
+            op.after = place.after;
+        this.#ops.push(op);
+    }
+    /** Despawns `id` (`cascade`: with its subtree). One spawned in this batch is cancelled instead, unless it has children spawned in the batch and `cascade` is off (then the runtime decides). */
+    despawn(id, opts = {}) {
+        const cascade = opts.cascade ?? false;
+        if (this.#spawnIndex(id) >= 0 && (cascade || this.#spawnedUnder(id).length === 0)) {
+            this.#cancel(id);
+            return;
+        }
+        this.#ops.push({ op: "despawn", id, cascade });
+    }
+    /** Locks or unlocks `id` (a flags-only patch, which a lock lets through). */
+    setLocked(id, locked) { this.patch(id, { flags: { locked } }); }
+    /** Drops this batch's spawn of `id`, every op naming it, and the spawns under it. */
+    #cancel(id) {
+        const children = this.#spawnedUnder(id);
+        for (let i = this.#ops.length - 1; i >= 0; i--) {
+            const op = this.#ops[i];
+            if ((op.op === "spawn" && op.entity.id === id) || (op.op !== "spawn" && op.id === id))
+                this.#ops.splice(i, 1);
+        }
+        for (const c of children)
+            this.#cancel(c);
+    }
+}
+// ----------------------------------------------------------------------------------- the folds
+/**
+ * Applies one diff op of a batch the runtime stamped `t` by `by` to the authored entities (the
+ * runtime's result, as the op describes it); returns the ids whose entity changed. A changed entity's
+ * `meta` is `{rev, t, by}`, as the runtime stamped it.
+ */
+export function foldAuthored(authored, op, t, by) {
+    const stamped = (e, rev) => ({ ...e, meta: { rev, t, by } });
+    switch (op.op) {
+        case "spawn": {
+            const id = op.entity?.id;
+            if (typeof id !== "string")
+                return [];
+            authored.set(id, op.entity);
+            return [id];
+        }
+        case "despawn":
+            for (const id of op.removed)
+                authored.delete(id);
+            return [...op.removed];
+        case "patch": {
+            const e = authored.get(op.id);
+            if (!e)
+                return [];
+            authored.set(op.id, stamped(mergeSet(e, op.set), op.rev));
+            return [op.id];
+        }
+        case "reparent": {
+            const e = authored.get(op.id);
+            if (!e)
+                return [];
+            const next = { ...e, parent: op.parent ?? null, order: op.order };
+            if (op.xform)
+                next.xform = op.xform;
+            authored.set(op.id, stamped(next, op.rev));
+            return [op.id];
+        }
+        case "rename": {
+            const e = authored.get(op.id);
+            if (!e)
+                return [];
+            authored.set(op.id, stamped({ ...e, name: op.name }, op.rev));
+            return [op.id];
+        }
+    }
+    return [];
+}
+/** What changed from `old` to `next`, in the diff ops' shapes (a snapshot replacing the mirror, the mirror emptying): a spawn per new entity, a despawn per gone one, and per changed one a reparent (parent or order), a rename (name) and a patch of the other keys that differ. */
+export function netDifference(old, next) {
+    const ops = [];
+    for (const [id, e] of next) {
+        const o = old.get(id);
+        if (!o) {
+            ops.push({ op: "spawn", entity: e });
+            continue;
+        }
+        if (o === e || deepEqual(o, e))
+            continue;
+        const rev = typeof e.meta?.rev === "number" ? e.meta.rev : 0;
+        if (parentOf(o) !== parentOf(e) || orderOf(o) !== orderOf(e))
+            ops.push({ op: "reparent", id, parent: parentOf(e), order: orderOf(e) ?? "", old_parent: parentOf(o), old_order: orderOf(o) ?? null, rev });
+        if (o.name !== e.name && typeof e.name === "string")
+            ops.push({ op: "rename", id, name: e.name, old_name: typeof o.name === "string" ? o.name : null, rev });
+        const set = {};
+        for (const [k, v] of Object.entries(e))
+            if (k !== "parent" && k !== "order" && k !== "name" && k !== "meta" && !deepEqual(o[k], v))
+                set[k] = v;
+        if (Object.keys(set).length)
+            ops.push({ op: "patch", id, set: set, rev });
+    }
+    for (const [id, o] of old)
+        if (!next.has(id))
+            ops.push({ op: "despawn", id, removed: [id], old_parent: parentOf(o), old_order: orderOf(o) ?? null });
+    return ops;
+}
+const list = (v) => (Array.isArray(v) ? v : []);
+/** Writes the lanes of a tick or keyframe into `table`: a lane replaces that lane of the row (made when missing), the others stay. */
+function putLanes(table, f) {
+    const ids = [];
+    // The row's stamp is the newest of its lanes' stamps (the runtime stamps every lane it sends).
+    const lane = (id, stamp, set) => {
+        const r = set(table.get(id) ?? {});
+        if (typeof stamp === "number" && (r.stamp === undefined || stamp > r.stamp))
+            r.stamp = stamp;
+        table.set(id, r);
+        ids.push(id);
+    };
+    for (const p of list(f.poses))
+        lane(p.id, p.stamp, r => ({ ...r, pose: { t: p.t, q: p.q } }));
+    for (const j of list(f.joints))
+        lane(j.id, j.stamp, r => ({ ...r, joints: j.j }));
+    for (const s of list(f.state))
+        lane(s.id, s.stamp, r => ({ ...r, state: s.s }));
+    return ids;
+}
+/** A keyframe as a fresh live table. */
+export function liveTableOf(k) {
+    const t = new Map();
+    for (const e of list(k.upsert))
+        if (typeof e?.id === "string")
+            t.set(e.id, { entity: e });
+    putLanes(t, k);
+    return t;
+}
+/** One tick folded into `table` with the runtime's rules (an upsert replaces the whole row, a lane replaces its lane, a remove drops the row); returns the ids it touched. */
+export function foldLive(table, d) {
+    const ids = [];
+    for (const e of list(d.upsert))
+        if (typeof e?.id === "string") {
+            table.set(e.id, { entity: e });
+            ids.push(e.id);
+        }
+    ids.push(...putLanes(table, d));
+    for (const r of list(d.remove)) {
+        table.delete(r.id);
+        ids.push(r.id);
+    }
+    return ids;
+}
+/** The merged read of one entity: the pose lane replaces `xform.t`/`xform.q` (the rest of the xform stays), the joints lane replaces `joints`, the state lane replaces `state`; nothing merges deeper. */
+export function overlay(entity, row) {
+    if (!row.pose && !row.joints && !row.state)
+        return entity;
+    const out = { ...entity };
+    if (row.pose)
+        out.xform = { ...(isObject(entity.xform) ? entity.xform : {}), t: row.pose.t, q: row.pose.q };
+    if (row.joints)
+        out.joints = row.joints;
+    if (row.state)
+        out.state = row.state;
+    return out;
+}
+/** A live row as the live plane shows it (`SceneEntityLive`): each key present only when the row has it. */
+export function liveValue(row) {
+    const out = {};
+    if (row.entity)
+        out.entity = row.entity;
+    if (row.pose)
+        out.pose = { t: row.pose.t, q: row.pose.q };
+    if (row.joints)
+        out.joints = row.joints;
+    if (row.state)
+        out.state = row.state;
+    if (row.stamp !== undefined)
+        out.stamp = row.stamp;
+    return out;
+}
+/** A live entity equal to the one held keeps its object (an upsert repeated, the periodic keyframe), so a view of it stays quiet. */
+function keepLiveEntities(table, held, ids) {
+    for (const id of ids) {
+        const r = table.get(id), o = held(id);
+        if (r?.entity && o && r.entity !== o)
+            table.set(id, { ...r, entity: replaceEqualDeep(o, r.entity) });
+    }
+}
+/** `id` as the entities show it: its live row over its authored entity, or a live entity's own row. */
+export function mergedOf(authored, live, id) {
+    const row = live.get(id), a = authored.get(id);
+    if (row?.entity)
+        return overlay(row.entity, row);
+    if (a && row)
+        return overlay(a, row);
+    return a;
+}
+/** What the task's reader writes and every handle reads: the scene as this node has it, and the handles' feeds. */
+export class Mirror {
+    state = "detached";
+    /** Why the handle closed (`client`, `connection_lost`). */
+    ended;
+    epoch;
+    version = 0;
+    hash = "";
+    /** An authored diff skipped a version; cleared by the next snapshot. */
+    gap = false;
+    pending = 0;
+    authored = new Map();
+    live = new Map();
+    /** authored ⊕ live: the same object while nothing changed; an unchanged entity keeps its object. */
+    merged = EMPTY;
+    #tree = [];
+    #treeStale = false;
+    #listeners = new Set();
+    #sinks = { changes: new Set(), removals: new Set(), denied: new Set(), states: new Set() };
+    subscribe(l) { this.#listeners.add(l); return () => { this.#listeners.delete(l); }; }
+    #notify() { for (const l of [...this.#listeners]) {
+        try {
+            l();
+        }
+        catch (e) {
+            rethrowLater(e);
+        }
+    } }
+    addSink(kind, s) { this.#sinks[kind].add(s); }
+    removeSink(kind, s) { this.#sinks[kind].delete(s); }
+    /** Every feed of handle `id` ends. */
+    dropHandle(id) {
+        for (const set of Object.values(this.#sinks))
+            for (const s of [...set])
+                if (s.handle === id) {
+                    set.delete(s);
+                    s.end();
+                }
+    }
+    #send(kind, item) { for (const s of [...this.#sinks[kind]])
+        s.deliver(item); }
+    /** The hierarchy now (recomputed only after a change of the ids, a parent or an order; the same object while equal). */
+    tree() {
+        if (this.#treeStale) {
+            this.#tree = replaceEqualDeep(this.#tree, treeOf(this.merged));
+            this.#treeStale = false;
+        }
+        return this.#tree;
+    }
+    #setState(s) {
+        if (this.state === s || this.state === "closed")
+            return;
+        this.state = s;
+        this.#send("states", s);
+    }
+    #emitChanges(ops) { if (ops.length)
+        this.#send("changes", ops); }
+    /** The merged reads of `ids` recomputed. */
+    #refresh(ids) {
+        let merged;
+        for (const id of new Set(ids)) {
+            const prev = this.merged[id];
+            let next = mergedOf(this.authored, this.live, id);
+            if (next && prev)
+                next = replaceEqualDeep(prev, next);
+            if (next === prev)
+                continue;
+            merged ??= { ...this.merged };
+            if (next)
+                merged[id] = next;
+            else
+                delete merged[id];
+            if (!prev || !next || parentOf(prev) !== parentOf(next) || orderOf(prev) !== orderOf(next))
+                this.#treeStale = true;
+        }
+        if (merged)
+            this.merged = merged;
+    }
+    /** Every merged read recomputed. */
+    #rebuild() {
+        const merged = {};
+        for (const id of new Set([...this.authored.keys(), ...this.live.keys()])) {
+            const prev = this.merged[id];
+            const next = mergedOf(this.authored, this.live, id);
+            if (next)
+                merged[id] = prev ? replaceEqualDeep(prev, next) : next;
+        }
+        this.merged = replaceEqualDeep(this.merged, merged);
+        this.#treeStale = true;
+    }
+    /** A snapshot of incarnation `epoch` replaces the authored copy; the change feeds get the net difference. Not yet `attached`: the reader catches up first (`attach`). */
+    applySnapshot(epoch, s) {
+        if (this.state === "closed")
+            return;
+        // An entity equal to the one held keeps its object, so a view of the authored entity stays quiet.
+        const next = new Map(Object.entries(s.entities).map(([id, e]) => [id, replaceEqualDeep(this.authored.get(id), e)]));
+        const ops = netDifference(this.authored, next);
+        this.authored = next;
+        this.version = s.version;
+        this.hash = s.hash;
+        this.epoch = epoch;
+        this.gap = false;
+        this.#rebuild();
+        this.#emitChanges(ops);
+        this.#notify();
+    }
+    /** The reader has applied everything this node held when it bound the incarnation. */
+    attach() { if (this.epoch !== undefined && this.state !== "closed") {
+        this.#setState("attached");
+        this.#notify();
+    } }
+    /** One applied batch: its ops folded into the authored copy; the feeds get them as they came. */
+    applyDiff(d, warn) {
+        if (this.epoch === undefined || this.state === "closed")
+            return;
+        if (d.version !== this.version + 1) {
+            warn(`scene: diff out of sequence (have ${this.version}, got ${d.version}); not synced until the next snapshot`);
+            this.gap = true;
+        }
+        const touched = [];
+        for (const op of d.ops)
+            touched.push(...foldAuthored(this.authored, op, d.t, d.by ?? null));
+        this.version = d.version;
+        this.hash = d.hash;
+        this.#refresh(touched);
+        this.#emitChanges(d.ops);
+        this.#notify();
+    }
+    /** A keyframe replaces the live table. */
+    applyKeyframe(k) {
+        if (this.state === "closed")
+            return;
+        const table = liveTableOf(k);
+        const old = this.live;
+        keepLiveEntities(table, id => old.get(id)?.entity, table.keys());
+        const ids = [...this.live.keys(), ...table.keys()];
+        this.live = table;
+        this.#refresh(ids);
+        this.#notify();
+    }
+    /** One tick folded into the live table; its removals go to the feeds. */
+    applyLiveTick(d) {
+        if (this.state === "closed")
+            return;
+        const held = new Map(list(d.upsert).map(e => [e?.id, this.live.get(e?.id)?.entity]));
+        const ids = foldLive(this.live, d);
+        keepLiveEntities(this.live, id => held.get(id), held.keys());
+        this.#refresh(ids);
+        const removed = list(d.remove);
+        if (removed.length)
+            this.#send("removals", removed);
+        this.#notify();
+    }
+    /** Ids of this node's live rows the runtime dropped. */
+    denied(ids) { if (this.state !== "closed")
+        this.#send("denied", ids); }
+    setPending(n) { this.pending = n; this.#notify(); }
+    /** No incarnation: the copy empties (the change feeds see the despawns), `detached`. */
+    detach() {
+        if (this.state === "closed")
+            return;
+        const ops = netDifference(this.authored, new Map());
+        this.authored = new Map();
+        this.live = new Map();
+        this.merged = EMPTY;
+        this.#treeStale = true;
+        this.epoch = undefined;
+        this.version = 0;
+        this.hash = "";
+        this.gap = false;
+        this.#setState("detached");
+        this.#emitChanges(ops);
+        this.#notify();
+    }
+    /** The end: emptied, `closed` (`reason` recorded), every feed ended. */
+    close(reason) {
+        if (this.state === "closed")
+            return;
+        this.detach();
+        this.#setState("closed");
+        this.ended = reason;
+        for (const set of Object.values(this.#sinks)) {
+            for (const s of set)
+                s.end();
+            set.clear();
+        }
+        this.#notify();
+    }
+}
+// --------------------------------------------------------------------------------------- views
+/**
+ * A value of the scene (`SceneView`): `read` picks it from the mirror (the same object until it
+ * changes). It follows the mirror only while someone listens (`subscribe`, a pending `changed()`),
+ * and while it does it is in `active`, so the handle's close can end it.
+ */
+class MirrorView {
+    mirror;
+    read;
+    active;
+    ended;
+    #listeners = new Set();
+    #waiting = [];
+    #unmirror;
+    #last;
+    constructor(mirror, read, active, ended) {
+        this.mirror = mirror;
+        this.read = read;
+        this.active = active;
+        this.ended = ended;
+    }
+    get() { return this.read(); }
+    subscribe(listener) {
+        if (this.ended())
+            return () => { };
+        this.#listeners.add(listener);
+        this.#follow();
+        return () => { this.#listeners.delete(listener); this.#unfollow(); };
+    }
+    changed() {
+        if (this.ended())
+            return Promise.resolve(this.read());
+        const d = deferred();
+        this.#waiting.push(d);
+        this.#follow();
+        return d.promise;
+    }
+    #follow() {
+        if (this.#unmirror)
+            return;
+        this.#last = this.read();
+        this.#unmirror = this.mirror.subscribe(() => this.#update());
+        this.active.add(this);
+    }
+    #unfollow() {
+        if (!this.#unmirror || this.#listeners.size || this.#waiting.length)
+            return;
+        this.#unmirror();
+        this.#unmirror = undefined;
+        this.active.delete(this);
+    }
+    #update() {
+        let v;
+        try {
+            v = this.read();
+        }
+        catch (e) {
+            rethrowLater(e);
+            return;
+        }
+        if (v === this.#last)
+            return;
+        this.#last = v;
+        for (const l of [...this.#listeners]) {
+            try {
+                l();
+            }
+            catch (e) {
+                rethrowLater(e);
+            }
+        }
+        for (const d of this.#waiting.splice(0))
+            d.resolve(v);
+        this.#unfollow();
+    }
+    /** The handle closed: a pending `changed()` resolves with the value now; listeners are dropped. */
+    end() {
+        let v;
+        try {
+            v = this.read();
+        }
+        catch {
+            v = this.#last;
+        }
+        for (const d of this.#waiting.splice(0))
+            d.resolve(v);
+        this.#listeners.clear();
+        this.#unfollow();
+    }
+}
+function openLiveWriter(s) {
+    const bc = s.createBroadcast(`${s.prefix}/scene/live`);
+    // Kept as long as a call track keeps its groups (the runtime's follower reads every batch).
+    const track = bc.createTrack(LIVE_TRACK, { priority: moqPriority(3), maxAge: Moq.Time.Milli(CALL_GROUP_MAX_AGE_MS), timescale: Moq.Time.Timescale.MICRO });
+    bc.announce();
+    return { session: s, bc, stream: new StreamWriter(track), seq: 0 };
+}
+function closeLiveWriter(w) {
+    if (!w)
+        return;
+    w.stream.close();
+    try {
+        w.bc.close();
+    }
+    catch { /* closed */ }
+}
+/** The node's scene: what every handle shares with the task. */
+export class Scene {
+    node;
+    warn;
+    mirror = new Mirror();
+    mailbox = new AsyncQueue(Infinity);
+    exited = deferred();
+    /** Handles neither closed nor dropped; the one that brings it to 0 tells the task `close`. */
+    handles = 0;
+    nextHandle = 0;
+    /** The live writer of the current session, made on the first `live()`. */
+    writer;
+    detachedDrops = 0;
+    constructor(node, warn) {
+        this.node = node;
+        this.warn = warn;
+    }
+    post(e) { return this.mailbox.push(e); }
+    request(make) {
+        const reply = deferred();
+        if (!this.post(make(reply)))
+            return Promise.reject(closedError(this.mirror.ended ?? ENDED_CLIENT));
+        return reply.promise;
+    }
+}
+const detachedError = () => new SynapseError("project_inactive", "the scene is detached: no incarnation of the active project's scene is bound");
+/** What a closed handle's verbs fail with: `not_connected`, the message saying why. */
+function closedError(reason) {
+    return new SynapseError("not_connected", reason === ENDED_CONNECTION_LOST ? "the node ended" : "the scene handle is closed");
+}
+const asError = (e) => (e instanceof SynapseError ? e : new SynapseError("internal", String(e)));
+export function startScene(scene, registry) { void run(scene, registry); }
+async function run(scene, registry) {
+    const { mirror, node } = scene;
+    let session;
+    let phase = { kind: "idle" };
+    const ph = () => phase;
+    let attempts = 0;
+    /** The incarnation that last ended: not bound again (its announcement may still be seen). */
+    let endedEpoch;
+    /** The session's project state as last read. */
+    let project;
+    let unwatchProject;
+    const joining = [];
+    let waiters = [];
+    const inactive = () => project !== undefined && project.active === null;
+    const answerJoins = () => { for (const j of joining.splice(0))
+        j.resolve(); };
+    const failWaiters = (e) => { for (const w of waiters.splice(0))
+        w.reply.reject(e()); };
+    const stopPhase = () => {
+        if (phase.kind === "following")
+            phase.stop.abort();
+        else if (phase.kind === "paced")
+            clearTimeout(phase.timer);
+        phase = { kind: "idle" };
+    };
+    /** Follows the announcements on the task's session, from `idle`. */
+    const follow = () => {
+        if (phase.kind !== "idle" || mirror.state === "closed" || !session)
+            return;
+        const s = session;
+        let announced;
+        try {
+            announced = s.sub.announced(Moq.Path.Pattern.parse(`${SCENE_BASE}/*`));
+        }
+        catch (e) {
+            scene.warn(`scene: announcements not followed: ${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        attempts += 1;
+        const attempt = attempts;
+        const stop = new AbortController();
+        phase = { kind: "following", attempt, stop };
+        void followIncarnation(scene, s, announced, endedEpoch, stop.signal).then(r => scene.post({ kind: "followEnded", attempt, epoch: r.epoch, reason: r.reason }));
+    };
+    /** The incarnation is let go: the mirror empties, writes waiting to show fail, followed again after `paceMs`. */
+    const again = (paceMs) => {
+        failWaiters(() => new SynapseError("conflict", "the scene's incarnation ended before the write showed"));
+        stopPhase();
+        mirror.detach();
+        const a = ++attempts;
+        phase = { kind: "paced", timer: setTimeout(() => scene.post({ kind: "paced", attempt: a }), paceMs) };
+    };
+    /** The node's session is now `s` (or none): what was bound on the previous one is over; the announcements are followed on `s`. */
+    const sessionChanged = (s) => {
+        session = s;
+        stopPhase();
+        failWaiters(() => new SynapseError("connection_lost", "the session ended before the write showed in the scene"));
+        mirror.detach();
+        closeLiveWriter(scene.writer);
+        scene.writer = undefined;
+        unwatchProject?.();
+        unwatchProject = undefined;
+        project = s?.project.get();
+        if (s)
+            unwatchProject = s.project.subscribe(p => { scene.post({ kind: "project", snapshot: p }); });
+        if (inactive())
+            answerJoins();
+        follow();
+    };
+    const applied = (epoch, version) => {
+        const reached = waiters.filter(w => w.epoch === epoch && w.version <= version);
+        waiters = waiters.filter(w => !reached.includes(w));
+        for (const w of reached)
+            w.reply.resolve();
+        if (mirror.state === "attached")
+            answerJoins();
+    };
+    const join = (reply) => { if (mirror.state === "attached" || inactive())
+        reply.resolve();
+    else
+        joining.push(reply); };
+    /** A batch: sent naming the bound incarnation's epoch. */
+    const apply = (ops, base, reply) => {
+        if (mirror.state === "closed") {
+            reply.reject(closedError(mirror.ended ?? ENDED_CLIENT));
+            return;
+        }
+        const epoch = mirror.epoch;
+        if (mirror.state !== "attached" || epoch === undefined || !session) {
+            reply.reject(detachedError());
+            return;
+        }
+        const args = { epoch, ops };
+        if (base !== undefined)
+            args.base = base;
+        let call;
+        try {
+            call = startOn(node, session, "synapse/scene/apply", args, {});
+        }
+        catch (e) {
+            reply.reject(asError(e));
+            return;
+        }
+        mirror.setPending(mirror.pending + 1);
+        const done = (result) => {
+            // The task is gone: the caller is answered from here (the runtime's answer, unseen).
+            if (!scene.post({ kind: "applyDone", epoch, result, reply })) {
+                if ("ok" in result)
+                    reply.resolve();
+                else
+                    reply.reject(result.err);
+            }
+        };
+        void call.result.then(v => done({ ok: v }), (e) => done({ err: asError(e) }));
+    };
+    /** The runtime answered a batch of `epoch`: applied, the caller is answered once the mirror shows it; refused, at once — and a stale epoch lets go of the incarnation read. */
+    const applyDone = (epoch, result, reply) => {
+        mirror.setPending(mirror.pending - 1);
+        if ("ok" in result) {
+            const v = result.ok?.version;
+            const version = typeof v === "number" ? v : typeof v === "bigint" ? Number(v) : undefined;
+            if (version === undefined) {
+                reply.reject(new SynapseError("internal", "scene apply reply not understood"));
+                return;
+            }
+            if (mirror.state === "closed") {
+                reply.reject(closedError(mirror.ended ?? ENDED_CLIENT));
+                return;
+            }
+            const here = mirror.state === "attached" && mirror.epoch === epoch;
+            if (here && mirror.version >= version)
+                reply.resolve();
+            else if (here)
+                waiters.push({ epoch, version, reply });
+            else
+                reply.reject(new SynapseError("conflict", "the scene's incarnation changed before the write showed"));
+            return;
+        }
+        const e = result.err;
+        const live = e.data?.live_epoch;
+        if (e.code === "conflict" && typeof live === "string" && live !== epoch && mirror.epoch === epoch) {
+            endedEpoch = epoch;
+            again(REFOLLOW_PACE_MS);
+        }
+        reply.reject(e);
+    };
+    /** A node notice: a live denial (`not_owner` with `data.ids`) goes to the denial feeds. */
+    const notice = (b) => {
+        if (b.code !== "not_owner")
+            return;
+        const ids = b.data?.ids;
+        if (Array.isArray(ids))
+            mirror.denied(ids.filter((x) => typeof x === "string"));
+    };
+    const { session: first, unmonitor } = node.monitor((e) => scene.post(e.kind === "started" ? { kind: "session", session: e.session } : e.kind === "ended" ? { kind: "sessionEnded" } : { kind: "nodeEnded" }));
+    const onNotice = (b) => { scene.post({ kind: "notice", body: b }); };
+    node.notices.add(onNotice);
+    let reason = ENDED_CLIENT;
+    try {
+        sessionChanged(first);
+        loop: for (;;) {
+            const ev = await scene.mailbox.next();
+            if (!ev)
+                break;
+            switch (ev.kind) {
+                case "session":
+                    sessionChanged(ev.session);
+                    break;
+                case "sessionEnded":
+                    sessionChanged(undefined);
+                    break;
+                case "nodeEnded":
+                    reason = ENDED_CONNECTION_LOST;
+                    break loop;
+                case "applied":
+                    applied(ev.epoch, ev.version);
+                    break;
+                case "followEnded": {
+                    {
+                        const p = ph();
+                        if (p.kind !== "following" || p.attempt !== ev.attempt)
+                            break;
+                    }
+                    phase = { kind: "idle" };
+                    // An incarnation that ended with its final frame is not bound again.
+                    if (ev.epoch !== undefined && ev.reason !== undefined)
+                        endedEpoch = ev.epoch;
+                    again(REFOLLOW_PACE_MS);
+                    break;
+                }
+                case "join":
+                    join(ev.reply);
+                    break;
+                case "apply":
+                    apply(ev.ops, ev.base, ev.reply);
+                    break;
+                case "applyDone":
+                    applyDone(ev.epoch, ev.result, ev.reply);
+                    break;
+                case "project":
+                    project = ev.snapshot;
+                    if (inactive())
+                        answerJoins();
+                    break;
+                case "notice":
+                    notice(ev.body);
+                    break;
+                case "paced":
+                    if (ph().kind === "paced" && ev.attempt === attempts) {
+                        phase = { kind: "idle" };
+                        follow();
+                    }
+                    break;
+                case "close": break loop;
+            }
+        }
+    }
+    finally {
+        unmonitor();
+        node.notices.delete(onNotice);
+        unwatchProject?.();
+        stopPhase();
+        mirror.close(reason);
+        closeLiveWriter(scene.writer);
+        scene.writer = undefined;
+        for (const j of joining.splice(0))
+            j.reject(closedError(reason));
+        failWaiters(() => closedError(reason));
+        // No new work is taken (a batch finds the handle closed), but every batch already on the wire is
+        // answered to its caller with what became of it before the task ends.
+        while (mirror.pending > 0) {
+            const ev = await scene.mailbox.next();
+            if (!ev)
+                break;
+            if (ev.kind === "applyDone")
+                applyDone(ev.epoch, ev.result, ev.reply);
+            else if (ev.kind === "apply" || ev.kind === "join")
+                ev.reply.reject(closedError(reason));
+        }
+        void scene.mailbox.close();
+        for (let ev = scene.mailbox.tryNext(); ev; ev = scene.mailbox.tryNext())
+            if (ev.kind === "apply" || ev.kind === "join" || ev.kind === "applyDone")
+                ev.reply.reject(closedError(reason));
+        if (registry.current === scene)
+            registry.current = undefined;
+        scene.exited.resolve();
+    }
+}
+/** The epoch of an announced prefix (`runtime/scene/@<epoch>`). */
+function announcedEpoch(prefix) {
+    if (!prefix.startsWith(`${SCENE_BASE}/@`))
+        return undefined;
+    const e = prefix.slice(SCENE_BASE.length + 2);
+    return e && !e.includes("/") ? e : undefined;
+}
+/** One track being read: its subscriber and the group it is in (both closed when the reading stops). */
+class TrackReading {
+    sub;
+    group;
+    constructor(sub) {
+        this.sub = sub;
+    }
+    close() { try {
+        this.group?.close();
+    }
+    catch { /* closed */ } try {
+        this.sub.close();
+    }
+    catch { /* closed */ } }
+    /** The first group and its first frame's payload. */
+    async first() {
+        try {
+            const g = await this.sub.recvGroup();
+            if (!g)
+                return undefined;
+            this.group = g;
+            return (await g.readFrame())?.payload;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Reads, without waiting, every frame already held, from the current group on (a newer group that is ready replaces the current one); `on` returns `false` to stop. */
+    drain(on) {
+        for (;;) {
+            const g = this.group;
+            if (g) {
+                let f;
+                try {
+                    f = g.tryReadFrame();
+                }
+                catch {
+                    f = undefined;
+                    this.group = undefined;
+                }
+                if (f) {
+                    if (on(f.payload))
+                        continue;
+                    return;
+                }
+                if (this.group && g.done)
+                    this.group = undefined;
+            }
+            let next;
+            try {
+                next = this.sub.tryRecvGroup();
+            }
+            catch {
+                next = undefined;
+            }
+            if (!next)
+                return;
+            try {
+                this.group?.close();
+            }
+            catch { /* closed */ }
+            this.group = next;
+        }
+    }
+    /** Reads frame by frame as frames come, from the current group on, until `on` returns `false` or the track ends. */
+    async readOn(on) {
+        try {
+            for (;;) {
+                if (!this.group) {
+                    this.group = await this.sub.recvGroup();
+                    if (!this.group)
+                        return;
+                }
+                const g = this.group;
+                for (;;) {
+                    let f;
+                    try {
+                        f = await g.readFrame();
+                    }
+                    catch {
+                        break;
+                    }
+                    if (!f)
+                        break;
+                    if (!on(f.payload))
+                        return;
+                }
+                this.group = undefined;
+            }
+        }
+        catch { /* the track went */ }
+    }
+}
+/** A frame's header flags and decoded body, or `undefined` (warned) when it does not decode. */
+function decodeFrame(p, warn, what) {
+    try {
+        const { header, hlen } = decodeHeader(p);
+        return { flags: header.flags, body: decodeBody(p.subarray(hlen)) };
+    }
+    catch {
+        warn(`scene: ${what} frame not decodable`);
+        return undefined;
+    }
+}
+/**
+ * Binds the first incarnation announced (other than `skip`, the one that last ended) and reads both
+ * its tracks into the mirror, telling the task of each authored frame applied; returns once the
+ * `authored` track ends (its final frame, or the track going). Once `signal` aborts it writes nothing more.
+ */
+async function followIncarnation(scene, session, announced, skip, signal) {
+    const { mirror, warn } = scene;
+    const none = { epoch: undefined, reason: undefined };
+    const closers = [announced];
+    const closeAll = () => { for (const c of closers) {
+        try {
+            c.close();
+        }
+        catch { /* closed */ }
+    } };
+    signal.addEventListener("abort", closeAll, { once: true });
+    try {
+        let epoch;
+        for (;;) {
+            const u = await announced.next();
+            if (!u || signal.aborted)
+                return none;
+            if (u.kind === "retracted")
+                continue;
+            const e = announcedEpoch(String(u.prefix));
+            if (e !== undefined && e !== skip) {
+                epoch = e;
+                break;
+            }
+        }
+        const at = epoch;
+        // Resolving the broadcast races an end of this epoch already on the cursor.
+        const req = session.request(`${SCENE_BASE}/@${at}`);
+        closers.push(req);
+        const retracted = (async () => { for (;;) {
+            const u = await announced.next();
+            if (!u)
+                return false;
+            if (u.kind === "retracted" && announcedEpoch(String(u.prefix)) === at)
+                return true;
+        } })();
+        let bc;
+        try {
+            const r = await Promise.race([waitActive(req, 10_000, signal).then(b => ({ bc: b })), retracted.then(gone => ({ gone }))]);
+            if ("gone" in r)
+                return r.gone ? { epoch: at, reason: "ended" } : none;
+            bc = r.bc;
+        }
+        catch {
+            return none;
+        }
+        announced.close();
+        closers.push(bc);
+        const authored = new TrackReading(bc.track(AUTHORED_TRACK).subscribe(latestSubscription(moqPriority(1))));
+        const live = new TrackReading(bc.track(LIVE_TRACK).subscribe(latestSubscription(moqPriority(1))));
+        closers.push(authored, live);
+        if (signal.aborted)
+            return none;
+        let end;
+        const ended = () => ({ epoch: at, reason: end });
+        const onAuthored = (p) => {
+            if (signal.aborted)
+                return false;
+            const f = decodeFrame(p, warn, "authored");
+            if (!f)
+                return true;
+            if (f.flags & FLAGS.END) {
+                const r = f.body?.reason;
+                end = typeof r === "string" ? r : "ended";
+                return false;
+            }
+            let version;
+            if (f.flags & FLAGS.KEY) {
+                const s = f.body;
+                if (!s || typeof s.version !== "number" || !isObject(s.entities)) {
+                    warn("scene: snapshot not understood");
+                    return true;
+                }
+                mirror.applySnapshot(at, s);
+                version = s.version;
+            }
+            else if (f.flags & FLAGS.DELTA) {
+                const d = f.body;
+                if (!d || typeof d.version !== "number" || !Array.isArray(d.ops)) {
+                    warn("scene: diff not understood");
+                    return true;
+                }
+                mirror.applyDiff(d, warn);
+                version = d.version;
+            }
+            else
+                return true;
+            scene.post({ kind: "applied", epoch: at, version });
+            return true;
+        };
+        const onLive = (p) => {
+            if (signal.aborted)
+                return false;
+            const f = decodeFrame(p, warn, "live");
+            if (!f || !isObject(f.body))
+                return true;
+            if (f.flags & FLAGS.KEY)
+                mirror.applyKeyframe(f.body);
+            else if (f.flags & FLAGS.DELTA)
+                mirror.applyLiveTick(f.body);
+            return true;
+        };
+        // Catching up: the first frame of each track (the open group's snapshot, the whole live set),
+        // then every frame this node already holds on either, read without waiting; only then is the
+        // handle `attached` (its version is the scene's as far as this node has it).
+        const a0 = await authored.first();
+        if (signal.aborted)
+            return none;
+        if (!a0)
+            return ended();
+        if (!onAuthored(a0))
+            return ended();
+        const l0 = await live.first();
+        if (signal.aborted)
+            return none;
+        if (!l0)
+            return ended();
+        onLive(l0);
+        authored.drain(onAuthored);
+        if (end !== undefined)
+            return ended();
+        live.drain(onLive);
+        if (signal.aborted)
+            return none;
+        mirror.attach();
+        scene.post({ kind: "applied", epoch: at, version: mirror.version });
+        // Then frame by frame as they come. The live track's end is the incarnation's: the authored track says how it ended.
+        void live.readOn(onLive);
+        await authored.readOn(onAuthored);
+        return ended();
+    }
+    catch {
+        return none;
+    }
+    finally {
+        signal.removeEventListener("abort", closeAll);
+        closeAll();
+    }
+}
+// ------------------------------------------------------------------------------------- handle
+/** Collects the items of one feed for an async iterator: a feed `SCENE_FEED_CAP` items behind is ended (what it holds is still read). */
+function queueSink(handle, onEnd) {
+    const q = new AsyncQueue(Infinity);
+    const sink = {
+        handle,
+        deliver: item => { if (q.size >= SCENE_FEED_CAP) {
+            onEnd();
+            void q.close();
+            return;
+        } q.push(item); },
+        end: () => { void q.close(); },
+    };
+    return { sink, q };
+}
+async function* iterate(q, leave) {
+    try {
+        for await (const item of q)
+            yield item;
+    }
+    finally {
+        leave();
+        void q.close();
+    }
+}
+/** The application's handle on the node's scene: the last one closed ends the task. */
+export class SceneHandleImpl {
+    scene;
+    #closed = false;
+    #id;
+    /** The views of this handle that follow the mirror now. */
+    #views = new Set();
+    #unsubscribes = new Set();
+    constructor(scene) {
+        this.scene = scene;
+        scene.handles++;
+        this.#id = scene.nextHandle++;
+    }
+    get entities() { return this.scene.mirror.merged; }
+    entity(id, opts = {}) {
+        const mirror = this.scene.mirror;
+        // The entity as declared (the authored one, or a live entity's upsert row): its object changes
+        // only when an authored batch or a new upsert changes it, never on a lane tick.
+        if (opts.plane === "authored")
+            return this.#view(() => mirror.authored.get(id) ?? mirror.live.get(id)?.entity);
+        if (opts.plane === "live") {
+            // The live row, rebuilt only when the row object changes and kept the same object while equal.
+            let from;
+            let last;
+            return this.#view(() => {
+                const row = mirror.live.get(id);
+                if (row === from)
+                    return last;
+                from = row;
+                last = row ? replaceEqualDeep(last, liveValue(row)) : undefined;
+                return last;
+            });
+        }
+        return this.#view(() => mirror.merged[id]);
+    }
+    tree() { return this.#view(() => this.scene.mirror.tree()); }
+    query(where) {
+        let from;
+        let last = [];
+        return this.#view(() => {
+            const m = this.scene.mirror.merged;
+            if (m === from)
+                return last;
+            from = m;
+            const ids = Object.keys(m).filter(id => where(m[id])).sort();
+            last = replaceEqualDeep(last, ids.map(id => m[id]));
+            return last;
+        });
+    }
+    #view(read) { return new MirrorView(this.scene.mirror, read, this.#views, () => this.#closed || this.scene.mirror.state === "closed"); }
+    get status() {
+        const m = this.scene.mirror;
+        const state = this.#closed ? "closed" : m.state;
+        return { state, synced: state === "attached" && this.scene.node.isConnected && m.pending === 0 && !m.gap, pending: m.pending, version: m.version, hash: m.hash, detachedDrops: this.scene.detachedDrops };
+    }
+    // ---- feeds
+    #feed(kind, cb) {
+        const m = this.scene.mirror;
+        const open = !this.#closed && m.state !== "closed";
+        if (cb) {
+            const sink = { handle: this.#id, deliver: item => { try {
+                    cb(item);
+                }
+                catch (e) {
+                    rethrowLater(e);
+                } }, end: () => { } };
+            if (open)
+                m.addSink(kind, sink);
+            return () => m.removeSink(kind, sink);
+        }
+        const { sink, q } = queueSink(this.#id, () => m.removeSink(kind, sink));
+        if (open)
+            m.addSink(kind, sink);
+        else
+            void q.close();
+        return iterate(q, () => m.removeSink(kind, sink));
+    }
+    watchChanges(cb) { return this.#feed("changes", cb); }
+    watchLiveRemovals(cb) { return this.#feed("removals", cb); }
+    watchLiveDenied(cb) { return this.#feed("denied", cb); }
+    watchState(cb) { return this.#feed("states", cb); }
+    // ---- author: every verb is one `apply`
+    async apply(ops, base) {
+        if (this.#closed)
+            throw closedError(ENDED_CLIENT);
+        if (this.scene.mirror.state === "detached")
+            throw detachedError();
+        await this.scene.request(reply => ({ kind: "apply", ops, base, reply }));
+    }
+    async txn(build) {
+        const t = new Txn();
+        build(t);
+        await this.apply([...t.ops]);
+    }
+    async spawn(kind, opts) {
+        let id = "";
+        await this.txn(t => { id = t.spawn(kind, opts); });
+        return id;
+    }
+    patch(id, set) { return this.txn(t => t.patch(id, set)); }
+    rename(id, name) { return this.txn(t => t.rename(id, name)); }
+    reparent(id, parent, place) { return this.txn(t => t.reparent(id, parent, place)); }
+    despawn(id, opts) { return this.txn(t => t.despawn(id, opts)); }
+    setLocked(id, locked) { return this.txn(t => t.setLocked(id, locked)); }
+    // ---- live
+    /**
+     * Writes one live batch on this node's live track (made on the first call of each session); returns
+     * at once, like `publish`. The runtime stamps the rows and owns the outcome: an id another writer owns
+     * comes back on `watchLiveDenied`, a malformed batch as a node notice. Not attached: dropped and counted.
+     */
+    live(batch) {
+        if (this.#closed)
+            throw closedError(ENDED_CLIENT);
+        const scene = this.scene;
+        const s = scene.node.currentSession();
+        if (scene.mirror.state !== "attached" || !s) {
+            scene.detachedDrops++;
+            return;
+        }
+        const body = {};
+        if (batch.upsert?.length)
+            body.upsert = batch.upsert;
+        if (batch.poses?.length)
+            body.poses = batch.poses.map(p => ({ id: p.id, t: p.t, q: p.q }));
+        if (batch.joints?.length)
+            body.joints = batch.joints.map(r => ({ id: r.id, j: r.j }));
+        if (batch.state?.length)
+            body.state = batch.state.map(r => ({ id: r.id, s: r.s }));
+        if (batch.remove?.length)
+            body.remove = batch.remove;
+        if (batch.lifetimeMs !== undefined)
+            body.lifetime_ms = batch.lifetimeMs;
+        let bytes;
+        try {
+            bytes = encodeBody(body);
+        }
+        catch (e) {
+            throw new SynapseError("invalid_input", `live batch not encodable: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (bytes.length > MAX_FRAME_BYTES)
+            throw frameTooLarge("scene live batch", bytes.length);
+        let w = scene.writer;
+        if (!w || w.session !== s) {
+            closeLiveWriter(w);
+            try {
+                w = scene.writer = openLiveWriter(s);
+            }
+            catch (e) {
+                scene.writer = undefined;
+                throw new SynapseError("internal", `scene live track not made: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        const header = { flags: 0, type: TYPES.PUB, seq: w.seq, tUs: nowUs() };
+        w.seq = (w.seq + 1) >>> 0;
+        try {
+            w.stream.write(header, bytes);
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: e instanceof Error ? e.message : String(e), source: "transport", cause: e });
+        }
+    }
+    /** The framework bridge (React's hooks): called on every change of the entities or the status. */
+    subscribe(listener) {
+        if (this.#closed)
+            return () => { };
+        const un = this.scene.mirror.subscribe(listener);
+        this.#unsubscribes.add(un);
+        return () => { un(); this.#unsubscribes.delete(un); };
+    }
+    /** Closes the handle: its verbs fail, its views and feeds end, its status says `closed`; the node's other scene handles go on. The last one ends the task, which ends this node's live writer (the runtime retracts its lifetimed rows and live entities: `writer_gone`). Idempotent. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.scene.mirror.dropHandle(this.#id);
+        for (const v of [...this.#views])
+            v.end();
+        for (const un of this.#unsubscribes)
+            un();
+        this.#unsubscribes.clear();
+        if (--this.scene.handles === 0)
+            this.scene.post({ kind: "close" });
+    }
+    async [Symbol.asyncDispose]() { this.close(); }
+}
+/**
+ * The active project's scene (one per project; one task per node, shared by every handle). Resolves
+ * once the handle is attached, or at once `detached` when the runtime says no project is active; the
+ * handle then follows the incarnations as they come and go. `not_connected` without a session.
+ */
+export async function openScene(node, registry, warn) {
+    if (!node.currentSession())
+        throw new SynapseError("not_connected");
+    let scene;
+    let h;
+    for (;;) {
+        const live = registry.current;
+        if (live) {
+            if (live.handles === 0 || live.mirror.state === "closed") {
+                await live.exited.promise;
+                continue;
+            }
+            scene = live;
+            h = new SceneHandleImpl(live);
+            break;
+        }
+        scene = new Scene(node, warn);
+        registry.current = scene;
+        h = new SceneHandleImpl(scene);
+        startScene(scene, registry);
+        break;
+    }
+    try {
+        await scene.request(reply => ({ kind: "join", reply }));
+    }
+    catch (e) {
+        h.close();
+        throw e;
+    }
+    return h;
+}