@synapse-sdk/client 0.3.3 → 0.3.6

package/dist/scene.d.ts

@@ -3,13 +3,15 @@ import { SynapseError, type ErrorBody, type ProjectSnapshot } from "@synapse-sdk
 import type { Node } from "./node.ts";
 import { StreamWriter, type Session } from "./session.ts";
 import type { Warn } from "./topics.ts";
-import type { LiveBatch, LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneDiffOp, SceneEntity, SceneEntityLive, SceneHandle, SceneOp, ScenePlace, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
-import { AsyncQueue, type Deferred } from "./util.ts";
+import type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, ScenePlace, SceneSpawnOptions, SceneState, SceneStatus, SceneTree, SceneTxn, SceneView, Vec3 } from "./types.ts";
+import { AsyncQueue, type Deferred, type StateValue } from "./util.ts";
 /** How many batches a feed may fall behind before it is ended (the store's `STORE_FEED_CAP`). */
 export declare const SCENE_FEED_CAP = 256;
 /** Keys a `patch` may not set (the runtime refuses them); a txn never folds such a patch into a spawn. */
 export declare const PATCH_PROTECTED: readonly string[];
 type Entities = Map<string, SceneEntity>;
+/** An entity named by its id or by a view of it (the id the view names now). */
+type EntityArg = string | SceneEntityView;
 /**
  * A fresh entity id: a ULID (26 Crockford base-32 characters) made from a UUIDv7 (48-bit ms, version,
  * 74 random bits, variant), so ids sort by the time they were minted; within one millisecond the
@@ -37,19 +39,19 @@ export declare function treeOf(entities: Readonly<Record<string, SceneEntity>>):
 export declare class Txn implements SceneTxn {
     #private;
     get ops(): readonly SceneOp[];
-    /** Spawns an entity of `kind` under `opts.parent` (default the world root) with the components given (`layer` `authored` when not given); its id is minted here (or `opts.id`, a known one) and returned. No `order` is sent: the runtime appends it after its siblings. */
-    spawn(kind: string, opts: SceneSpawnOptions): string;
-    /** Sets components of `id` (one level deep: an object merges into an object). */
-    patch(id: string, set: Partial<SceneEntity>): void;
-    rename(id: string, name: string): void;
-    /** Moves `id` under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(id: string, parent: string | null, place?: ScenePlace): void;
-    /** 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: string, opts?: {
+    /** 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: SceneKind, opts: SceneSpawnOptions): string;
+    /** Sets components of the entity (one level deep: an object merges into an object). */
+    patch(entity: EntityArg, set: Partial<SceneEntity>): void;
+    rename(entity: EntityArg, name: string): void;
+    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
+    reparent(entity: EntityArg, parent: EntityArg | null, place?: ScenePlace): void;
+    /** 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: EntityArg, opts?: {
         cascade?: boolean;
     }): void;
-    /** Locks or unlocks `id` (a flags-only patch, which a lock lets through). */
-    setLocked(id: string, locked: boolean): void;
+    /** Locks or unlocks the entity (a flags-only patch, which a lock lets through). */
+    setLocked(entity: EntityArg, locked: boolean): void;
 }
 /**
  * Applies one diff op of a batch the runtime stamped `t` by `by` to the authored entities (the
@@ -57,8 +59,6 @@ export declare class Txn implements SceneTxn {
  * `meta` is `{rev, t, by}`, as the runtime stamped it.
  */
 export declare function foldAuthored(authored: Entities, op: SceneDiffOp, t: number, by: string | null): string[];
-/** 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 declare function netDifference(old: Entities, next: Entities): SceneDiffOp[];
 /** One live row as this node keeps it: the whole live entity of an upsert (absent: an override of an authored entity), the lanes, and the newest lane stamp (the runtime's clock). */
 export interface LiveRow {
     entity?: SceneEntity;
@@ -85,6 +85,10 @@ export interface LiveFrame {
 }
 /** A keyframe as a fresh live table. */
 export declare function liveTableOf(k: LiveFrame): LiveTable;
+/** The authored or calibration entity named `name` (live overrides never count). */
+export declare function authoredNamed(authored: Entities, name: string): SceneEntity | undefined;
+/** The id of the live entity named `name` (a lane-only row carries no name). */
+export declare function liveNamed(live: LiveTable, name: string): string | 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 declare function foldLive(table: LiveTable, d: LiveFrame): string[];
 /** The merged read of one entity: the pose lane replaces `xform.t`/`xform.q` (the rest of the xform stays), the joints lane replaces `joints`, the state lane replaces `state`; nothing merges deeper. */
@@ -93,9 +97,8 @@ export declare function overlay(entity: SceneEntity, row: LiveRow): SceneEntity;
 export declare function liveValue(row: LiveRow): SceneEntityLive;
 /** `id` as the entities show it: its live row over its authored entity, or a live entity's own row. */
 export declare function mergedOf(authored: Entities, live: LiveTable, id: string): SceneEntity | undefined;
-type FeedKind = "changes" | "removals" | "denied" | "states";
+type FeedKind = "removals" | "denied" | "states";
 interface FeedItems {
-    changes: SceneDiffOp[];
     removals: LiveRemoved[];
     denied: string[];
     states: SceneState;
@@ -129,8 +132,10 @@ export declare class Mirror {
     epoch: string | undefined;
     version: number;
     hash: string;
-    /** An authored diff skipped a version; cleared by the next snapshot. */
-    gap: boolean;
+    /** An authored diff skipped a version (not applied; the track is read again from its snapshot): the highest version seen then. Cleared once the copy is back at it (PLAN v0.34 §2.2). */
+    gap: number | undefined;
+    /** The live track's first keyframe of the incarnation is in the copy. */
+    liveKeyed: boolean;
     pending: number;
     authored: Entities;
     live: LiveTable;
@@ -143,12 +148,16 @@ export declare class Mirror {
     dropHandle(id: number): void;
     /** The hierarchy now (recomputed only after a change of the ids, a parent or an order; the same object while equal). */
     tree(): SceneTree;
-    /** 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. The first one is not yet `attached`: that is the task's, once the copy is at the version the open answered. */
     applySnapshot(epoch: string, s: Snapshot): void;
-    /** The reader has applied everything this node held when it bound the incarnation. */
+    /** The copy is current as of the attach (the task checked it): `attached`. */
     attach(): void;
-    /** One applied batch: its ops folded into the authored copy; the feeds get them as they came. */
-    applyDiff(d: Diff, warn: Warn): void;
+    /**
+     * One applied batch: its ops folded into the authored copy, when it is the next version. Otherwise it is not applied
+     * (`false`): a gap, `synced` false until the copy is back at the version seen; the reader reads the track again from
+     * its snapshot (PLAN v0.34 §2.2).
+     */
+    applyDiff(d: Diff, warn: Warn): boolean;
     /** A keyframe replaces the live table. */
     applyKeyframe(k: LiveFrame): void;
     /** One tick folded into the live table; its removals go to the feeds. */
@@ -156,7 +165,7 @@ export declare class Mirror {
     /** Ids of this node's live rows the runtime dropped. */
     denied(ids: string[]): void;
     setPending(n: number): void;
-    /** No incarnation: the copy empties (the change feeds see the despawns), `detached`. */
+    /** No incarnation: the copy empties, `detached`. */
     detach(): void;
     /** The end: emptied, `closed` (`reason` recorded), every feed ended. */
     close(reason: string): void;
@@ -174,12 +183,23 @@ type Event = {
 } | {
     kind: "nodeEnded";
 }
+/** The answer of `synapse/scene/open` of attempt `attempt`. */
+ | {
+    kind: "opened";
+    attempt: number;
+    result: Result<unknown>;
+}
 /** The reader applied an authored frame of incarnation `epoch`: the mirror is at `version`. */
  | {
     kind: "applied";
     epoch: string;
     version: number;
 }
+/** The reader applied the live track's first keyframe of incarnation `epoch`. */
+ | {
+    kind: "liveKeyed";
+    epoch: string;
+}
 /** The reader of attempt `attempt` ended: the incarnation it bound and its final frame's reason (none: the tracks or the session went). */
  | {
     kind: "followEnded";
@@ -210,9 +230,47 @@ type Event = {
 } | {
     kind: "paced";
     attempt: number;
+}
+/** `live.upsert`: a live entity's claim (its args, no id); answered with the id the runtime decided. */
+ | {
+    kind: "upsert";
+    args: Record<string, unknown>;
+    reply: Deferred<string>;
+}
+/** `live.remove`. */
+ | {
+    kind: "remove";
+    id: string;
+    reply: Deferred<void>;
+}
+/** A lane write asked the claim of `id` (marked asked by the handle). */
+ | {
+    kind: "claim";
+    id: string;
+}
+/** The runtime's answer to a claim asked in attach `bind`. */
+ | {
+    kind: "claimDone";
+    ask: Ask;
+    bind: number;
+    result: Result<unknown>;
+}
+/** A refused live entity may be due to be asked again. */
+ | {
+    kind: "reclaim";
 } | {
     kind: "close";
 };
+/** A claim being asked: a `live.upsert` (its args, its caller), or one of this node's claims asked again. */
+type Ask = {
+    kind: "first";
+    args: Record<string, unknown>;
+    reply: Deferred<string>;
+    token: number;
+} | {
+    kind: "again";
+    id: string;
+};
 /** This node's live writer: the session's `<prefix>/scene/live` broadcast and its track `live`. */
 interface LiveWriter {
     session: Session;
@@ -220,6 +278,51 @@ interface LiveWriter {
     stream: StreamWriter;
     seq: number;
 }
+/** Where one of this node's claims stands in the bound incarnation. */
+type ClaimState = 
+/** Not claimed in the bound incarnation (none bound, or not asked yet). */
+{
+    kind: "unclaimed";
+}
+/** Asked (or about to be, by the task): lane rows are parked until the answer. */
+ | {
+    kind: "asking";
+}
+/** The runtime granted it in the bound incarnation: lane rows go out. */
+ | {
+    kind: "claimed";
+}
+/**
+ * Asked again from `at` (`performance.now()` ms) on. `refused`: the runtime refused it (rows are dropped until then; a
+ * live entity is asked by the task's timer, an override by its next lane write once due); not refused: a transient
+ * answer (rows keep parking; the task's timer asks it).
+ */
+ | {
+    kind: "paced";
+    at: number;
+    refused: boolean;
+};
+/** The latest lane rows of one id written while its claim is not answered yet: one slot per lane, latest wins (state, not history), sent once the claim is granted, dropped on a refusal. */
+interface Parked {
+    pose?: LivePose;
+    joints?: LiveJoints;
+    state?: LiveState;
+    lifetimeMs?: number;
+}
+/** One of this node's claims: its own intent, never world state. */
+declare class Claim {
+    readonly args: Record<string, unknown>;
+    state: ClaimState;
+    /** Refusals of it in a row (the pace of the next ask). */
+    refusals: number;
+    parked: 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: Record<string, unknown>, state: ClaimState);
+    /** A live entity (claimed again on every attach), not an override (claimed by its lanes). */
+    get isEntity(): boolean;
+}
+/** What the lane gate does with a row: sent now (claimed), parked (the claim is not answered yet), dropped and counted (refused, not due again). */
+type Gate = "send" | "park" | "drop";
 /** The node's scene: what every handle shares with the task. */
 export declare class Scene {
     readonly node: Node;
@@ -230,11 +333,24 @@ export declare class Scene {
     /** Handles neither closed nor dropped; the one that brings it to 0 tells the task `close`. */
     handles: number;
     nextHandle: number;
-    /** 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: LiveWriter | undefined;
+    /** This node's claims by id (what `live.upsert` made and what lane writes asked for); `live.remove` drops one. Nothing else is kept. */
+    readonly claims: Map<string, Claim>;
     detachedDrops: number;
+    /** Lane rows dropped because their id's claim was refused (and not due again), or parked rows a refusal dropped. */
+    unclaimedDrops: number;
+    /** Told when a counter of the status changes (the listeners of the status state values). */
+    readonly counters: Set<() => void>;
     constructor(node: Node, warn: Warn);
     post(e: Event): boolean;
+    countersChanged(): void;
+    /**
+     * 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: string, now: number, ask: string[]): Gate;
     request<T>(make: (reply: Deferred<T>) => Event): Promise<T>;
 }
 /** The node's one scene task, if any (set with the task, cleared by the task when it exits). */
@@ -246,54 +362,43 @@ export declare function startScene(scene: Scene, registry: SceneRegistry): void;
 export declare class SceneHandleImpl implements SceneHandle {
     #private;
     private readonly scene;
+    /** The authored plane's verbs. */
+    readonly authored: SceneAuthored;
+    /** This node's live writes. */
+    readonly live: SceneLive;
+    /** The handle's own state, a state value: `get()` (the same object while unchanged), `onChange`, `changed()`, `watch()`. */
+    readonly status: StateValue<SceneStatus>;
     constructor(scene: Scene);
-    get entities(): Readonly<Record<string, SceneEntity>>;
-    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>;
+    /** The merged entities now; a closed handle reads nothing (the mirror may live on for the node's other handles). */
+    get(): Readonly<Record<string, SceneEntity>>;
+    /** One entity as a view: the merged entity, with its authored value (`authored`) and its live row (`live`). */
+    entity(ref: SceneEntityRef): SceneEntityView;
     tree(): SceneView<SceneTree>;
     query(where: (e: SceneEntity) => boolean): SceneView<SceneEntity[]>;
-    get status(): SceneStatus;
-    watchChanges(cb: (batch: SceneDiffOp[]) => void): () => void;
-    watchChanges(): AsyncIterableIterator<SceneDiffOp[]>;
+    /** The one boolean a node author checks: `status.get().synced`. */
+    get synced(): boolean;
+    /** Resolves once the handle is attached (at once if it is); `not_connected` once it is closed (`close()`, or the node ending). */
+    ready(): Promise<void>;
+    /** The entities after their next change (state, not history); `not_connected` once this handle is closed. */
+    changed(): Promise<Readonly<Record<string, SceneEntity>>>;
+    /** The entities after each change; ends with the handle. */
+    watch(): AsyncIterable<Readonly<Record<string, SceneEntity>>>;
     watchLiveRemovals(cb: (batch: LiveRemoved[]) => void): () => void;
     watchLiveRemovals(): AsyncIterableIterator<LiveRemoved[]>;
     watchLiveDenied(cb: (ids: string[]) => void): () => void;
     watchLiveDenied(): AsyncIterableIterator<string[]>;
-    watchState(cb: (state: SceneState) => void): () => void;
-    watchState(): AsyncIterableIterator<SceneState>;
-    apply(ops: SceneOp[], base?: number): Promise<void>;
-    txn(build: (t: SceneTxn) => void): Promise<void>;
-    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 (made on the first call of each session); returns
-     * at once, like `publish`. The runtime stamps the rows and owns the outcome: an id another writer owns
-     * comes back on `watchLiveDenied`, a malformed batch as a node notice. Not attached: dropped and counted.
-     */
-    live(batch: LiveBatch): void;
-    /** The framework bridge (React's hooks): called on every change of the entities or the status. */
-    subscribe(listener: () => void): () => void;
-    /** 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. */
+    /** `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: (entities: Readonly<Record<string, SceneEntity>>) => void): () => void;
+    /** 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(): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * 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.
+ * once the handle is attached (the copy at the version `synapse/scene/open` answered, or past it), or at
+ * once `detached` when the runtime says no project is active; the
+ * 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 declare function openScene(node: Node, registry: SceneRegistry, warn: Warn): Promise<SceneHandleImpl>;
 export {};