@womp/kakapo-sdk 0.3.0 → 0.3.1

package/README.md

@@ -53,10 +53,10 @@ dynamically in Node.js.
 
 Applications that already own a renderer connection can pass a `KakapoAPITransport` as
 `new KakapoAPI({ transport })`. The adapter defines connection lifecycle, RPC, and token responses.
-`captureScreenshot({ view: "current" })` requests the renderer's JPEG without changing the camera
-or requiring a cached scene. Current-view captures cannot include `targetId` or `targetIds`.
-Framed captures restore the camera they replaced after capture. If another client moves the camera
-while capture is pending, the SDK detects that change and preserves the newer camera instead.
+`captureScreenshot({ view: "current" })` requests the renderer's JPEG without changing the camera
+or requiring a cached scene. Current-view captures cannot include `targetId` or `targetIds`.
+Framed captures restore the camera they replaced after capture. If another client moves the camera
+while capture is pending, the SDK detects that change and preserves the newer camera instead.
 
 All public inputs are checked at runtime as well as by TypeScript. Invalid calls throw structured
 `KakapoValidationError` objects with a stable `code`, offending `path`, expected rule, and a
@@ -80,15 +80,22 @@ typed `points` array replaces that data; use the granular operations when editin
 Engine-backed reads such as bounding boxes and screenshots remain asynchronous. Run them before the
 first draft mutation or after `editScene()` commits.
 
-Each `editScene()` refreshes before creating its private draft. Top-level edits are serialized per
-client. Changed drafts reread canonical state before submission and reject a changed baseline;
-camera movement alone does not invalidate an ordinary scene edit. This read does not eliminate
-a cross-client race between validation and submission through a backend wrapper. Commit patches add
-RFC 6902 `test` guards only for the wrapper partitions the draft changes: `/ext` and the remaining
-scene. This avoids turning a geometry-only edit into an unnecessary extension operation. Adding a
-missing `/ext` root is rejected because the existing wrapper cannot guard that cross-partition change;
-refresh or migrate the scene before retrying. Calling a scene-mutating method through raw `rpc()`
+Each `editScene()` refreshes before creating its private draft. Top-level edits are serialized per
+client. Changed drafts reread canonical state before submission and reject a changed baseline;
+camera movement alone does not invalidate an ordinary scene edit. This read does not eliminate
+a cross-client race between validation and submission through a backend wrapper. Commit patches add
+RFC 6902 `test` guards only for the wrapper partitions the draft changes: `/ext` and the remaining
+scene. This avoids turning a geometry-only edit into an unnecessary extension operation. Adding a
+missing `/ext` root is rejected because the existing wrapper cannot guard that cross-partition change;
+refresh or migrate the scene before retrying. Calling a scene-mutating method through raw `rpc()`
 deliberately marks the cache stale.
+
+Node IDs allocated by `createNode()` and `cloneNode()` increase for the lifetime of a `KakapoAPI`
+instance. IDs observed in scene snapshots, draft patches, or numeric node-extension keys remain
+reserved after deletion, rollback, and reconnect. This prevents delete-and-create edits from changing
+an existing renderer object's type by reusing its ID. A new API instance starts above IDs in its current
+snapshot; this is not a persistent project-wide allocator. Raw patches supply their own IDs and must
+preserve object identity; concurrent clients remain subject to the scene revision guards.
 
 `editSceneAndSave(callback)` submits the standard `scene_state_patch` command and, after
 acknowledgement, calls `save_scene` once on the same connection. No new Kakapo command is required.

package/dist/api.d.ts

@@ -84,6 +84,7 @@ export declare class KakapoAPI {
     private draftScene?;
     private draftDirty;
     private rendererSyncRequired;
+    private nextNodeId;
     constructor(options?: KakapoAPIOptions);
     get isConnected(): boolean;
     connect(): Promise<void>;
@@ -137,6 +138,7 @@ export declare class KakapoAPI {
     private ensureRendererReady;
     private captureRendererFrame;
     private screenshotDirection;
+    private reserveNodeIds;
     private createNode;
     private cloneNode;
     private updateNode;

package/dist/api.js

@@ -24,6 +24,7 @@ export class KakapoAPI {
     draftScene;
     draftDirty = false;
     rendererSyncRequired = false;
+    nextNodeId = 1;
     constructor(options = {}) {
         this.transport = options.transport ?? new KakapoTransport({
             url: options.url ?? "ws://127.0.0.1:5502",
@@ -77,6 +78,7 @@ export class KakapoAPI {
         const result = await this.call("scene_state_get");
         const scene = parseJsonResult(result, "scene_state_get");
         assertScene(scene, "refreshScene");
+        this.reserveNodeIds(scene);
         this.rawScene = scene;
         this.cacheValid = true;
         return this.getScene();
@@ -207,6 +209,7 @@ export class KakapoAPI {
     applyScenePatch(operations) {
         const candidate = applyJsonPatch(this.requireDraft("applyScenePatch"), operations);
         assertScene(candidate, "applyScenePatch");
+        this.reserveNodeIds(candidate);
         this.draftScene = candidate;
         this.draftDirty = true;
         return this.getScene();
@@ -439,12 +442,24 @@ export class KakapoAPI {
         };
         return directions[view];
     }
+    reserveNodeIds(scene) {
+        // Never rewind after deletion, rollback, or reconnect: old IDs may still be referenced.
+        for (const record of [scene.nodes, scene.ext ?? {}]) {
+            for (const key of Object.keys(record)) {
+                const id = Number(key);
+                if (Number.isSafeInteger(id) && id >= this.nextNodeId)
+                    this.nextNodeId = id + 1;
+            }
+        }
+    }
     createNode(input) {
         const scene = this.requireDraft("createNode");
         assertId(input.parentId, "createNode", "parentId", true);
         if (!scene.nodes[String(input.parentId)])
             throw missingNode(input.parentId, "createNode");
-        const id = nextId(scene.nodes);
+        const id = this.nextNodeId;
+        assertId(id, "createNode", "nodeId");
+        this.nextNodeId++;
         const initial = defaultNode(input.kind, id, input.name ?? "");
         const node = this.mergeNode(initial, input.properties ?? {});
         const children = this.treeArrays(scene);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/kakapo-sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Typed Node.js and browser SDK for controlling Kakapo over WebSocket",
   "type": "module",
   "main": "./dist/index.js",