@synapse-sdk/client 0.3.3 → 0.3.4

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc, Tlv, JsonSchema } from "@synapse-sdk/core";
 import type { SynapseError, TasksRun } from "@synapse-sdk/core";
+import type { StateValue } from "./util.ts";
 export type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc };
 /** What the reconnect policy is asked before every attempt. */
 export interface RetryContext {
@@ -12,31 +13,21 @@ export interface ReconnectPolicy {
     nextRetryDelayMs(ctx: RetryContext): number | null;
 }
 export type Transport = "auto" | "webtransport" | "websocket";
+/** The node's own options (`new Synapse(opts)`): who it is and how it behaves. Where it connects is a `ConnectTarget`, given to `connect()`. */
 export interface ConnectOptions {
-    /**
-     * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
-     * the runtime's path, `https://relay:4443/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
-     * Absent: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts); a browser has no environment,
-     * so there it is `invalid_input`.
-     */
-    url?: string;
-    /** The relay token that lets this node through a relay; none for a runtime dialed directly. Never printed. */
-    token?: string;
     /** This node's type (WP §3.1): bounds the role it may exercise; the runtime grants the role. */
     type: ClientType;
     /** This node's name `[a-z0-9_-]{1,64}`; minted (`<type>-<6 hex>`) when absent and kept across reconnects. */
     name?: string;
-    /** Shared across one human's clients so they are promoted and demoted together (WP §3.5); a `web`/`hmi` node without one mints one. */
+    /** Shared across one human's web clients so they are promoted and demoted together (WP §3.5; an hmi is never promoted or demoted); a `web`/`hmi` node without one mints one. */
     userId?: string;
     /** Reserved for signed credentials. */
     credential?: string;
-    /** Pin of the broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned. */
-    brokerCertSha256?: string;
     /** Time-domain id override (WP §7.3); default per runtime. */
     domId?: string;
     /** Standing project intent (WP §3.5), sent with the connect request. */
     project?: "operator";
-    /** `null` = no reconnect: a dropped session ends the node `closed`. Default: 100 ms → 10 s, ×2, jitter, unlimited. */
+    /** `null` = no reconnect: a dropped session leaves the node `failed` (resting; `connect()` dials again). Default: 100 ms → 10 s, ×2, jitter, unlimited. */
     reconnect?: ReconnectPolicy | null;
     transport?: Transport;
     connectTimeoutMs?: number;
@@ -45,18 +36,34 @@ export interface ConnectOptions {
     /** Bun/Node: close cleanly on SIGINT/SIGTERM (default true). */
     signals?: boolean;
 }
-/** Where the node should be connected: the argument of `setTarget` (fields left out keep the node's current ones). */
+/** Where the node should be connected: the argument of `connect()` (identity fields left out keep the node's current ones). */
 export interface ConnectTarget {
+    /**
+     * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
+     * the runtime's path, `https://relay:4443/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     */
     url: string;
+    /** The type to declare there; left out keeps the node's current one. */
     type?: ClientType;
+    /** The name to declare there; left out keeps the node's current one. */
     name?: string;
+    /** The user id to declare there; left out keeps the node's current one. */
     userId?: string;
+    /** The credential to present there; left out keeps the node's current one. Never printed. */
     credential?: string;
+    /** Pin of *this* broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned (per attempt). */
     brokerCertSha256?: string;
-    /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). */
+    /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). Never printed. */
     token?: string;
 }
+/**
+ * Where the node stands. `idle`: no target (constructed and not yet `connect()`ed, or after `disconnect()`). `failed`:
+ * the dialing gave up (`unauthorized`, the bounded `connect()` timed out, the reconnect policy declined); the node rests
+ * there and a later `connect()` dials again. `closed`: after `close()`, for good.
+ */
 export type ConnectionState = {
+    status: "idle";
+} | {
     status: "connecting";
     attempt: number;
 } | {
@@ -205,12 +212,15 @@ export interface ViewOptions<T, S> extends SubscribeOptions {
     staleTime?: number;
     select?: (v: T) => S;
 }
-/** A topic's value now, as a cell: `get()` any time, `subscribe` for changes (the framework bridge), `changed()` for the next one; subscribed from creation until `close()`. */
+/** A topic's value now, as a state value: `get()` any time, `onChange` for each change (the framework bridge), `changed()` for the next one, `watch()` for each one in a loop; subscribed from creation until `close()`. */
 export interface View<S> extends AsyncDisposable {
     get(): ViewState<S>;
-    subscribe(listener: () => void): () => void;
+    /** `cb` with the state on each change; returns the remover. */
+    onChange(cb: (state: ViewState<S>) => void): () => void;
     ready(): Promise<void>;
     changed(): Promise<ViewState<S>>;
+    /** The state after each change (state, not history: changes in between fold into the latest); ends when the view is closed or the node ends. */
+    watch(): AsyncIterable<ViewState<S>>;
     close(): void;
 }
 export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "canceled";
@@ -306,18 +316,25 @@ export type StoreChange = {
     by: string | undefined;
 };
 /**
- * A namespace as a value kept current (SDK §9): `value`/`get` read it, `set`/`delete` resolve once the
- * value shows the write, `synced` says whether it is current, `watch()` follows changes. The runtime
- * decides every write (`not_owner`, `unauthorized`, `store_gone`).
+ * A namespace as a value kept current (SDK §9): `get()` reads it, `set`/`delete` resolve once the
+ * value shows the write, `synced` says whether it is current, `onChange`/`watch()` follow changes. The runtime
+ * decides every write (`not_owner`, `unauthorized`, `store_gone`). A write made while the handle is
+ * between incarnations (its intent being replayed, e.g. after a project activation) waits for the
+ * handle to bind again and is decided then; it is refused `store_gone` only if the handle ends first.
  */
 export interface StoreHandle extends AsyncDisposable {
     readonly name: string;
     /** The whole value, what the runtime has (the same object while nothing changed). */
-    readonly value: Record<string, unknown>;
+    get(): Record<string, unknown>;
+    /** One key's value (`undefined` when absent). */
     get(key: string): unknown;
+    /** The one boolean a node author checks: `status.get().synced`. */
     readonly synced: boolean;
-    readonly status: StoreStatus;
-    /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `value` shows it. */
+    /** The handle's own state, a state value: `get()` now (the same object while unchanged), `onChange` for each change, `changed()` for the next. */
+    readonly status: StateValue<StoreStatus>;
+    /** Resolves once the first value is in (the first snapshot applied, or the namespace absent). */
+    ready(): Promise<void>;
+    /** `set(key, value)`, or `set({ ... })` for several keys as one atomic write; resolves once `get()` shows it. */
     set(key: string, value: unknown): Promise<void>;
     set(values: Record<string, unknown>): Promise<void>;
     delete(key: string): Promise<void>;
@@ -326,8 +343,10 @@ export interface StoreHandle extends AsyncDisposable {
     destroy(): Promise<void>;
     /** The whole value after each change; with `key`, that key's value each time it changes (`undefined` after a delete). */
     watch(key?: string): AsyncIterable<unknown>;
-    /** The framework bridge (React): called on every change of the value or the status. */
-    subscribe(listener: () => void): () => void;
+    /** The whole value after its next change; `store_gone` once this handle is closed. */
+    changed(): Promise<Record<string, unknown>>;
+    /** `cb` with the whole value on every change of the value or the status (the framework bridge); returns the remover. */
+    onChange(cb: (value: Record<string, unknown>) => void): () => void;
     close(): void;
 }
 export type Vec3 = [number, number, number];
@@ -341,6 +360,11 @@ export interface Xform {
 }
 /** Which plane an entity lives in: `authored` (the project's), `calibration` (the robot's), `live` (never persisted). */
 export type SceneLayer = "authored" | "calibration" | "live";
+/**
+ * What an entity is. Any string is a kind; these are offered for completion: `frame` and `robot` are the two the runtime
+ * gives meaning to, `model` and `scan` the common others.
+ */
+export type SceneKind = "frame" | "robot" | "model" | "scan" | (string & {});
 /** Each flag holds only when it is `true`. `locked` refuses patch/reparent/rename/despawn (a flags-only patch passes). */
 export interface SceneFlags {
     locked?: boolean;
@@ -414,8 +438,11 @@ export interface Hardpoint {
 export interface SceneEntity {
     /** A ULID; never changes. */
     id: string;
-    kind: string;
-    /** Unique across the authored and calibration planes. */
+    kind: SceneKind;
+    /**
+     * Unique across every plane (authored, calibration, live): a write that would give an entity a name another entity
+     * holds is refused `name_taken`, its `data.holder` the id holding the name.
+     */
     name?: string;
     /** The parent's id; `null` is the world root. */
     parent: string | null;
@@ -450,7 +477,7 @@ export interface SceneEntity {
     [key: string]: unknown;
 }
 /**
- * An id's live row (`scene.entity(id, { plane: "live" })`), each key present only when the row has it:
+ * An id's live row (`view.live.get()`), each key present only when the row has it:
  * `entity` is a live-layer entity's upsert row; `pose`, `joints`, `state` are the lanes; `stamp` is the
  * newest lane stamp (the runtime's clock).
  */
@@ -476,15 +503,96 @@ export interface SceneTreeNode {
 export type SceneTree = SceneTreeNode[];
 /**
  * A value of the scene, kept current: `get()` the value now (the same object until it changes),
- * `subscribe` for each change (the framework bridge), `changed()` for the next one. It reads the
- * handle's copy of the scene (no subscription of its own) and ends with the handle.
+ * `onChange` for each change (the framework bridge), `changed()` for the next one, `watch()` for each one in a
+ * loop. It reads the handle's copy of the scene (no subscription of its own) and ends with the handle.
  */
 export interface SceneView<T> {
     get(): T;
-    subscribe(listener: () => void): () => void;
-    /** Resolves with the value after its next change (with the value as it is when the handle closes). */
+    /** `cb` with the value on each change; returns the remover. */
+    onChange(cb: (value: T) => void): () => void;
+    /** The value after each change (state, not history: changes in between fold into the latest); ends with the handle. */
+    watch(): AsyncIterable<T>;
+    /** Resolves with the value after its next change relative to the value at the call: a change already readable when it is called is not its change (with the value as it is when the handle closes). */
     changed(): Promise<T>;
 }
+/** Which entity an entity view follows: an id (that entity only), or a name (whichever entity holds it now, on any plane). */
+export type SceneEntityRef = string | {
+    name: string;
+};
+/**
+ * One entity as a view (`scene.entity(id)`, `scene.entity({ name })`), shaped like a store handle: `get()` is the
+ * merged entity now (authored with its live overrides; `undefined` when there is none), `get(component)` one of its
+ * components; `watch()` follows it. It is a `SceneView` too (`onChange`, `changed()`), so it fits wherever a view
+ * does. The scene's two planes are its two namespaces: `authored` (`get`, `set`: the entity as declared, one patch)
+ * and `live` (`get`: the live row with its `stamp`; `set`: the lanes; `remove`: the row). They have no `watch`,
+ * `onChange` or `changed` of their own: the view's cover the entity, whichever plane changed.
+ *
+ * A view by name follows the name: when the entity holding it is despawned and another takes the name, the view
+ * reads the new one (a view by id reads `undefined` from then on).
+ */
+export interface SceneEntityView extends SceneView<SceneEntity | undefined> {
+    /**
+     * The id of the entity the view names now: a view by id (what `upsert` returns), its id; a view by name, the id
+     * holding the name now (none holds it: `not_found`, `data: { name }`).
+     */
+    readonly id: string;
+    /** The merged entity now; `undefined` when there is none (absent, or the handle detached or closed). */
+    get(): SceneEntity | undefined;
+    /** One component of the merged entity now (`get("xform")`); `undefined` when the entity or the component is absent. */
+    get<K extends keyof SceneEntity & string>(component: K): SceneEntity[K] | undefined;
+    /** The entity's authored plane: one object for the view's life. */
+    readonly authored: EntityAuthored;
+    /** The entity's live plane: one object for the view's life. */
+    readonly live: EntityLive;
+    /**
+     * The entity after each change (`undefined` once it is gone); with `component`, that component each time it
+     * changes. It is state, not history: changes in between are folded, the latest wins. Ends with the handle.
+     */
+    watch(): AsyncIterable<SceneEntity | undefined>;
+    watch<K extends keyof SceneEntity & string>(component: K): AsyncIterable<SceneEntity[K] | undefined>;
+}
+/** An entity view's authored plane (`view.authored`). Reads as the view does: nothing once the handle is detached or closed. */
+export interface EntityAuthored {
+    /** The entity as declared (the authored entity, or a live entity's upsert row), without the live lanes; its object changes only when that value does. */
+    get(): SceneEntity | undefined;
+    get<K extends keyof SceneEntity & string>(component: K): SceneEntity[K] | undefined;
+    /**
+     * `set(component, value)`, or `set({ ...components })` for several: one `patch` of the authored entity the view
+     * names now (by name: the id holding the name at the call), resolved once the entities show it; the runtime's
+     * refusal is the error. A view by id sends the patch as `scene.authored.patch(id, …)` does (an id the runtime does
+     * not have: its `not_found`). A view by name whose name no entity holds has no id to send to: `not_found`
+     * (`data: { name }`), nothing sent. Detached: `project_inactive`.
+     */
+    set<K extends keyof SceneEntity & string>(component: K, value: SceneEntity[K]): Promise<void>;
+    set(components: Partial<SceneEntity>): Promise<void>;
+}
+/** An entity view's live plane (`view.live`). Reads as the view does: nothing once the handle is detached or closed. */
+export interface EntityLive {
+    /** The entity's live row ({@link SceneEntityLive}, its `stamp` included); `undefined` without one. */
+    get(): SceneEntityLive | undefined;
+    get<K extends keyof SceneEntityLive & string>(component: K): SceneEntityLive[K] | undefined;
+    /**
+     * Writes the live lanes of the entity the view names now, as one `scene.live.batch` (synchronous, like `publish`):
+     * `xform: { t, q }` the pose lane (both required, nothing else), `joints` the joints lane, `state` the state lane; any
+     * other component is `invalid_input`. `lifetimeMs`: the override expires that long after its last write (the entity's
+     * authored values show again); a live entity keeps the lifetime it was upserted with. The first write for an id this
+     * node has not claimed asks the claim (see `scene.live.batch`), so a single write lands. A view by name whose name no
+     * entity holds: `not_found`. Not attached: dropped and counted (`status.get().detachedDrops`). Closed, or the node
+     * ended: `not_connected`.
+     */
+    set(components: {
+        xform?: {
+            t: Vec3;
+            q: Quat;
+        };
+        joints?: Record<string, number>;
+        state?: Record<string, unknown>;
+    }, opts?: {
+        lifetimeMs?: number;
+    }): void;
+    /** Releases this node's claim of the entity the view names now (`scene.live.remove(id)`, the call): the runtime retracts its live row. */
+    remove(): Promise<void>;
+}
 /** `attached`: the scene of the active project is in; `detached`: none is (no project active, a session gap, between incarnations); `closed`: for good. */
 export type SceneState = "attached" | "detached" | "closed";
 export interface SceneStatus {
@@ -496,10 +604,12 @@ export interface SceneStatus {
     /** The authored plane's version and hash as this handle has them (0 and "" while detached). */
     version: number;
     hash: string;
-    /** `live()` batches dropped because the handle was not attached. */
+    /** Live writes (`scene.live.batch`, `view.live.set`) dropped because the handle was not attached. */
     detachedDrops: number;
+    /** Lane rows dropped because their id's claim was refused (rows parked while it was asked, and rows written while refused). */
+    unclaimedDrops: number;
 }
-/** An authored change as the runtime applied it (the `watchChanges` feed). */
+/** An authored change as the runtime applied it (a diff op of the scene's `authored` track). */
 export type SceneDiffOp = {
     op: "spawn";
     entity: SceneEntity;
@@ -563,27 +673,27 @@ export type SceneOp = {
  */
 export type SceneSpawnOptions = {
     name: string;
-    parent?: string | null;
+    parent?: string | SceneEntityView | null;
     id?: string;
 } & Partial<Omit<SceneEntity, "id" | "kind" | "name" | "parent" | "order" | "meta">>;
-/** Where `reparent` puts the entity among its new siblings (default: after the last). */
+/** Where `reparent` puts the entity among its new siblings (default: after the last): a sibling by its id or its view. */
 export type ScenePlace = {
-    before: string;
+    before: string | SceneEntityView;
 } | {
-    after: string;
+    after: string | SceneEntityView;
 };
-/** One authoring batch being built (`txn`): sent as one atomic `apply`. */
+/** One authoring batch being built (`txn`): sent as one atomic `apply`. An entity is named by its id or by a view of it (`upsert`'s result). */
 export interface SceneTxn {
     /** Spawns an entity of `kind`; returns its id. */
-    spawn(kind: string, opts: SceneSpawnOptions): string;
-    /** Sets components of `id` (an object merges into an object one level deep). */
-    patch(id: string, set: Partial<SceneEntity>): void;
-    rename(id: string, name: string): void;
-    reparent(id: string, parent: string | null, place?: ScenePlace): void;
-    despawn(id: string, opts?: {
+    spawn(kind: SceneKind, opts: SceneSpawnOptions): string;
+    /** Sets components of the entity (an object merges into an object one level deep). */
+    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): void;
+    rename(entity: string | SceneEntityView, name: string): void;
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): void;
+    despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): void;
-    setLocked(id: string, locked: boolean): void;
+    setLocked(entity: string | SceneEntityView, locked: boolean): void;
     /** The ops as they will be sent. */
     readonly ops: readonly SceneOp[];
 }
@@ -600,77 +710,131 @@ export interface LiveState {
     id: string;
     s: Record<string, unknown>;
 }
-/** One live batch: live entities (`layer: "live"`), lane overrides, removals; `lifetimeMs` makes the override rows it touches expire. */
+/**
+ * One live batch: data only, the lanes (`poses`, `joints`, `state`). `lifetimeMs` makes the override rows the batch
+ * touches expire. Claims are calls, never rows: `scene.live.upsert` and `scene.live.remove`.
+ */
 export interface LiveBatch {
-    upsert?: SceneEntity[];
     poses?: LivePose[];
     joints?: LiveJoints[];
     state?: LiveState[];
-    remove?: string[];
     lifetimeMs?: number;
+    upsert?: never;
+    remove?: never;
 }
-/** A live row removed: the writer removed it, its lifetime ran out, or its writer left. */
+/** A live row removed: the writer removed it, its lifetime ran out, its writer left, or its entity (or a parent) was despawned (the claim is released). */
 export interface LiveRemoved {
     id: string;
-    by: "explicit" | "timeout" | "writer_gone";
+    by: "explicit" | "timeout" | "writer_gone" | "despawned";
+}
+/**
+ * The authored plane's verbs (`scene.authored`): the editor's (`spawn`, `patch`, `rename`, `reparent`, `despawn`,
+ * `setLocked`, `txn`, `apply`) and the node author's `upsert`. Every write goes to the runtime, which decides it, and
+ * resolves once the entities show it; a refusal is the runtime's error. Detached: `project_inactive`. An entity is
+ * named by its id or by a view of it.
+ */
+export interface SceneAuthored {
+    /** One atomic batch; `base`: the version its structural ops assume. */
+    apply(ops: SceneOp[], base?: number): Promise<void>;
+    /** The ops `build` makes, as one atomic batch. */
+    txn(build: (t: SceneTxn) => void): Promise<void>;
+    /** Spawns an entity; its id, once the entities show it. */
+    spawn(kind: SceneKind, opts: SceneSpawnOptions): Promise<string>;
+    patch(entity: string | SceneEntityView, set: Partial<SceneEntity>): Promise<void>;
+    /**
+     * A builder's one verb, keyed by `name`; resolves with the entity's view (by id: that entity) once the entities show
+     * it. No authored entity of that name: `spawn(kind, { name, parent, ...components })`. One of `kind`: its authored
+     * value is compared with what `patch(id, components)` would make of it (one-level merge; live overrides never
+     * count): equal, nothing is sent; else a patch of the components that differ. `parent` is used by the spawn only: an
+     * existing entity is not reparented. One of another kind, or a name a live entity holds: the spawn is sent and the
+     * runtime answers (`name_taken`, `data.holder`, while the name is held; the copy here may be stale). An `id`
+     * component: `invalid_input` (`data: { component: "id" }`), nothing sent.
+     */
+    upsert(kind: SceneKind, opts: SceneSpawnOptions & {
+        id?: never;
+    }): Promise<SceneEntityView>;
+    rename(entity: string | SceneEntityView, name: string): Promise<void>;
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): Promise<void>;
+    despawn(entity: string | SceneEntityView, opts?: {
+        cascade?: boolean;
+    }): Promise<void>;
+    setLocked(entity: string | SceneEntityView, locked: boolean): Promise<void>;
+}
+/**
+ * The live plane's verbs (`scene.live`). Decisions are calls, data is streams (PLAN v0.31): a claim is the call
+ * `synapse/scene/live/upsert` (`upsert`), a release the call `synapse/scene/live/remove` (`remove`); the lanes go on this
+ * node's live track (made on the first write of each session), synchronously like `publish` (`batch`, `view.live.set`).
+ * The runtime decides identity and ownership; nothing here reads the entities to decide what to send.
+ */
+export interface SceneLive {
+    /**
+     * One batch of lanes (the sim's one call per tick); returns at once. A row goes out only for an id this node claimed in
+     * the bound incarnation: a live entity of its `upsert`, or the override of an entity of the scene, which the first row
+     * of its id asks for (the call `upsert {id}`, once). Until the answer the latest row of each lane of that id is kept
+     * (latest wins) and sent once the claim is granted, so a single write lands; a refusal drops them (counted in
+     * `status.get().unclaimedDrops` with the rows written while refused), is a node notice (`node.notices`) and is asked
+     * again, paced, by a later row. The runtime stamps the rows; a row it does not apply comes back on `watchLiveDenied`.
+     * Not attached: dropped and counted (`status.get().detachedDrops`). Closed: `not_connected`. Never sent again.
+     */
+    batch(batch: LiveBatch): void;
+    /**
+     * A live entity of this node's: the call `synapse/scene/live/upsert {kind, name?, parent, lifetime_ms?, ...components}`;
+     * resolves with its view (by the id the runtime answered: minted for a new one; a name this node already claimed sends
+     * that claim's id). Rejects with the runtime's refusal as it came (`name_taken {name, id, holder}`, `not_owner`,
+     * `conflict`, `invalid_tree`, `project_inactive`, `unauthorized`, ...): nothing is kept. Granted, it is this node's claim:
+     * claimed again, same id, on every attach (a new session, a project switch, a scene restart; a refused re-claim is
+     * asked again, paced, with a warning), until `remove`. A session that goes before the answer: asked at the next
+     * attach. Detached: `project_inactive`; the node ending: `not_connected`. An `id` component: `invalid_input`
+     * (`data: { component: "id" }`), nothing sent.
+     */
+    upsert(kind: SceneKind, opts?: Omit<SceneSpawnOptions, "name" | "id"> & {
+        name?: string;
+        id?: never;
+    }, live?: {
+        lifetimeMs?: number;
+    }): Promise<SceneEntityView>;
+    /** Releases this node's claim of the entity: the call `synapse/scene/live/remove {id}` (the runtime retracts its row); the claim is not made again. Not held in the bound incarnation: resolves at once. */
+    remove(entity: string | SceneEntityView): Promise<void>;
 }
 /**
  * The active project's scene as this node sees it (PLAN v0.24 §5): authored ⊕ live, kept current.
- * Views and feeds read the handle's copy of the scene; every write goes to the runtime, which
- * decides it, and resolves once the entities show it.
+ * Views and feeds read the handle's copy of the scene; the writes are in `authored` (the authored plane) and `live`
+ * (this node's live rows).
  */
 export interface SceneHandle extends AsyncDisposable {
     /** The entities now, authored with the live overrides applied; the same object while nothing changed. */
-    readonly entities: Readonly<Record<string, SceneEntity>>;
+    get(): Readonly<Record<string, SceneEntity>>;
     /**
-     * One entity as a view (`undefined` when it is not in the scene). `plane` reads one layer alone and
-     * the view changes only when that layer's value for the id does: `authored` is the entity as
-     * declared without the live lanes (the authored entity, or a live entity's upsert row); `live` is
-     * the id's live row (`SceneEntityLive`), `undefined` without one. Without `plane`: merged.
+     * One entity as a view ({@link SceneEntityView}), by id or by name (`entity({ name: "tool" })`: the entity holding
+     * the name now): merged, authored with its live overrides; one plane alone through the view (`view.authored`, `view.live`).
      */
-    entity(id: string, opts?: {
-        plane?: "authored";
-    }): SceneView<SceneEntity | undefined>;
-    entity(id: string, opts: {
-        plane: "live";
-    }): SceneView<SceneEntityLive | undefined>;
-    entity(id: string, opts?: {
-        plane?: "authored" | "live";
-    }): SceneView<SceneEntity | SceneEntityLive | undefined>;
+    entity(ref: SceneEntityRef): SceneEntityView;
     /** The hierarchy as a view. */
     tree(): SceneView<SceneTree>;
     /** The entities for which `where` holds (in id order), as a view. */
     query(where: (e: SceneEntity) => boolean): SceneView<SceneEntity[]>;
-    readonly status: SceneStatus;
-    /** The authored changes, one batch per applied change. */
-    watchChanges(cb: (batch: SceneDiffOp[]) => void): () => void;
-    watchChanges(): AsyncIterableIterator<SceneDiffOp[]>;
+    /** The handle's own state, a state value: `get()` now (the same object while unchanged), `onChange` for each change, `changed()` for the next. */
+    readonly status: StateValue<SceneStatus>;
+    /** The one boolean a node author checks: `status.get().synced`. */
+    readonly synced: boolean;
+    /** Resolves once the handle is attached (at once if it is); `not_connected` once the handle is closed. No timeout: pass an `AbortSignal` to what awaits it, or race it. */
+    ready(): Promise<void>;
+    /** The entities after their next change (state, not history); `not_connected` once the handle is closed. */
+    changed(): Promise<Readonly<Record<string, SceneEntity>>>;
+    /** The entities after each change (state, not history: changes in between fold into the latest); ends with the handle. */
+    watch(): AsyncIterable<Readonly<Record<string, SceneEntity>>>;
+    /** `cb` with the entities on every change of the entities or the status (the framework bridge); returns the remover. */
+    onChange(cb: (entities: Readonly<Record<string, SceneEntity>>) => void): () => void;
     /** The live rows removed, one batch per runtime tick that removed some. */
     watchLiveRemovals(cb: (batch: LiveRemoved[]) => void): () => void;
     watchLiveRemovals(): AsyncIterableIterator<LiveRemoved[]>;
     /** The ids of this node's live writes the runtime dropped because another writer owns them, one batch per denied batch. */
     watchLiveDenied(cb: (ids: string[]) => void): () => void;
     watchLiveDenied(): AsyncIterableIterator<string[]>;
-    /** The handle's state at each change; ends after `closed`. */
-    watchState(cb: (state: SceneState) => void): () => void;
-    watchState(): AsyncIterableIterator<SceneState>;
-    /** One atomic batch; `base`: the version its structural ops assume. Resolves once the entities show it; a refusal is the runtime's error. Detached: `project_inactive`. */
-    apply(ops: SceneOp[], base?: number): Promise<void>;
-    /** The ops `build` makes, as one atomic batch. */
-    txn(build: (t: SceneTxn) => void): Promise<void>;
-    /** Spawns an entity; its id, once the entities show it. */
-    spawn(kind: string, opts: SceneSpawnOptions): Promise<string>;
-    patch(id: string, set: Partial<SceneEntity>): Promise<void>;
-    rename(id: string, name: string): Promise<void>;
-    reparent(id: string, parent: string | null, place?: ScenePlace): Promise<void>;
-    despawn(id: string, opts?: {
-        cascade?: boolean;
-    }): Promise<void>;
-    setLocked(id: string, locked: boolean): Promise<void>;
-    /** Writes one live batch on this node's live track; returns at once (like `publish`). Not attached: dropped and counted (`status.detachedDrops`). */
-    live(batch: LiveBatch): void;
-    /** The framework bridge (React): called on every change of the entities or the status. */
-    subscribe(listener: () => void): () => void;
+    /** The authored plane's verbs. */
+    readonly authored: SceneAuthored;
+    /** This node's live writes. */
+    readonly live: SceneLive;
     /** Ends this handle: its verbs fail `not_connected`, its views and feeds end; the node's other scene handles go on. */
     close(): void;
 }
@@ -748,21 +912,28 @@ export interface TaskCatalogEntry {
 /** A value the runtime keeps current that this node only reads: it has no writes. */
 export interface ReadonlyStoreHandle<V> {
     /** The value now; the same object while nothing changed, and an unchanged part keeps its object when another part changes. */
-    readonly value: V;
+    get(): V;
     /** `true` while the value is current. */
     readonly synced: boolean;
     /** Resolves once the value is current (the first time). */
     ready(): Promise<void>;
     /** The whole value after each change. It is state, not history: a reader slower than the changes sees the latest value. */
     watch(): AsyncIterable<V>;
-    /** The framework bridge (React): called on every change of the value or of `synced`. */
-    subscribe(listener: () => void): () => void;
+    /** `cb` with the value on every change of the value or of `synced` (the framework bridge); returns the remover. */
+    onChange(cb: (value: V) => void): () => void;
 }
 /** The robot's task declarations, `instance` → declaration (operators write them). The node owns this handle: it has no `close` or `destroy`. */
-export interface TaskDeclarations extends Omit<StoreHandle, "name" | "value" | "get" | "set" | "watch" | "destroy" | "close" | typeof Symbol.asyncDispose> {
-    readonly value: Readonly<Record<string, TaskDeclaration>>;
+export interface TaskDeclarations extends Omit<StoreHandle, "name" | "get" | "set" | "watch" | "destroy" | "close" | typeof Symbol.asyncDispose> {
+    /** Every declaration, `instance` → declaration. */
+    get(): Readonly<Record<string, TaskDeclaration>>;
     get(instance: string): TaskDeclaration | undefined;
-    /** `set(instance, declaration)`, or `set({ ... })` for several as one atomic write; waits for the value to be current first, resolves once `value` shows the write. */
+    /**
+     * `set(declaration)`: a new declaration under an instance the SDK mints (a ulid), resolving with that instance;
+     * `set(instance, declaration)` writes the one named; `set({ ... })` several as one atomic write. One object is a
+     * declaration when its `ref` is a string, else a map `instance` → declaration. Each waits for the value to be current
+     * first and resolves once `get()` shows the write.
+     */
+    set(declaration: TaskDeclaration): Promise<string>;
     set(instance: string, declaration: TaskDeclaration): Promise<void>;
     set(declarations: Record<string, TaskDeclaration>): Promise<void>;
     /** The whole value after each change; with `instance`, that declaration each time it changes (`undefined` after a delete). */

package/dist/util.d.ts

@@ -5,6 +5,19 @@ export interface Deferred<T> {
     settled: boolean;
 }
 export declare function deferred<T>(): Deferred<T>;
+/**
+ * A state value (`node.status`, `node.catalog`, `node.project`, the `status` of the store, scene and tasks handles):
+ * `get()` the value now (the same object while it is unchanged), `onChange` for each change (the framework bridge;
+ * `cb` gets the value; returns the remover), `changed()` for the value after the next change (at once with the value
+ * now once the node has ended), `watch()` for the value after each change in a loop (ends when the node, or the
+ * handle, ends). Not exported from the package: no user builds one.
+ */
+export interface StateValue<T> {
+    get(): T;
+    onChange(cb: (value: T) => void): () => void;
+    changed(): Promise<T>;
+    watch(): AsyncIterable<T>;
+}
 /** A value plus listeners. `changed()` resolves on the next `set`. */
 export declare class Cell<T> {
     #private;
@@ -16,6 +29,8 @@ export declare class Cell<T> {
     changed(): Promise<T>;
     get listenerCount(): number;
 }
+/** A callback's throw, rethrown on its own microtask: the caller's loop goes on and the error still surfaces. */
+export declare const rethrowLater: (e: unknown) => void;
 export declare const DONE: unique symbol;
 /**
  * Bounded FIFO with one consumer. `push` never blocks: past `capacity` the oldest item is dropped
@@ -65,3 +80,31 @@ export declare class Ring {
     push(v: number): void;
     percentile(p: number): number | undefined;
 }
+/**
+ * The loop form of a state value (`watch()`), built from its `onChange` and `get`: the value after each change, compared
+ * by reference (a state value keeps its object while unchanged), changes in between folded into the latest (state, not
+ * history). It ends when it is told of a change once `ended()` holds; each state value tells its listeners when it ends.
+ * Leaving the loop removes the listener.
+ */
+export declare function watchState<T>(onChange: (cb: () => void) => () => void, get: () => T, ended: () => boolean): AsyncGenerator<T, void, undefined>;
+/**
+ * A handle's own state as a state value (`store.status`, `scene.status`; the `StateValue` shape): `get()` is `read()`
+ * kept the same object while every field is equal (`shallowEqual`), `onChange` calls back only when that object
+ * changes, `changed()` resolves with the next one (at once with the value now once `ended()`), `watch()` is the loop
+ * form. `source` is what tells of a possible change: the handle's own notifications.
+ */
+export declare class StatusCell<T> {
+    #private;
+    private readonly read;
+    private readonly source;
+    private readonly ended;
+    constructor(read: () => T, source: (l: () => void) => () => void, ended: () => boolean);
+    get(): T;
+    /** `cb` with the value on each change; once the handle has ended (or this state value was disposed) nothing will change: a no-op remover. */
+    onChange(cb: (value: T) => void): () => void;
+    /** The handle closed: every upstream registration is removed (after the listeners were told of the close); new subscriptions are refused. */
+    dispose(): void;
+    changed(): Promise<T>;
+    /** The value after each change; ends with the handle. */
+    watch(): AsyncIterable<T>;
+}