@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/scene.d.ts

@@ -0,0 +1,299 @@
+import * as Moq from "@moq/net";
+import { SynapseError, type ErrorBody, type ProjectSnapshot } from "@synapse-sdk/core";
+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";
+/** 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>;
+/**
+ * A fresh entity id: a ULID (26 Crockford base-32 characters) made from a UUIDv7 (48-bit ms, version,
+ * 74 random bits, variant), so ids sort by the time they were minted; within one millisecond the
+ * random part counts up, so ids minted here keep their order.
+ */
+export declare function ulid(): string;
+/** An `order` strictly before `order`. */
+export declare function orderBefore(order: string): string;
+/** An `order` strictly after `order`. */
+export declare function orderAfter(order: string): string;
+/** An `order` strictly between `left` and `right` (either may be open: `null`); `invalid_input` when `left >= right`. */
+export declare function orderBetween(left: string | null | undefined, right: string | null | undefined): string;
+/**
+ * The hierarchy of `entities`, as its roots: each node's children by `(order, id)` (an entity without
+ * an `order` after the ordered ones); an entity whose parent is not in the scene is a root (the
+ * prototype's rule). A cycle cannot come from the runtime; were one there, it is cut where it closes.
+ */
+export declare function treeOf(entities: Readonly<Record<string, SceneEntity>>): SceneTree;
+/**
+ * One authoring batch being built (`txn`): the ops it sends as one atomic `apply`. Ops on an entity
+ * spawned in the same batch fold into its spawn: a patch (of keys a patch may set) or a rename merges
+ * into it, a despawn cancels it (with every entity spawned under it in the batch). Nothing else is
+ * checked here: the runtime decides.
+ */
+export 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?: {
+        cascade?: boolean;
+    }): void;
+    /** Locks or unlocks `id` (a flags-only patch, which a lock lets through). */
+    setLocked(id: string, locked: boolean): void;
+}
+/**
+ * Applies one diff op of a batch the runtime stamped `t` by `by` to the authored entities (the
+ * runtime's result, as the op describes it); returns the ids whose entity changed. A changed entity's
+ * `meta` is `{rev, t, by}`, as the runtime stamped it.
+ */
+export 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;
+    pose?: {
+        t: Vec3;
+        q: Quat;
+    };
+    joints?: Record<string, number>;
+    state?: Record<string, unknown>;
+    stamp?: number;
+}
+export type LiveTable = Map<string, LiveRow>;
+/** A frame of the merged `live` track: a keyframe (the whole live set) or a tick; the runtime stamps each lane row. */
+type Stamped<T> = T & {
+    stamp?: number;
+};
+export interface LiveFrame {
+    upsert?: SceneEntity[];
+    poses?: Stamped<LivePose>[];
+    joints?: Stamped<LiveJoints>[];
+    state?: Stamped<LiveState>[];
+    remove?: LiveRemoved[];
+    keyframe?: boolean;
+}
+/** A keyframe as a fresh live table. */
+export declare function liveTableOf(k: LiveFrame): LiveTable;
+/** 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. */
+export declare function overlay(entity: SceneEntity, row: LiveRow): SceneEntity;
+/** A live row as the live plane shows it (`SceneEntityLive`): each key present only when the row has it. */
+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";
+interface FeedItems {
+    changes: SceneDiffOp[];
+    removals: LiveRemoved[];
+    denied: string[];
+    states: SceneState;
+}
+/** One feed of one handle: where its items go, and how it ends. */
+interface Sink<T> {
+    handle: number;
+    deliver(item: T): void;
+    end(): void;
+}
+/** A snapshot frame of the `authored` track. */
+interface Snapshot {
+    version: number;
+    hash: string;
+    entities: Record<string, SceneEntity>;
+}
+/** A diff frame of the `authored` track: one applied batch, with the `t` and `by` it was stamped with. */
+interface Diff {
+    version: number;
+    hash: string;
+    ops: SceneDiffOp[];
+    t: number;
+    by?: string | null;
+}
+/** What the task's reader writes and every handle reads: the scene as this node has it, and the handles' feeds. */
+export declare class Mirror {
+    #private;
+    state: SceneState;
+    /** Why the handle closed (`client`, `connection_lost`). */
+    ended: string | undefined;
+    epoch: string | undefined;
+    version: number;
+    hash: string;
+    /** An authored diff skipped a version; cleared by the next snapshot. */
+    gap: boolean;
+    pending: number;
+    authored: Entities;
+    live: LiveTable;
+    /** authored ⊕ live: the same object while nothing changed; an unchanged entity keeps its object. */
+    merged: Readonly<Record<string, SceneEntity>>;
+    subscribe(l: () => void): () => void;
+    addSink<K extends FeedKind>(kind: K, s: Sink<FeedItems[K]>): void;
+    removeSink<K extends FeedKind>(kind: K, s: Sink<FeedItems[K]>): void;
+    /** Every feed of handle `id` ends. */
+    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`). */
+    applySnapshot(epoch: string, s: Snapshot): void;
+    /** The reader has applied everything this node held when it bound the incarnation. */
+    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;
+    /** A keyframe replaces the live table. */
+    applyKeyframe(k: LiveFrame): void;
+    /** One tick folded into the live table; its removals go to the feeds. */
+    applyLiveTick(d: LiveFrame): void;
+    /** 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`. */
+    detach(): void;
+    /** The end: emptied, `closed` (`reason` recorded), every feed ended. */
+    close(reason: string): void;
+}
+type Result<T> = {
+    ok: T;
+} | {
+    err: SynapseError;
+};
+type Event = {
+    kind: "session";
+    session: Session;
+} | {
+    kind: "sessionEnded";
+} | {
+    kind: "nodeEnded";
+}
+/** The reader applied an authored frame of incarnation `epoch`: the mirror is at `version`. */
+ | {
+    kind: "applied";
+    epoch: string;
+    version: number;
+}
+/** 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";
+    attempt: number;
+    epoch: string | undefined;
+    reason: string | undefined;
+} | {
+    kind: "join";
+    reply: Deferred<void>;
+} | {
+    kind: "apply";
+    ops: SceneOp[];
+    base: number | undefined;
+    reply: Deferred<void>;
+}
+/** The runtime's answer to a batch sent on incarnation `epoch`. */
+ | {
+    kind: "applyDone";
+    epoch: string;
+    result: Result<unknown>;
+    reply: Deferred<void>;
+} | {
+    kind: "project";
+    snapshot: ProjectSnapshot | undefined;
+} | {
+    kind: "notice";
+    body: ErrorBody;
+} | {
+    kind: "paced";
+    attempt: number;
+} | {
+    kind: "close";
+};
+/** This node's live writer: the session's `<prefix>/scene/live` broadcast and its track `live`. */
+interface LiveWriter {
+    session: Session;
+    bc: Moq.Broadcast.Producer;
+    stream: StreamWriter;
+    seq: number;
+}
+/** The node's scene: what every handle shares with the task. */
+export declare class Scene {
+    readonly node: Node;
+    readonly warn: Warn;
+    readonly mirror: Mirror;
+    readonly mailbox: AsyncQueue<Event>;
+    readonly exited: Deferred<void>;
+    /** 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()`. */
+    writer: LiveWriter | undefined;
+    detachedDrops: number;
+    constructor(node: Node, warn: Warn);
+    post(e: Event): boolean;
+    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). */
+export interface SceneRegistry {
+    current: Scene | undefined;
+}
+export declare function startScene(scene: Scene, registry: SceneRegistry): void;
+/** The application's handle on the node's scene: the last one closed ends the task. */
+export declare class SceneHandleImpl implements SceneHandle {
+    #private;
+    private readonly scene;
+    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>;
+    tree(): SceneView<SceneTree>;
+    query(where: (e: SceneEntity) => boolean): SceneView<SceneEntity[]>;
+    get status(): SceneStatus;
+    watchChanges(cb: (batch: SceneDiffOp[]) => void): () => void;
+    watchChanges(): AsyncIterableIterator<SceneDiffOp[]>;
+    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. */
+    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.
+ */
+export declare function openScene(node: Node, registry: SceneRegistry, warn: Warn): Promise<SceneHandleImpl>;
+export {};