@synapse-sdk/client 0.3.7 → 0.3.8

package/dist/scene.d.ts

@@ -3,7 +3,7 @@ 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 { 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 type { LiveJoints, LivePose, LiveRemoved, LiveState, Quat, SceneAuthored, SceneDiffOp, SceneEntity, SceneEntityLive, SceneEntityRef, SceneEntityView, SceneHandle, SceneKind, SceneLive, SceneOp, 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;
@@ -12,6 +12,9 @@ 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 patch's `set` and `reparent`'s options, as the public interfaces take them. */
+type PatchSet = Parameters<SceneTxn["patch"]>[1];
+type ReparentOptions = NonNullable<Parameters<SceneTxn["reparent"]>[2]>;
 /**
  * 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
@@ -30,6 +33,14 @@ export declare function orderBetween(left: string | null | undefined, right: str
  * 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;
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export declare function mergeSet(into: Record<string, unknown>, set: Record<string, unknown>): Record<string, unknown>;
 /**
  * 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
@@ -41,11 +52,15 @@ export declare class Txn implements SceneTxn {
     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, 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;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: EntityArg, set: PatchSet): 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;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity: EntityArg, parent: EntityArg | null, opts?: ReparentOptions): 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;

package/dist/scene.js

@@ -231,14 +231,45 @@ export function treeOf(entities) {
     return build(null);
 }
 // -------------------------------------------------------------------------------------------- txn
-/** One level of the runtime's patch merge: an object merges into an object key by key; anything else replaces. */
-function mergeSet(into, set) {
+/**
+ * The runtime's patch merge (`merge_set`): merges one level deep; a null deletes the key it names. A top-level null
+ * removes the component; an object merges into an object component key by key, a null sub-key removing that sub-key;
+ * an object given for a component that is absent or not an object replaces it without its null sub-keys, and nulls
+ * alone leave no component (an explicitly given `{}` is kept); any other value replaces. `undefined` is not given (the
+ * encoder skips it).
+ */
+export function mergeSet(into, set) {
     const out = { ...into };
     for (const [k, v] of Object.entries(set)) {
         if (v === undefined)
             continue;
+        if (v === null) {
+            delete out[k];
+            continue;
+        }
+        if (!isObject(v)) {
+            out[k] = v;
+            continue;
+        }
+        const given = Object.entries(v).filter(([, s]) => s !== undefined);
         const old = out[k];
-        out[k] = isObject(old) && isObject(v) ? { ...old, ...v } : v;
+        if (isObject(old)) {
+            const next = { ...old };
+            for (const [s, sv] of given) {
+                if (sv === null)
+                    delete next[s];
+                else
+                    next[s] = sv;
+            }
+            out[k] = next;
+        }
+        else {
+            const kept = given.filter(([, s]) => s !== null);
+            if (kept.length === 0 && given.length > 0)
+                delete out[k];
+            else
+                out[k] = Object.fromEntries(kept);
+        }
     }
     return out;
 }
@@ -264,7 +295,7 @@ export class Txn {
         this.#ops.push({ op: "spawn", entity });
         return id;
     }
-    /** Sets components of the entity (one level deep: an object merges into an object). */
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
     patch(entity, set) {
         const id = idOf(entity);
         // A protected key is the runtime's to refuse: such a patch is sent as it is.
@@ -287,13 +318,19 @@ export class Txn {
         }
         this.#ops.push({ op: "rename", id, name });
     }
-    /** Moves the entity under `parent` (`null`: the world root), before or after a sibling (default: after the last). */
-    reparent(entity, parent, place) {
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (the runtime's default: nothing sent); `preserveWorld: false` sends
+     * `preserve_world: false`, and it keeps its local xform.
+     */
+    reparent(entity, parent, opts = {}) {
         const op = { op: "reparent", id: idOf(entity), parent: parent === null ? null : idOf(parent, "parent") };
-        if (place && "before" in place)
-            op.before = idOf(place.before, "before");
-        else if (place && "after" in place)
-            op.after = idOf(place.after, "after");
+        if (opts.before !== undefined)
+            op.before = idOf(opts.before, "before");
+        else if (opts.after !== undefined)
+            op.after = idOf(opts.after, "after");
+        if (opts.preserveWorld === false)
+            op.preserve_world = false;
         this.#ops.push(op);
     }
     /** 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). */
@@ -1972,7 +2009,7 @@ export class SceneHandleImpl {
             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)),
+            reparent: (entity, parent, opts) => this.#txn(t => t.reparent(entity, parent, opts)),
             despawn: (entity, opts) => this.#txn(t => t.despawn(entity, opts)),
             setLocked: (entity, locked) => this.#txn(t => t.setLocked(entity, locked)),
         });

package/dist/synapse.d.ts

@@ -2,7 +2,7 @@ import { type Age, type ErrorBody, type ProjectSnapshot, type ServiceContract, t
 import { Node } from "./node.ts";
 import { StoreHandleImpl } from "./store.ts";
 import { type Warn } from "./topics.ts";
-import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
+import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, ProjectListing, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
 import { type StateValue } from "./util.ts";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.ts";
 export declare class Synapse implements AsyncDisposable {
@@ -133,6 +133,11 @@ export declare class Synapse implements AsyncDisposable {
      * resolves once the demoted session is connected.
      */
     leaveProject(): Promise<ProjectSnapshot>;
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects(): Promise<ProjectListing>;
     /**
      * The robot's task declarations, what runs (`status`), what the runtime can run (`catalog`), and the verbs; the same
      * object for the node's life. Each handle opens on its first touch and is the node's own (`node.close()` ends it).

package/dist/synapse.js

@@ -355,6 +355,11 @@ export class Synapse {
      * resolves once the demoted session is connected.
      */
     leaveProject() { return this.#projectCall("leave", {}); }
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects() { return this.call("synapse/project/list", {}).result; }
     // -------------------------------------------------------------------------------- tasks
     #tasks;
     /**

package/dist/types.d.ts

@@ -488,6 +488,8 @@ export interface Hardpoint {
 /**
  * An entity of the scene. The fields below are the ones the runtime and the early users read;
  * every other key passes through untouched.
+ * A component is absent (none), `{}` (there, nothing specified yet: every field at its default) or
+ * specified; a null component or sub-key is never stored (a patch deletes the key it names, a spawn drops it).
  */
 export interface SceneEntity {
     /** A ULID; never changes. */
@@ -620,8 +622,8 @@ export interface EntityAuthored {
      * 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>;
+    set<K extends keyof SceneEntity & string>(component: K, value: PatchSet[K]): Promise<void>;
+    set(components: PatchSet): 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 {
@@ -666,6 +668,12 @@ export interface SceneStatus {
     /** Lane rows dropped because their id's claim was refused (rows parked while it was asked, and rows written while refused). */
     unclaimedDrops: number;
 }
+type NullSubKeys<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [S in keyof T]?: T[S] | null;
+} : T;
+type PatchSet = {
+    [K in keyof SceneEntity]?: unknown extends SceneEntity[K] ? unknown : NullSubKeys<NonNullable<SceneEntity[K]>> | null;
+};
 /** An authored change as the runtime applied it (a diff op of the scene's `authored` track). */
 export type SceneDiffOp = {
     op: "spawn";
@@ -679,7 +687,7 @@ export type SceneDiffOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
     rev: number;
 } | {
     op: "reparent";
@@ -710,7 +718,7 @@ export type SceneOp = {
 } | {
     op: "patch";
     id: string;
-    set: Partial<SceneEntity>;
+    set: PatchSet;
 } | {
     op: "reparent";
     id: string;
@@ -733,20 +741,22 @@ export type SceneSpawnOptions = {
     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): a sibling by its id or its view. */
-export type ScenePlace = {
-    before: string | SceneEntityView;
-} | {
-    after: string | SceneEntityView;
-};
 /** 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: 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;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): void;
     rename(entity: string | SceneEntityView, name: string): void;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): void;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default it keeps its world pose (its local xform is recomputed); `preserveWorld: false` keeps its local xform.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): void;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): void;
@@ -797,7 +807,8 @@ export interface SceneAuthored {
     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>;
+    /** Sets components of the entity: merges one level deep; a null deletes the key it names. */
+    patch(entity: string | SceneEntityView, set: PatchSet): 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. The id is the runtime's answer, never the copy's: `spawn(kind, { name, parent, ...components })` (a fresh id) is
@@ -813,7 +824,16 @@ export interface SceneAuthored {
         id?: never;
     }): Promise<SceneEntityView>;
     rename(entity: string | SceneEntityView, name: string): Promise<void>;
-    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, place?: ScenePlace): Promise<void>;
+    /**
+     * Moves the entity under `parent` (`null`: the world root), `before` or `after` a sibling (default: after the last).
+     * By default the entity keeps its world pose (its local xform is recomputed). With `preserveWorld: false` it keeps its
+     * local xform instead, so a tool moved to another flange snaps to it.
+     */
+    reparent(entity: string | SceneEntityView, parent: string | SceneEntityView | null, opts?: {
+        before?: string | SceneEntityView;
+        after?: string | SceneEntityView;
+        preserveWorld?: boolean;
+    }): Promise<void>;
     despawn(entity: string | SceneEntityView, opts?: {
         cascade?: boolean;
     }): Promise<void>;
@@ -1024,6 +1044,21 @@ export interface Tasks {
     /** Stops every project task (also when none ran). Robot tasks are not touched. */
     stopProjectTasks(): Promise<void>;
 }
+/** The answer of `node.listProjects()` (`synapse/project/list`): every project the runtime has, sorted by id. */
+export interface ProjectListing {
+    projects: ProjectEntry[];
+}
+/** One project of a {@link ProjectListing}: what its document names (`name` when it has one), or why it cannot be read (`error`). */
+export type ProjectEntry = {
+    id: string;
+    name?: string;
+    scene_id: string;
+    store_id: string;
+    active: boolean;
+} | {
+    id: string;
+    error: string;
+};
 export interface Catalog {
     readonly topics: Readonly<Record<string, {
         desc?: TrackDesc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.7",
+    "@synapse-sdk/core": "0.3.8",
     "@moq/net": "0.4.2",
     "smol-toml": "1.9.0"
   },