@synapse-sdk/client 0.3.3 → 0.3.4

package/dist/scene.js

@@ -21,13 +21,25 @@
 // - `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`);
+// - `upsert` / `remove` / `claim` / `claimDone` / `reclaim`: this node's live claims (PLAN v0.31: decisions are calls,
+//   data is streams): `live.upsert` and `live.remove` are the calls `synapse/scene/live/upsert` and
+//   `synapse/scene/live/remove`; a lane write for an id this node has not claimed in the bound incarnation asks the
+//   claim once (the override of an entity of the scene); the runtime's answers; a refused live entity due again;
 // - `close`: the last open handle left.
 //
+// The claims are this node's own intent (id → the claim's args), never world state: on every attach to an incarnation
+// (a new session, a project switch, a restarted scene owner) the live entities among them are claimed again with the
+// same ids; an override is claimed again by its next lane write. A refused re-claim is asked again, paced, with a
+// warning (the store's re-open rule and constants: `refusalPaceMs`). Lane rows for an id not claimed in the bound
+// incarnation are parked (latest per lane) while the claim is asked, sent once granted, dropped and counted
+// (`status.get().unclaimedDrops`) when refused. Nothing here reads the mirror to decide what to send: the mirror is a
+// read cache. The Rust client's `scene.rs` is the reference; this file behaves as it does.
+//
 // 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`.
+// detached the entities are empty, every author verb fails `project_inactive` at once and a live
+// write 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
@@ -42,9 +54,9 @@
 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 { REFOLLOW_PACE_MS, isTransient, refusalPaceMs } from "./channel.js";
 import { CALL_GROUP_MAX_AGE_MS, StreamWriter, frameTooLarge, latestSubscription, waitActive } from "./session.js";
-import { AsyncQueue, deferred, replaceEqualDeep } from "./util.js";
+import { AsyncQueue, StatusCell, deferred, replaceEqualDeep, rethrowLater, watchState } from "./util.js";
 /** Where the runtime announces the scene's incarnations: `runtime/scene/@<epoch>`. */
 const SCENE_BASE = "runtime/scene";
 const AUTHORED_TRACK = "authored";
@@ -60,12 +72,22 @@ 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({});
+/** What a closed handle's `tree()` and `query()` read: one object each, so a reader that compares by reference stays quiet. */
+const EMPTY_TREE = Object.freeze([]);
+const EMPTY_LIST = 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; }); };
+/** The id `x` names: a string, or a view this SDK made (`EntityView`); anything else (`{ id }` included) is `invalid_input` naming `arg`. */
+const idOf = (x, arg = "entity") => {
+    if (typeof x === "string")
+        return x;
+    if (x instanceof EntityView)
+        return x.id;
+    throw new SynapseError("invalid_input", `scene: ${arg} is an id or an entity view (scene.entity, upsert), not ${x === null ? "null" : typeof x}`);
+};
 // ------------------------------------------------------------------------------------- helpers
 const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 const RAND_BITS = 74n;
@@ -227,17 +249,18 @@ export class Txn {
     #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. */
+    /** Spawns an entity of `kind` under `opts.parent` (default the world root) with the components given (`layer` `authored` when not given, else `calibration`; a live entity is not spawned here, it comes from `scene.live.upsert`); 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 };
+        const entity = { ...components, id, kind, parent: parent == null ? null : idOf(parent, "parent") };
         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) {
+    /** Sets components of the entity (one level deep: an object merges into an object). */
+    patch(entity, set) {
+        const id = idOf(entity);
         // 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);
@@ -248,7 +271,8 @@ export class Txn {
         }
         this.#ops.push({ op: "patch", id, set });
     }
-    rename(id, name) {
+    rename(entity, name) {
+        const id = idOf(entity);
         const i = this.#spawnIndex(id);
         if (i >= 0) {
             const op = this.#ops[i];
@@ -257,17 +281,18 @@ export class Txn {
         }
         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 };
+    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
+    reparent(entity, parent, place) {
+        const op = { op: "reparent", id: idOf(entity), parent: parent === null ? null : idOf(parent, "parent") };
         if (place && "before" in place)
-            op.before = place.before;
+            op.before = idOf(place.before, "before");
         else if (place && "after" in place)
-            op.after = place.after;
+            op.after = idOf(place.after, "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 = {}) {
+    /** Despawns the entity (`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(entity, opts = {}) {
+        const id = idOf(entity);
         const cascade = opts.cascade ?? false;
         if (this.#spawnIndex(id) >= 0 && (cascade || this.#spawnedUnder(id).length === 0)) {
             this.#cancel(id);
@@ -275,8 +300,8 @@ export class Txn {
         }
         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 } }); }
+    /** Locks or unlocks the entity (a flags-only patch, which a lock lets through). */
+    setLocked(entity, locked) { this.patch(entity, { 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);
@@ -313,7 +338,8 @@ export function foldAuthored(authored, op, t, by) {
             const e = authored.get(op.id);
             if (!e)
                 return [];
-            authored.set(op.id, stamped(mergeSet(e, op.set), op.rev));
+            // An unchanged component keeps its object, so a view of the authored entity stays quiet on it.
+            authored.set(op.id, replaceEqualDeep(e, stamped(mergeSet(e, op.set), op.rev)));
             return [op.id];
         }
         case "reparent": {
@@ -336,34 +362,6 @@ export function foldAuthored(authored, op, t, by) {
     }
     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) {
@@ -393,6 +391,20 @@ export function liveTableOf(k) {
     putLanes(t, k);
     return t;
 }
+/** The authored or calibration entity named `name` (live overrides never count). */
+export function authoredNamed(authored, name) {
+    for (const e of authored.values())
+        if (e.name === name)
+            return e;
+    return undefined;
+}
+/** The id of the live entity named `name` (a lane-only row carries no name). */
+export function liveNamed(live, name) {
+    for (const [id, r] of live)
+        if (r.entity?.name === name)
+            return id;
+    return undefined;
+}
 /** 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 = [];
@@ -471,7 +483,7 @@ export class Mirror {
     #tree = [];
     #treeStale = false;
     #listeners = new Set();
-    #sinks = { changes: new Set(), removals: new Set(), denied: new Set(), states: new Set() };
+    #sinks = { 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 {
@@ -508,8 +520,6 @@ export class Mirror {
         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;
@@ -543,20 +553,18 @@ export class Mirror {
         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`). */
+    /** A snapshot of incarnation `epoch` replaces the authored copy. 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. */
@@ -564,7 +572,7 @@ export class Mirror {
         this.#setState("attached");
         this.#notify();
     } }
-    /** One applied batch: its ops folded into the authored copy; the feeds get them as they came. */
+    /** One applied batch: its ops folded into the authored copy. */
     applyDiff(d, warn) {
         if (this.epoch === undefined || this.state === "closed")
             return;
@@ -578,7 +586,6 @@ export class Mirror {
         this.version = d.version;
         this.hash = d.hash;
         this.#refresh(touched);
-        this.#emitChanges(d.ops);
         this.#notify();
     }
     /** A keyframe replaces the live table. */
@@ -610,11 +617,10 @@ export class Mirror {
     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`. */
+    /** No incarnation: the copy empties, `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;
@@ -624,7 +630,6 @@ export class Mirror {
         this.hash = "";
         this.gap = false;
         this.#setState("detached");
-        this.#emitChanges(ops);
         this.#notify();
     }
     /** The end: emptied, `closed` (`reason` recorded), every feed ended. */
@@ -645,7 +650,7 @@ export class Mirror {
 // --------------------------------------------------------------------------------------- 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()`),
+ * changes). It follows the mirror only while someone listens (`onChange`, a pending `changed()`, a `watch()` loop),
  * and while it does it is in `active`, so the handle's close can end it.
  */
 class MirrorView {
@@ -654,9 +659,12 @@ class MirrorView {
     active;
     ended;
     #listeners = new Set();
+    /** Pending `changed()` calls, each with the value it was armed on: it resolves on the first value that differs from it. */
     #waiting = [];
     #unmirror;
     #last;
+    /** `end()` ran (it runs once). */
+    #over = false;
     constructor(mirror, read, active, ended) {
         this.mirror = mirror;
         this.read = read;
@@ -664,18 +672,21 @@ class MirrorView {
         this.ended = ended;
     }
     get() { return this.read(); }
-    subscribe(listener) {
+    /** `cb` with the value on each change, and once more when the view ends; returns the remover. */
+    onChange(cb) {
         if (this.ended())
             return () => { };
-        this.#listeners.add(listener);
+        this.#listeners.add(cb);
         this.#follow();
-        return () => { this.#listeners.delete(listener); this.#unfollow(); };
+        return () => { this.#listeners.delete(cb); this.#unfollow(); };
     }
+    /** The value after each change; ends with the handle. */
+    watch() { return watchState(cb => this.onChange(cb), () => this.get(), this.ended); }
     changed() {
         if (this.ended())
             return Promise.resolve(this.read());
         const d = deferred();
-        this.#waiting.push(d);
+        this.#waiting.push({ d, armedOn: this.read() });
         this.#follow();
         return d.promise;
     }
@@ -694,6 +705,11 @@ class MirrorView {
         this.active.delete(this);
     }
     #update() {
+        // The node ended (the mirror closed): the view ends with it.
+        if (this.ended()) {
+            this.end();
+            return;
+        }
         let v;
         try {
             v = this.read();
@@ -705,20 +721,28 @@ class MirrorView {
         if (v === this.#last)
             return;
         this.#last = v;
+        // The waits this change answers are taken before the listeners run: a `changed()` a listener arms waits for the next change.
+        // A wait armed on this value already (a scene-level callback ran before this view's update) is not answered by it: it keeps waiting.
+        const waiting = this.#waiting.splice(0);
+        this.#waiting.push(...waiting.filter(w => w.armedOn === v));
         for (const l of [...this.#listeners]) {
             try {
-                l();
+                l(v);
             }
             catch (e) {
                 rethrowLater(e);
             }
         }
-        for (const d of this.#waiting.splice(0))
-            d.resolve(v);
+        for (const w of waiting)
+            if (w.armedOn !== v)
+                w.d.resolve(v);
         this.#unfollow();
     }
-    /** The handle closed: a pending `changed()` resolves with the value now; listeners are dropped. */
+    /** The handle closed: a pending `changed()` resolves with the value now; each callback is told once, then dropped (a `watch()` loop ends there). Once: a callback that closes the handle again is not told twice. */
     end() {
+        if (this.#over)
+            return;
+        this.#over = true;
         let v;
         try {
             v = this.read();
@@ -726,12 +750,73 @@ class MirrorView {
         catch {
             v = this.#last;
         }
-        for (const d of this.#waiting.splice(0))
-            d.resolve(v);
+        for (const w of this.#waiting.splice(0))
+            w.d.resolve(v);
+        for (const l of [...this.#listeners]) {
+            try {
+                l(v);
+            }
+            catch (e) {
+                rethrowLater(e);
+            }
+        }
         this.#listeners.clear();
         this.#unfollow();
     }
 }
+/** `e`, or its `component` (`undefined` when `e` is). */
+const pick = (e, component) => component === undefined ? e : e === undefined ? undefined : e[component];
+/**
+ * One entity as a view (`scene.entity(id | { name })`): the `SceneView` of the merged entity with the store handle's
+ * members, and the entity's two planes (`authored`, `live`), frozen objects made once with the view. `read` picks the
+ * merged entity for the id the view names now; `ops.write` patches the authored entity the view names at the call,
+ * `ops.live` writes its live lanes, `ops.remove` drops its live row.
+ */
+class EntityView extends MirrorView {
+    ops;
+    authored;
+    live;
+    constructor(mirror, read, active, ended, ops) {
+        super(mirror, read, active, ended);
+        this.ops = ops;
+        this.authored = Object.freeze({
+            get: ((component) => pick(ops.readAuthored(), component)),
+            set: ((a, b) => ops.write(typeof a === "string" ? { [a]: b } : a)),
+        });
+        this.live = Object.freeze({
+            get: ((component) => pick(ops.readLive(), component)),
+            set: (components, opts = {}) => ops.live(components, opts),
+            remove: () => ops.remove(),
+        });
+    }
+    get id() { return this.ops.id(); }
+    get(component) { return pick(this.read(), component); }
+    /**
+     * The entity (or `component` of it) after each change; changes in between fold into the latest. A component is
+     * compared by reference: the mirror keeps an unchanged component's object across a change elsewhere (structural
+     * sharing), so only a change of that component wakes it.
+     */
+    watch(component) {
+        return watchState(cb => this.onChange(cb), () => this.get(component), this.ended);
+    }
+}
+/** Releases a claim this node does not keep (granted after its handle closed, or after a `live.remove`): the call `synapse/scene/live/remove`, best effort. */
+function release(node, session, id) {
+    if (!session)
+        return;
+    try {
+        void startOn(node, session, "synapse/scene/live/remove", { id }, {}).result.catch(() => { });
+    }
+    catch { /* the session's end releases it */ }
+}
+/** The id a claim's reply names. */
+function replyId(v) {
+    const id = v?.id;
+    if (typeof id !== "string")
+        throw new SynapseError("internal", "scene live claim reply not understood");
+    return id;
+}
+const sessionGone = (e) => e.code === "connection_lost" || e.code === "not_connected";
 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).
@@ -748,6 +833,82 @@ function closeLiveWriter(w) {
     }
     catch { /* closed */ }
 }
+/** A live batch's wire bytes. */
+function encodeLive(body) {
+    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);
+    return bytes;
+}
+/** One frame on the live writer. */
+function writeLive(w, bytes) {
+    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 });
+    }
+}
+/** Session `s`'s live writer: the current one, or a new one when that is another session's. */
+function liveWriterOn(scene, s) {
+    let w = scene.writer;
+    if (w && w.session === s)
+        return w;
+    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)}`);
+    }
+    return w;
+}
+const UNCLAIMED = { kind: "unclaimed" }, ASKING = { kind: "asking" }, CLAIMED = { kind: "claimed" };
+const parkedRows = (p) => (p.pose ? 1 : 0) + (p.joints ? 1 : 0) + (p.state ? 1 : 0);
+/** One of this node's claims: its own intent, never world state. */
+class Claim {
+    args;
+    state;
+    /** Refusals of it in a row (the pace of the next ask). */
+    refusals = 0;
+    parked = {};
+    /** `args`: the `upsert` call's args besides `id` (a live entity's `kind`, `name`, `parent`, `lifetime_ms` and components); empty for the override of an entity of the scene. */
+    constructor(args, state) {
+        this.args = args;
+        this.state = state;
+    }
+    /** A live entity (claimed again on every attach), not an override (claimed by its lanes). */
+    get isEntity() { return Object.keys(this.args).length > 0; }
+}
+/** When the task's timer asks `c` again: a paced live entity (refused or transient), or a claim paced after a transient answer with rows parked; a refused override is asked by its next lane write instead. */
+function timerDue(c) {
+    const st = c.state;
+    return st.kind === "paced" && (c.isEntity || (!st.refused && parkedRows(c.parked) > 0)) ? st.at : undefined;
+}
+/** A lane batch on the wire: data only (stamps are the runtime's). */
+function laneBody(poses, joints, state, lifetimeMs) {
+    const body = {};
+    if (poses.length)
+        body.poses = poses.map(p => ({ id: p.id, t: p.t, q: p.q }));
+    if (joints.length)
+        body.joints = joints.map(r => ({ id: r.id, j: r.j }));
+    if (state.length)
+        body.state = state.map(r => ({ id: r.id, s: r.s }));
+    if (!Object.keys(body).length)
+        return undefined;
+    if (lifetimeMs !== undefined)
+        body.lifetime_ms = lifetimeMs;
+    return body;
+}
 /** The node's scene: what every handle shares with the task. */
 export class Scene {
     node;
@@ -758,14 +919,52 @@ export class Scene {
     /** 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()`. */
+    /** The live writer of the current session, made on the first live write. */
     writer;
+    /** This node's claims by id (what `live.upsert` made and what lane writes asked for); `live.remove` drops one. Nothing else is kept. */
+    claims = new Map();
     detachedDrops = 0;
+    /** Lane rows dropped because their id's claim was refused (and not due again), or parked rows a refusal dropped. */
+    unclaimedDrops = 0;
+    /** Told when a counter of the status changes (the listeners of the status state values). */
+    counters = new Set();
     constructor(node, warn) {
         this.node = node;
         this.warn = warn;
     }
     post(e) { return this.mailbox.push(e); }
+    countersChanged() { for (const l of [...this.counters]) {
+        try {
+            l();
+        }
+        catch (e) {
+            rethrowLater(e);
+        }
+    } }
+    /**
+     * What happens to a lane row of `id` now. An id with no claim becomes the override's claim; an override that is
+     * unclaimed, or refused and due again, is marked asked and returned in `ask` (the task asks it: one ask per id at a
+     * time). A live entity's claim is asked by the task (on attach, paced after a refusal), never by a lane.
+     */
+    gate(id, now, ask) {
+        let c = this.claims.get(id);
+        if (!c)
+            this.claims.set(id, (c = new Claim({}, UNCLAIMED)));
+        const st = c.state;
+        if (st.kind === "claimed")
+            return "send";
+        if (st.kind === "asking")
+            return "park";
+        if (st.kind === "unclaimed" && c.isEntity)
+            return "park";
+        if (st.kind === "paced" && !st.refused)
+            return "park";
+        if (st.kind === "paced" && (c.isEntity || st.at > now))
+            return "drop";
+        c.state = ASKING;
+        ask.push(id);
+        return "park";
+    }
     request(make) {
         const reply = deferred();
         if (!this.post(make(reply)))
@@ -778,6 +977,16 @@ const detachedError = () => new SynapseError("project_inactive", "the scene is d
 function closedError(reason) {
     return new SynapseError("not_connected", reason === ENDED_CONNECTION_LOST ? "the node ended" : "the scene handle is closed");
 }
+/** A view by name whose name no entity holds: nothing to send to (`not_found`, as the runtime answers an unknown id). */
+function notNamed(ref) {
+    const name = typeof ref === "string" ? undefined : ref.name;
+    return new SynapseError("not_found", { message: `scene: no entity is named ${JSON.stringify(name)}`, data: { name } });
+}
+/** An `upsert` is keyed by its name: an `id` component (the type forbids it; JavaScript does not) is `invalid_input`, nothing sent. */
+function refuseId(opts, verb) {
+    if ("id" in opts)
+        throw new SynapseError("invalid_input", { message: `${verb} is keyed by its name: an id component is not taken`, data: { component: "id" } });
+}
 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) {
@@ -793,6 +1002,23 @@ async function run(scene, registry) {
     let unwatchProject;
     const joining = [];
     let waiters = [];
+    /** The attach the claims are made for (session and incarnation), if any. */
+    let bound;
+    /** Counts attaches: an answer to a claim asked in an earlier one is not this one's. */
+    let bindNo = 0;
+    /** The ids whose claim is being asked again (one ask per id at a time). */
+    const asking = new Set();
+    /** `live.upsert` calls waiting for an attach (attached a moment before the task was told, or their session went before the answer). */
+    let parkedUpserts = [];
+    /**
+     * The `live.upsert` calls on the wire, by token: the id each named (a claim of that name this node held), and whether its
+     * answer may still be kept (`false` once a `live.remove` of that id or the handle's close came after it: a grant is then
+     * released, never kept).
+     */
+    const firsts = new Map();
+    let nextFirst = 0;
+    let reclaimTimer;
+    let reclaimAt = Infinity;
     const inactive = () => project !== undefined && project.active === null;
     const answerJoins = () => { for (const j of joining.splice(0))
         j.resolve(); };
@@ -822,13 +1048,14 @@ async function run(scene, registry) {
         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 }));
+        void followIncarnation(scene, s, announced, endedEpoch, stop.signal, attempt).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();
+        unbind();
         const a = ++attempts;
         phase = { kind: "paced", timer: setTimeout(() => scene.post({ kind: "paced", attempt: a }), paceMs) };
     };
@@ -838,6 +1065,7 @@ async function run(scene, registry) {
         stopPhase();
         failWaiters(() => new SynapseError("connection_lost", "the session ended before the write showed in the scene"));
         mirror.detach();
+        unbind();
         closeLiveWriter(scene.writer);
         scene.writer = undefined;
         unwatchProject?.();
@@ -849,13 +1077,317 @@ async function run(scene, registry) {
             answerJoins();
         follow();
     };
+    /** The reader applied an authored frame of `epoch` reaching `version`: the writes it shows are answered; attached, the `scene()` calls waiting too. */
     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();
+        if (mirror.state !== "attached")
+            return;
+        answerJoins();
+    };
+    /**
+     * Reading `attempt` (the one in progress) caught up with incarnation `epoch` at `version`: the claims are made for it
+     * first (`bind`), then the handle is `attached` (one path: nothing a handle does after it sees `attached` meets an
+     * unbound attach). A stale reader's attach is ignored.
+     */
+    const attach = (attempt, epoch, version) => {
+        const p = ph();
+        if (p.kind !== "following" || p.attempt !== attempt || mirror.epoch !== epoch || !session)
+            return;
+        if (bound?.session !== session || bound.epoch !== epoch)
+            bind(session, epoch);
+        mirror.attach();
+        applied(epoch, version);
+    };
+    // ---- claims (PLAN v0.31)
+    /** The claims are made for an attach no more (a session gap, an incarnation let go): each is unclaimed; answers of asks made before are not this attach's. */
+    const unbind = () => {
+        bound = undefined;
+        bindNo += 1;
+        asking.clear();
+        // Rows parked for the attach that ended are not this one's data.
+        for (const c of scene.claims.values()) {
+            c.state = UNCLAIMED;
+            c.parked = {};
+        }
+    };
+    /** Attached to incarnation `epoch` on session `s`: every live entity of this node's is claimed again, same id (an override, by its next lane write); the `live.upsert` calls waiting are asked. */
+    const bind = (s, epoch) => {
+        unbind();
+        bound = { session: s, epoch };
+        for (const [id, c] of [...scene.claims])
+            if (c.isEntity)
+                askAgain(id);
+        const waiting = parkedUpserts;
+        parkedUpserts = [];
+        for (const u of waiting)
+            askFirst(u.args, u.reply);
+    };
+    /** Starts the claim call with `args` in this attach; its answer comes back as `claimDone`. Returns the error when it could not be sent. */
+    const callClaim = (ask, args) => {
+        if (!session || !bound)
+            return detachedError();
+        let call;
+        try {
+            call = startOn(node, session, "synapse/scene/live/upsert", args, {});
+        }
+        catch (e) {
+            return asError(e);
+        }
+        const b = bindNo;
+        const s = session;
+        const done = (result) => {
+            if (scene.post({ kind: "claimDone", ask, bind: b, result }))
+                return;
+            // The task is gone (the handle closed): a grant is released, never kept; a `live.upsert` caller is answered from here.
+            if ("ok" in result) {
+                try {
+                    release(node, s, replyId(result.ok));
+                }
+                catch { /* not understood: nothing to release */ }
+            }
+            if (ask.kind === "first")
+                ask.reply.reject(closedError(ENDED_CLIENT));
+        };
+        void call.result.then(v => done({ ok: v }), (e) => done({ err: asError(e) }));
+        return undefined;
+    };
+    /** Asks the claim of `id` again with its args (one ask per id at a time). */
+    const askAgain = (id) => {
+        if (!bound || asking.has(id))
+            return;
+        const c = scene.claims.get(id);
+        if (!c)
+            return;
+        c.state = ASKING;
+        asking.add(id);
+        if (callClaim({ kind: "again", id }, { ...c.args, id })) {
+            // Not sent: asked again at the next attach.
+            asking.delete(id);
+            const now = scene.claims.get(id);
+            if (now)
+                now.state = UNCLAIMED;
+        }
+    };
+    /** A `live.upsert`: asked with the id of this node's claim of that name, if it has one (its own intent), else without an id (the runtime mints it). */
+    const askFirst = (args, reply) => {
+        const callArgs = { ...args };
+        let named;
+        if (args.name !== undefined)
+            for (const [id, c] of scene.claims)
+                if (c.args.name === args.name) {
+                    callArgs.id = named = id;
+                    break;
+                }
+        const token = nextFirst++;
+        firsts.set(token, { named, keep: true });
+        const e = callClaim({ kind: "first", args, reply, token }, callArgs);
+        if (e) {
+            firsts.delete(token);
+            reply.reject(e);
+        }
+    };
+    const upsert = (args, reply) => {
+        if (mirror.state === "closed")
+            reply.reject(closedError(mirror.ended ?? ENDED_CLIENT));
+        else if (mirror.state === "detached")
+            reply.reject(detachedError());
+        // Attached: the claims are bound (the task attaches the handle after the bind: one path).
+        else
+            askFirst(args, reply);
+    };
+    /** A lane write asked the claim of `id`: asked now when bound; otherwise unclaimed (the next lane write after the attach asks it). */
+    const claimAsked = (id) => {
+        if (bound) {
+            askAgain(id);
+            return;
+        }
+        const c = scene.claims.get(id);
+        if (c?.state.kind === "asking")
+            c.state = UNCLAIMED;
+    };
+    /** `live.remove`: the claim dropped; the runtime asked to release it when this attach holds it (or asks it), else answered at once. */
+    const remove = (id, reply) => {
+        const c = scene.claims.get(id);
+        scene.claims.delete(id);
+        asking.delete(id);
+        // A `live.upsert` of this id on the wire: its answer is not kept (granted, it is released).
+        for (const f of firsts.values())
+            if (f.named === id)
+                f.keep = false;
+        const held = !c || c.state.kind === "claimed" || c.state.kind === "asking";
+        if (!session || !bound || !held) {
+            reply.resolve();
+            return;
+        }
+        let call;
+        try {
+            call = startOn(node, session, "synapse/scene/live/remove", { id }, {});
+        }
+        catch (e) {
+            reply.reject(asError(e));
+            return;
+        }
+        void call.result.then(() => reply.resolve(), (e) => reply.reject(asError(e)));
+    };
+    /** The rows parked for `id` go out now, as one batch. */
+    const sendParked = (id) => {
+        const c = scene.claims.get(id);
+        if (!c || !session)
+            return;
+        const p = c.parked;
+        c.parked = {};
+        const body = laneBody(p.pose ? [p.pose] : [], p.joints ? [p.joints] : [], p.state ? [p.state] : [], p.lifetimeMs);
+        if (!body)
+            return;
+        // Not sent (the session is going): its end resets the claims, the rows are not re-sent (a batch is never re-sent).
+        try {
+            writeLive(liveWriterOn(scene, session), encodeLive(body));
+        }
+        catch { /* the session's end follows */ }
+    };
+    /** The runtime answered a claim asked in attach `b`. */
+    const claimDone = (ask, b, result) => {
+        if (ask.kind === "first") {
+            let r;
+            if ("ok" in result) {
+                try {
+                    r = { ok: replyId(result.ok) };
+                }
+                catch (e) {
+                    r = { err: asError(e) };
+                }
+            }
+            else
+                r = result;
+            const f = firsts.get(ask.token);
+            firsts.delete(ask.token);
+            const keep = (f?.keep ?? false) && mirror.state !== "closed";
+            if ("ok" in r && !keep) {
+                // Not kept: a `live.remove` of its id or the handle's close came after it. A grant is released; nothing is kept.
+                release(node, session, r.ok);
+                if (mirror.state === "closed")
+                    ask.reply.reject(closedError(mirror.ended ?? ENDED_CLIENT));
+                else
+                    ask.reply.resolve(r.ok);
+            }
+            else if ("ok" in r) {
+                // Granted in an earlier attach: claimed again in this one.
+                const here = b === bindNo;
+                scene.claims.set(r.ok, new Claim(ask.args, here ? CLAIMED : UNCLAIMED));
+                if (!here)
+                    askAgain(r.ok);
+                ask.reply.resolve(r.ok);
+            }
+            else if (sessionGone(r.err)) {
+                // The session went before the runtime answered: asked on the next attach (unless no longer wanted).
+                if (!keep)
+                    ask.reply.reject(r.err);
+                else if (b !== bindNo && bound)
+                    askFirst(ask.args, ask.reply);
+                else
+                    parkedUpserts.push({ args: ask.args, reply: ask.reply });
+            }
+            else
+                ask.reply.reject(r.err);
+            return;
+        }
+        if (b !== bindNo)
+            return;
+        const id = ask.id;
+        asking.delete(id);
+        const c = scene.claims.get(id);
+        if (!c)
+            return;
+        if ("ok" in result) {
+            c.state = CLAIMED;
+            c.refusals = 0;
+            // The rows parked while it was asked go out now.
+            sendParked(id);
+            return;
+        }
+        const e = result.err;
+        if (sessionGone(e)) {
+            c.state = UNCLAIMED;
+            return;
+        }
+        // The runtime is mid-change: asked again shortly, silently (rows keep parking).
+        if (isTransient(e)) {
+            c.state = { kind: "paced", at: performance.now() + REFOLLOW_PACE_MS, refused: false };
+            return;
+        }
+        c.refusals += 1;
+        const pace = refusalPaceMs(c.refusals);
+        scene.warn(`scene: live claim of ${id} refused by the runtime (${e.code}${e.message ? `: ${e.message}` : ""}; attempt ${c.refusals}; asking again in ${pace} ms)`);
+        c.state = { kind: "paced", at: performance.now() + pace, refused: true };
+        const dropped = parkedRows(c.parked);
+        c.parked = {};
+        if (dropped) {
+            scene.unclaimedDrops += dropped;
+            scene.countersChanged();
+        }
+        // An override's refusal is the writer's to see: a node notice (a `not_owner` reaches the denial feeds through it).
+        if (!c.isEntity) {
+            const body = { code: e.code };
+            if (e.message)
+                body.message = e.message;
+            if (e.data !== undefined)
+                body.data = e.data;
+            for (const cb of [...node.notices]) {
+                try {
+                    cb(body);
+                }
+                catch (x) {
+                    rethrowLater(x);
+                }
+            }
+        }
+    };
+    /** The task ends: every claim held (or asked) in this attach is released by the call `synapse/scene/live/remove {id}`, one call per claim, best effort (not awaited); the claims are dropped. The session's end releases whatever remains. */
+    const releaseClaims = () => {
+        for (const f of firsts.values())
+            f.keep = false;
+        const claims = [...scene.claims];
+        scene.claims.clear();
+        if (!session || !bound)
+            return;
+        for (const [id, c] of claims) {
+            if (c.state.kind !== "claimed" && c.state.kind !== "asking")
+                continue;
+            try {
+                void startOn(node, session, "synapse/scene/live/remove", { id }, {}).result.catch(() => { });
+            }
+            catch { /* the session's end releases it */ }
+        }
+    };
+    /** The refused live entities that are due are asked again. */
+    const reclaimDue = () => {
+        const now = performance.now();
+        for (const [id, c] of [...scene.claims]) {
+            const at = timerDue(c);
+            if (at !== undefined && at <= now)
+                askAgain(id);
+        }
+    };
+    /** The timer for the next refused live entity due to be asked again (none while unbound or nothing paced). */
+    const armReclaim = () => {
+        let at = Infinity;
+        if (bound)
+            for (const c of scene.claims.values()) {
+                const due = timerDue(c);
+                if (due !== undefined && due < at)
+                    at = due;
+            }
+        if (at === reclaimAt)
+            return;
+        if (reclaimTimer !== undefined)
+            clearTimeout(reclaimTimer);
+        reclaimTimer = undefined;
+        reclaimAt = at;
+        if (at !== Infinity)
+            reclaimTimer = setTimeout(() => { reclaimAt = Infinity; reclaimTimer = undefined; scene.post({ kind: "reclaim" }); }, Math.max(0, at - performance.now()));
     };
     const join = (reply) => { if (mirror.state === "attached" || inactive())
         reply.resolve();
@@ -957,6 +1489,9 @@ async function run(scene, registry) {
                 case "applied":
                     applied(ev.epoch, ev.version);
                     break;
+                case "attach":
+                    attach(ev.attempt, ev.epoch, ev.version);
+                    break;
                 case "followEnded": {
                     {
                         const p = ph();
@@ -993,11 +1528,33 @@ async function run(scene, registry) {
                         follow();
                     }
                     break;
+                case "upsert":
+                    upsert(ev.args, ev.reply);
+                    break;
+                case "remove":
+                    remove(ev.id, ev.reply);
+                    break;
+                case "claim":
+                    claimAsked(ev.id);
+                    break;
+                case "claimDone":
+                    claimDone(ev.ask, ev.bind, ev.result);
+                    break;
+                case "reclaim":
+                    reclaimDue();
+                    break;
                 case "close": break loop;
             }
+            armReclaim();
         }
     }
     finally {
+        // The last handle closed (or the node ended): this node's claims are released (best effort).
+        releaseClaims();
+        if (reclaimTimer !== undefined)
+            clearTimeout(reclaimTimer);
+        for (const u of parkedUpserts.splice(0))
+            u.reply.reject(closedError(reason));
         unmonitor();
         node.notices.delete(onNotice);
         unwatchProject?.();
@@ -1016,13 +1573,18 @@ async function run(scene, registry) {
                 break;
             if (ev.kind === "applyDone")
                 applyDone(ev.epoch, ev.result, ev.reply);
-            else if (ev.kind === "apply" || ev.kind === "join")
+            else if (ev.kind === "apply" || ev.kind === "join" || ev.kind === "upsert" || ev.kind === "remove")
                 ev.reply.reject(closedError(reason));
+            else if (ev.kind === "claimDone")
+                claimDone(ev.ask, ev.bind, ev.result); // a grant arriving now is released (`releaseClaims` marked every first not kept)
         }
         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")
+        for (let ev = scene.mailbox.tryNext(); ev; ev = scene.mailbox.tryNext()) {
+            if (ev.kind === "apply" || ev.kind === "join" || ev.kind === "applyDone" || ev.kind === "upsert" || ev.kind === "remove")
                 ev.reply.reject(closedError(reason));
+            else if (ev.kind === "claimDone")
+                claimDone(ev.ask, ev.bind, ev.result); // a grant arriving now is released (`releaseClaims` marked every first not kept)
+        }
         if (registry.current === scene)
             registry.current = undefined;
         scene.exited.resolve();
@@ -1144,7 +1706,7 @@ function decodeFrame(p, warn, what) {
  * 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) {
+async function followIncarnation(scene, session, announced, skip, signal, attempt) {
     const { mirror, warn } = scene;
     const none = { epoch: undefined, reason: undefined };
     const closers = [announced];
@@ -1268,8 +1830,8 @@ async function followIncarnation(scene, session, announced, skip, signal) {
         live.drain(onLive);
         if (signal.aborted)
             return none;
-        mirror.attach();
-        scene.post({ kind: "applied", epoch: at, version: mirror.version });
+        // The task attaches the handle, once the claims are made for this incarnation.
+        scene.post({ kind: "attach", attempt, 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);
@@ -1316,34 +1878,180 @@ export class SceneHandleImpl {
     /** The views of this handle that follow the mirror now. */
     #views = new Set();
     #unsubscribes = new Set();
+    /** `ready()` calls waiting for the handle to attach: rejected by `close()`. */
+    #readies = new Set();
+    /** Told when this handle closes (its status says `closed` from then on, whatever the node's other handles do). */
+    #onClose = new Set();
+    /** The authored plane's verbs. */
+    authored;
+    /** This node's live writes. */
+    live;
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    status;
+    #status;
     constructor(scene) {
         this.scene = scene;
         scene.handles++;
         this.#id = scene.nextHandle++;
+        this.status = this.#status = new StatusCell(() => this.#statusNow(), l => {
+            const un = scene.mirror.subscribe(l);
+            scene.counters.add(l);
+            this.#onClose.add(l);
+            return () => { un(); scene.counters.delete(l); this.#onClose.delete(l); };
+        }, () => this.#closed || scene.mirror.state === "closed");
+        // One object each for the handle's life.
+        this.authored = Object.freeze({
+            apply: (ops, base) => this.#apply(ops, base),
+            txn: (build) => this.#txn(build),
+            spawn: (kind, opts) => this.#spawn(kind, opts),
+            patch: (entity, set) => this.#txn(t => t.patch(entity, set)),
+            upsert: (kind, opts) => this.#upsert(kind, opts),
+            rename: (entity, name) => this.#txn(t => t.rename(entity, name)),
+            reparent: (entity, parent, place) => this.#txn(t => t.reparent(entity, parent, place)),
+            despawn: (entity, opts) => this.#txn(t => t.despawn(entity, opts)),
+            setLocked: (entity, locked) => this.#txn(t => t.setLocked(entity, locked)),
+        });
+        this.live = Object.freeze({
+            batch: (batch) => this.#batch(batch),
+            upsert: (kind, opts, live) => this.#liveUpsert(kind, opts ?? {}, live ?? {}),
+            remove: (entity) => { try {
+                return this.#releaseId(idOf(entity));
+            }
+            catch (e) {
+                return Promise.reject(e);
+            } },
+        });
     }
-    get entities() { return this.scene.mirror.merged; }
-    entity(id, opts = {}) {
+    /** The merged entities now; a closed handle reads nothing (the mirror may live on for the node's other handles). */
+    get() { return this.#closed ? EMPTY : this.scene.mirror.merged; }
+    /** One entity as a view: the merged entity, with its authored value (`authored`) and its live row (`live`). */
+    entity(ref) {
         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 named = this.#idOf(ref);
+        const id = () => {
+            const id = named();
+            if (id === undefined)
+                throw notNamed(ref);
+            return id;
+        };
+        const ended = () => this.#closed || mirror.state === "closed";
+        // Every read goes through the same guard: a closed handle reads nothing (the mirror may live on for the node's other handles).
+        const reader = (read) => () => {
+            if (ended())
+                return undefined;
+            const id = named();
+            return id === undefined ? undefined : read(id);
+        };
+        // The live row, rebuilt only when the row object changes and kept the same object while equal.
+        let from;
+        let last;
+        const ops = {
+            id,
+            // 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.
+            readAuthored: reader(id => mirror.authored.get(id) ?? mirror.live.get(id)?.entity),
+            readLive: reader(id => {
                 const row = mirror.live.get(id);
                 if (row === from)
                     return last;
                 from = row;
                 last = row ? replaceEqualDeep(last, liveValue(row)) : undefined;
                 return last;
-            });
+            }),
+            write: components => this.#write(ref, named, components),
+            live: (components, opts) => this.#liveLanes(ref, named, components, opts),
+            remove: () => this.#liveRemove(ref, named),
+        };
+        return new EntityView(mirror, reader(id => mirror.merged[id]), this.#views, ended, ops);
+    }
+    /**
+     * The id a view names now: its id, or the id of the entity holding its name (names are unique across every plane;
+     * an authored or calibration entity, else a live entity). The last id found is checked first: a name is held by one
+     * entity at a time.
+     */
+    #idOf(ref) {
+        if (typeof ref === "string")
+            return () => ref;
+        if (!isObject(ref) || typeof ref.name !== "string")
+            throw new SynapseError("invalid_input", "scene.entity takes an id or { name }");
+        const name = ref.name, mirror = this.scene.mirror;
+        let held;
+        return () => {
+            if (held !== undefined && (mirror.authored.get(held) ?? mirror.live.get(held)?.entity)?.name === name)
+                return held;
+            held = authoredNamed(mirror.authored, name)?.id ?? liveNamed(mirror.live, name);
+            return held;
+        };
+    }
+    /** An entity view's `authored.set`: one patch of the id it names now. A name no entity holds has nothing to send: `not_found`, as the runtime answers a patch of an unknown id. */
+    async #write(ref, named, components) {
+        if (this.#closed)
+            throw closedError(ENDED_CLIENT);
+        if (this.scene.mirror.state === "detached")
+            throw detachedError();
+        const id = named();
+        if (id === undefined)
+            throw notNamed(ref);
+        await this.#txn(t => t.patch(id, components));
+    }
+    /** An entity view's `live.set`: the lanes of the id it names now, as one batch. */
+    #liveLanes(ref, named, components, opts) {
+        this.#liveOpen();
+        const lanes = {};
+        for (const [k, v] of Object.entries(components)) {
+            if (v === undefined)
+                continue;
+            if (k === "xform") {
+                const x = v;
+                if (!isObject(v) || !("t" in x) || !("q" in x) || Object.keys(x).some(k => k !== "t" && k !== "q"))
+                    throw new SynapseError("invalid_input", "scene: live xform is the pose lane: { t, q }, both, nothing else");
+            }
+            else if (k !== "joints" && k !== "state")
+                throw new SynapseError("invalid_input", { message: `scene: live.set(...) writes the lanes xform ({ t, q }), joints and state, not ${JSON.stringify(k)}`, data: { component: k } });
+            lanes[k] = v;
+        }
+        const id = named();
+        if (id === undefined) {
+            // Detached, nothing is named: the write is dropped and counted, as every live write then is.
+            if (this.scene.mirror.state !== "attached") {
+                this.scene.detachedDrops++;
+                this.scene.countersChanged();
+                return;
+            }
+            throw notNamed(ref);
+        }
+        const batch = {};
+        const x = lanes.xform;
+        if (x)
+            batch.poses = [{ id, t: x.t, q: x.q }];
+        if (lanes.joints !== undefined)
+            batch.joints = [{ id, j: lanes.joints }];
+        if (lanes.state !== undefined)
+            batch.state = [{ id, s: lanes.state }];
+        if (opts.lifetimeMs !== undefined)
+            batch.lifetimeMs = opts.lifetimeMs;
+        this.#batch(batch);
+    }
+    /** An entity view's `live.remove`: the release call of the id it names now (`scene.live.remove(id)`); a view by name whose name no entity holds has no id to release: `not_found`. */
+    #liveRemove(ref, named) {
+        try {
+            this.#liveOpen();
+            const id = named();
+            if (id === undefined)
+                throw notNamed(ref);
+            return this.#releaseId(id);
         }
-        return this.#view(() => mirror.merged[id]);
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    /** `live.remove`: the call `synapse/scene/live/remove {id}` through the task (it drops the claim). */
+    #releaseId(id) {
+        if (this.#closed)
+            return Promise.reject(closedError(ENDED_CLIENT));
+        return this.scene.request(reply => ({ kind: "remove", id, reply }));
     }
-    tree() { return this.#view(() => this.scene.mirror.tree()); }
+    tree() { return this.#view(() => this.scene.mirror.tree(), EMPTY_TREE); }
     query(where) {
         let from;
         let last = [];
@@ -1355,13 +2063,40 @@ export class SceneHandleImpl {
             const ids = Object.keys(m).filter(id => where(m[id])).sort();
             last = replaceEqualDeep(last, ids.map(id => m[id]));
             return last;
-        });
+        }, EMPTY_LIST);
+    }
+    /** A view of `read`; a closed handle reads `empty` (the mirror may live on for the node's other handles), as its entity views and `get()` do. */
+    #view(read, empty) {
+        const ended = () => this.#closed || this.scene.mirror.state === "closed";
+        return new MirrorView(this.scene.mirror, () => (ended() ? empty : read()), this.#views, ended);
     }
-    #view(read) { return new MirrorView(this.scene.mirror, read, this.#views, () => this.#closed || this.scene.mirror.state === "closed"); }
-    get status() {
+    #statusNow() {
         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 };
+        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, unclaimedDrops: this.scene.unclaimedDrops };
+    }
+    /** The one boolean a node author checks: `status.get().synced`. */
+    get synced() { return this.status.get().synced; }
+    /** Resolves once the handle is attached (at once if it is); `not_connected` once it is closed (`close()`, or the node ending). */
+    ready() {
+        const m = this.scene.mirror;
+        if (this.#closed || m.state === "closed")
+            return Promise.reject(closedError(this.#closed ? ENDED_CLIENT : m.ended ?? ENDED_CLIENT));
+        if (m.state === "attached")
+            return Promise.resolve();
+        const d = deferred();
+        this.#readies.add(d);
+        const un = this.onChange(() => {
+            if (m.state === "closed")
+                d.reject(closedError(m.ended ?? ENDED_CLIENT));
+            else if (m.state === "attached")
+                d.resolve();
+            else
+                return;
+            un();
+            this.#readies.delete(d);
+        });
+        return d.promise;
     }
     // ---- feeds
     #feed(kind, cb) {
@@ -1385,99 +2120,184 @@ export class SceneHandleImpl {
             void q.close();
         return iterate(q, () => m.removeSink(kind, sink));
     }
-    watchChanges(cb) { return this.#feed("changes", cb); }
+    #ended() { return this.#closed || this.scene.mirror.state === "closed"; }
+    /** The entities after their next change (state, not history); `not_connected` once this handle is closed. */
+    changed() {
+        const m = this.scene.mirror;
+        const closed = () => closedError(this.#closed ? ENDED_CLIENT : m.ended ?? ENDED_CLIENT);
+        if (this.#ended())
+            return Promise.reject(closed());
+        const from = this.get();
+        const d = deferred();
+        const un = this.onChange(v => {
+            if (this.#ended())
+                d.reject(closed());
+            else if (v !== from)
+                d.resolve(v);
+            else
+                return;
+            un();
+        });
+        return d.promise;
+    }
+    /** The entities after each change; ends with the handle. */
+    watch() { return watchState(cb => this.onChange(cb), () => this.get(), () => this.#ended()); }
     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) {
+    // ---- authored (`scene.authored`): 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) {
+    async #txn(build) {
         const t = new Txn();
         build(t);
-        await this.apply([...t.ops]);
+        await this.#apply([...t.ops]);
     }
-    async spawn(kind, opts) {
+    async #spawn(kind, opts) {
         let id = "";
-        await this.txn(t => { id = t.spawn(kind, opts); });
+        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.
+     * The entity named `name`, made to carry `components`; its view (by id). None of that name in the authored scene:
+     * `spawn` (with `parent`). One: its authored row (live overrides never count) is compared with what a `patch` of the
+     * components would make of it; equal, nothing is sent; else a `patch` of the components that differ. `parent` is for
+     * the spawn only (an existing entity is not reparented). One of another kind in the mirror: `spawn` too, and the
+     * runtime answers (the mirror may be stale: `name_taken` with `holder` while the name is held, the spawn when it was
+     * freed). An `id` component: `invalid_input` (`data: { component: "id" }`), nothing sent.
      */
-    live(batch) {
+    async #upsert(kind, opts) {
         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;
+        refuseId(opts, "scene.authored.upsert");
+        const { name, parent: _parent, ...components } = opts;
+        const found = authoredNamed(this.scene.mirror.authored, name);
+        if (!found || found.kind !== kind)
+            return this.entity(await this.#spawn(kind, opts));
+        const row = found;
+        const after = mergeSet(row, components);
+        // Only the components that differ (a patch of `flags` alone is what a locked entity accepts).
+        const differ = Object.fromEntries(Object.entries(components).filter(([k]) => !deepEqual(row[k], after[k])));
+        if (Object.keys(differ).length)
+            await this.#txn(t => t.patch(found.id, differ));
+        return this.entity(found.id);
+    }
+    // ---- live (`scene.live`)
+    /**
+     * A live entity of this node's: the call `synapse/scene/live/upsert {kind, name?, parent, lifetime_ms?, ...components}`
+     * through the task; resolves with the view of the id the runtime answered (a name this node already claimed sends that
+     * claim's id: its own intent). The runtime decides: its refusal is the rejection, as it came, and nothing is kept.
+     * Granted, it is this node's claim, claimed again (same id) on every attach until `remove`. A session that goes before
+     * the answer: asked at the next attach. Detached: `project_inactive`; the node ending: `not_connected`.
+     */
+    #liveUpsert(kind, opts, live) {
         try {
-            bytes = encodeBody(body);
+            this.#liveOpen();
+            refuseId(opts, "scene.live.upsert");
         }
         catch (e) {
-            throw new SynapseError("invalid_input", `live batch not encodable: ${e instanceof Error ? e.message : String(e)}`);
+            return Promise.reject(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;
+        const { name, parent, ...components } = opts;
+        let parentId;
         try {
-            w.stream.write(header, bytes);
+            parentId = parent == null ? null : idOf(parent, "parent");
         }
         catch (e) {
-            throw new SynapseError("connection_lost", { message: e instanceof Error ? e.message : String(e), source: "transport", cause: e });
+            return Promise.reject(e);
+        }
+        const args = {};
+        for (const [k, v] of Object.entries(components))
+            if (v !== undefined)
+                args[k] = v;
+        args.kind = kind;
+        if (name !== undefined)
+            args.name = name;
+        args.parent = parentId;
+        if (live.lifetimeMs !== undefined)
+            args.lifetime_ms = live.lifetimeMs;
+        return this.scene.request(reply => ({ kind: "upsert", args, reply })).then(id => this.entity(id));
+    }
+    /**
+     * Writes one lane batch on this node's live track (made on the first write of each session); returns at once, like
+     * `publish`. A row goes out only for an id this node claimed in the bound incarnation; the first row of an id with no
+     * claim asks `upsert {id}` (the override) once, and until the answer the latest row of each lane of that id is parked
+     * (latest wins), sent once granted, dropped and counted when refused (`unclaimedDrops`; rows written while refused and
+     * not due again are dropped and counted too). Not attached: dropped and counted (`detachedDrops`). `upsert`/`remove`
+     * keys (the type does not allow them) are sent as given: the runtime refuses such a batch (`invalid_input`, `data {lane}`).
+     */
+    #batch(batch) {
+        this.#liveOpen();
+        const scene = this.scene;
+        const s = scene.node.currentSession();
+        if (scene.mirror.state !== "attached" || !s) {
+            scene.detachedDrops++;
+            scene.countersChanged();
+            return;
+        }
+        const now = performance.now(), ask = [];
+        const poses = [], joints = [], state = [];
+        let dropped = 0;
+        const lane = (rows, out, park) => {
+            for (const r of rows ?? []) {
+                const g = scene.gate(r.id, now, ask);
+                if (g === "send")
+                    out.push(r);
+                else if (g === "park") {
+                    const p = scene.claims.get(r.id).parked;
+                    park(p, r);
+                    p.lifetimeMs = batch.lifetimeMs;
+                }
+                else
+                    dropped += 1;
+            }
+        };
+        lane(batch.poses, poses, (p, r) => { p.pose = r; });
+        lane(batch.joints, joints, (p, r) => { p.joints = r; });
+        lane(batch.state, state, (p, r) => { p.state = r; });
+        if (dropped) {
+            scene.unclaimedDrops += dropped;
+            scene.countersChanged();
         }
+        for (const id of ask)
+            scene.post({ kind: "claim", id });
+        const body = laneBody(poses, joints, state, batch.lifetimeMs) ?? {};
+        const rest = batch;
+        if (rest.upsert !== undefined)
+            body.upsert = rest.upsert;
+        if (rest.remove !== undefined)
+            body.remove = rest.remove;
+        if (!Object.keys(body).length)
+            return;
+        if (batch.lifetimeMs !== undefined)
+            body.lifetime_ms = batch.lifetimeMs;
+        writeLive(liveWriterOn(scene, s), encodeLive(body));
+    }
+    /** A live write on a closed handle, or after the node ended (the node says so at once; the mirror closes once the scene task took `nodeEnded`), is `not_connected`, never a detached drop. */
+    #liveOpen() {
+        if (this.#closed)
+            throw closedError(ENDED_CLIENT);
+        if (this.scene.node.isEnded)
+            throw closedError(ENDED_CONNECTION_LOST);
+        const m = this.scene.mirror;
+        if (m.state === "closed")
+            throw closedError(m.ended ?? ENDED_CLIENT);
     }
-    /** The framework bridge (React's hooks): called on every change of the entities or the status. */
-    subscribe(listener) {
+    /** `cb` with the entities on every change of the entities or the status (the framework bridge, React's hooks), and once more when this handle closes; returns the remover. */
+    onChange(cb) {
         if (this.#closed)
             return () => { };
-        const un = this.scene.mirror.subscribe(listener);
+        const l = () => cb(this.get());
+        const un = this.scene.mirror.subscribe(l);
         this.#unsubscribes.add(un);
-        return () => { un(); this.#unsubscribes.delete(un); };
+        this.#onClose.add(l);
+        return () => { un(); this.#unsubscribes.delete(un); this.#onClose.delete(l); };
     }
-    /** 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. */
+    /** 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 releases this node's claims (one `synapse/scene/live/remove` call per claim, best effort, not awaited; the session's end releases what remains) and ends its live writer. Idempotent. */
     close() {
         if (this.#closed)
             return;
@@ -1488,6 +2308,19 @@ export class SceneHandleImpl {
         for (const un of this.#unsubscribes)
             un();
         this.#unsubscribes.clear();
+        for (const d of this.#readies)
+            d.reject(closedError(ENDED_CLIENT));
+        this.#readies.clear();
+        for (const l of [...this.#onClose]) {
+            try {
+                l();
+            }
+            catch (e) {
+                rethrowLater(e);
+            }
+        }
+        this.#onClose.clear();
+        this.#status.dispose();
         if (--this.scene.handles === 0)
             this.scene.post({ kind: "close" });
     }
@@ -1496,11 +2329,10 @@ export class SceneHandleImpl {
 /**
  * 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.
+ * handle then follows the incarnations as they come and go. Without a session (before the first, between
+ * two) the task waits for the next one, like after a drop.
  */
 export async function openScene(node, registry, warn) {
-    if (!node.currentSession())
-        throw new SynapseError("not_connected");
     let scene;
     let h;
     for (;;) {