@womp/kakapo-sdk 0.2.2 → 0.3.1

package/README.md

@@ -1,87 +1,135 @@
-# @womp/kakapo-sdk
-
-Typed Node.js and browser SDK for manipulating a Kakapo scene through its JSON-RPC WebSocket.
-
-```bash
-yarn install
-yarn build
-```
-
-```ts
-import { KakapoAPI } from "@womp/kakapo-sdk";
-
-const kakapo = new KakapoAPI();
-await kakapo.connect();
-
-const union = await kakapo.editScene((scene) => {
-  const root = scene.createNode({
-    kind: "union",
-    parentId: 0,
-    name: "Agent Model",
-  });
-
-  const box = scene.createNode({
-    kind: "primitive",
-    parentId: root.id,
-    name: "Body",
-    properties: {
-      primitive: "box",
-      transform: { scale: { x: 10, y: 4, z: 6 } },
-    },
-  });
-
-  const red = scene.createMaterial({
-    color: { x: 1, y: 0.05, z: 0.05 },
-    roughness: 0.4,
-  });
-
-  const body = scene.node(box.id, "primitive");
-  body.materialId = red.id;
-  body.position = { x: 0, y: 4, z: 0 };
-  body.round = 0.2;
-  body.save();
-  return root;
-});
-
-console.log(await kakapo.getNodeBoundingBox(union.id));
-
-kakapo.disconnect();
-```
-
-The transport uses the browser's native `WebSocket` when bundled for the web and loads `ws`
-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`.
-
-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
-correction `hint` intended for automated agents.
-
-`editScene()` refreshes once, exposes synchronous JSON reads and mutations, then validates and sends
-one RFC 6902 patch after the callback succeeds. Callback or commit failures discard the draft and
-refresh the authoritative scene. `node(id, kind)` returns a typed editable handle; `save()` applies
-its staged properties synchronously to the transaction draft.
-
-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. Calling a scene-mutating method through raw `rpc()` deliberately marks the cache stale.
-
-Mesh, field, and decal names are syntax-checked, but their existence cannot be enumerated by the
-current engine RPC surface. Font family/weight/style combinations are checked against `listFonts()`.
-
-## Verification
-
-```bash
-yarn test       # fake WebSocket protocol and API behavior
-yarn test:live  # launches ../kakapo/kakapo_app.exe and runs named live tests per API method
-yarn test:all   # runs both suites
-```
-
-The live suite starts Kakapo once, runs methods sequentially, and reports failures as names such as
-`live:setNodeParent` or `live:createNode:mesh`. Mutations refresh the authoritative engine scene
-before asserting their result. See [TEST_MATRIX.md](./TEST_MATRIX.md) for the exact unit/live mapping.
+# @womp/kakapo-sdk
+
+Typed Node.js and browser SDK for manipulating a Kakapo scene through its JSON-RPC WebSocket.
+
+```bash
+yarn install
+yarn build
+```
+
+```ts
+import { KakapoAPI } from "@womp/kakapo-sdk";
+
+const kakapo = new KakapoAPI();
+await kakapo.connect();
+
+const union = await kakapo.editScene((scene) => {
+  const root = scene.createNode({
+    kind: "union",
+    parentId: 0,
+    name: "Agent Model",
+  });
+
+  const box = scene.createNode({
+    kind: "primitive",
+    parentId: root.id,
+    name: "Body",
+    properties: {
+      primitive: "box",
+      transform: { scale: { x: 10, y: 4, z: 6 } },
+    },
+  });
+
+  const red = scene.createMaterial({
+    color: { x: 1, y: 0.05, z: 0.05 },
+    roughness: 0.4,
+  });
+
+  const body = scene.node(box.id, "primitive");
+  body.materialId = red.id;
+  body.position = { x: 0, y: 4, z: 0 };
+  body.round = 0.2;
+  body.save();
+  return root;
+});
+
+console.log(await kakapo.getNodeBoundingBox(union.id));
+
+kakapo.disconnect();
+```
+
+The transport uses the browser's native `WebSocket` when bundled for the web and loads `ws`
+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.
+
+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
+correction `hint` intended for automated agents.
+
+`editScene()` refreshes once, exposes synchronous JSON reads and mutations, then validates and sends
+one RFC 6902 patch after the callback succeeds. Callback or commit failures discard the draft and
+refresh the authoritative scene. `node(id, kind)` returns a typed editable handle; `save()` applies
+its staged properties synchronously to the transaction draft.
+
+Use the same SDK edit methods in browser and standalone hosts. Hosts coordinate connection ownership,
+permissions, and local editor activity; the SDK reads the canonical scene and submits the change.
+`getSceneSnapshotRevision(snapshot)` computes the same local fingerprint as `api.getSceneRevision()`;
+neither fingerprint establishes a server-side atomic commit guarantee.
+
+For incremental curve edits, use `SceneEdit.updateCurvePoint(id, index, changes)`,
+`cloneCurvePoint(id, sourceIndex, insertionIndex)`, and `deleteCurvePoint(id, index)`.
+These retain native per-point fields unknown to this SDK. Replacing a node's entire
+typed `points` array replaces that data; use the granular operations when editing existing points.
+
+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()`
+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.
+The result preserves the callback value separately from save status: `acknowledged` includes the
+returned filename, `unknown` includes an error, and `not_needed` means the draft did not change.
+A save acknowledgement does not prove a new durable snapshot: some endpoints return an existing
+filename. Verify persistence through the owning service. Never repeat the edit to recover saving.
+The backend wrapper may apply geometry before extension processing fails; patch errors and lost
+replies therefore have an `unknown` outcome unless rejection before execution is proven. SDK state
+is refreshed after submission, and no mutation is automatically replayed.
+
+`getSceneRevision()` fingerprints the cached native scene or active draft, including renderer fields
+not exposed by `getScene()`. Camera movement and object-key ordering do not affect it. Refresh before
+inspection; this fingerprint is not a server-issued revision or an atomic commit guarantee through a wrapper.
+
+Mesh, field, and decal names are syntax-checked, but their existence cannot be enumerated by the
+current engine RPC surface. Font family/weight/style combinations are checked against `listFonts()`.
+
+## Verification
+
+```bash
+yarn test       # fake WebSocket protocol and API behavior
+yarn test:live  # launches the sibling Kakapo build and runs named live tests per API method
+yarn test:all   # runs both suites
+```
+
+The live suite starts Kakapo once, runs methods sequentially, and reports failures as names such as
+`live:setNodeParent` or `live:createNode:mesh`. Mutations refresh the authoritative engine scene
+before asserting their result. See [TEST_MATRIX.md](./TEST_MATRIX.md) for the exact unit/live mapping.
+
+Build the sibling engine before running live tests. On Windows the default executable is
+`../kakapo/build/code/RelWithDebInfo/kakapo_app.exe`; on other platforms it is
+`../kakapo/build/code/kakapo_app`. Set `KAKAPO_BINARY` to test another build explicitly.
+
+### Importing catalog materials
+
+Inside `editScene`, `scene.importMaterial({ data, shaders })` imports native renderer material data and shader slots. `data` retains opaque fields and constants. Each non-null shader gets a new scene-local ID; null slots remain zero. The returned material can be assigned with `setNodeMaterial`. Material and shader resources share the draft's commit and rollback boundary. The host supplies the catalog data; the SDK does not fetch account or asset services.

package/dist/api.d.ts

@@ -1,5 +1,17 @@
 import { type NodeHandle } from "./node-handle.js";
-import type { BoundingBox, CaptureScreenshotOptions, CreateNodeInput, DeleteNodeOptions, FindNodeOptions, FontFamily, JsonPatchOperation, JsonValue, KakapoAPIOptions, KakapoNode, NodeKind, ListNodeOptions, Material, MaterialData, NodeUpdate, OpenScadScript, OpenScadValidationResult, PendingResources, PrimitiveOperation, Scene, ScreenshotImage, SvgPath, TokenMessage, Transform, Vec3 } from "./types.js";
+import type { BoundingBox, CaptureScreenshotOptions, CreateNodeInput, CurvePoint, DeleteNodeOptions, FindNodeOptions, FontFamily, JsonPatchOperation, JsonValue, KakapoAPIOptions, KakapoNode, NodeKind, ListNodeOptions, Material, MaterialData, MaterialResource, NodeUpdate, OpenScadScript, OpenScadValidationResult, PendingResources, PrimitiveOperation, Scene, ScreenshotImage, SvgPath, TokenMessage, Transform, Vec3 } from "./types.js";
+export type SceneSaveResult = {
+    status: "not_needed";
+} | {
+    status: "acknowledged";
+    filename: string;
+} | {
+    status: "unknown";
+    error: string;
+} | {
+    status: "failed";
+    error: string;
+};
 export interface SceneEdit {
     getScene(): Scene;
     listNodes(options?: ListNodeOptions): KakapoNode[];
@@ -15,6 +27,8 @@ export interface SceneEdit {
     applyScenePatch(operations: JsonPatchOperation[]): Scene;
     getSceneExt(): Record<string, JsonValue>;
     patchSceneExt(operations: JsonPatchOperation[]): Scene;
+    getSceneStorage(): Record<string, JsonValue>;
+    patchSceneStorage(operations: JsonPatchOperation[]): Scene;
     getSceneProperties(): Record<string, JsonValue>;
     patchSceneProperties(operations: JsonPatchOperation[]): Scene;
     createNode(input: CreateNodeInput): KakapoNode;
@@ -37,6 +51,9 @@ export interface SceneEdit {
     setNodeOperation(id: number, operation: PrimitiveOperation): KakapoNode;
     setTextContent(id: number, text: string): KakapoNode;
     setTextFont(id: number, fontFamily: string, weight?: number, italic?: boolean): KakapoNode;
+    updateCurvePoint(id: number, index: number, changes: Partial<CurvePoint>): void;
+    cloneCurvePoint(id: number, sourceIndex: number, index: number): void;
+    deleteCurvePoint(id: number, index: number): void;
     setSvgPaths(id: number, paths: SvgPath[]): KakapoNode;
     setMeshSource(id: number, mesh: string, meshIndex?: number): KakapoNode;
     setFieldSource(id: number, field: string): KakapoNode;
@@ -46,6 +63,7 @@ export interface SceneEdit {
     listMaterials(): Material[];
     getMaterial(id: number): Material;
     createMaterial(data?: Partial<MaterialData>, shaderIds?: number[]): Material;
+    importMaterial(resource: MaterialResource): Material;
     updateMaterial(id: number, data: Partial<MaterialData>, shaderIds?: number[]): Material;
     deleteMaterial(id: number): void;
     listOpenScadScripts(): OpenScadScript[];
@@ -66,6 +84,7 @@ export declare class KakapoAPI {
     private draftScene?;
     private draftDirty;
     private rendererSyncRequired;
+    private nextNodeId;
     constructor(options?: KakapoAPIOptions);
     get isConnected(): boolean;
     connect(): Promise<void>;
@@ -76,16 +95,33 @@ export declare class KakapoAPI {
     waitForToken(token: string, timeoutMs?: number): Promise<TokenMessage>;
     refreshScene(): Promise<Scene>;
     getScene(): Scene;
+    /** Fingerprint of the cached scene or active draft, including unknown native fields.
+     * Camera movement is excluded. This is not a server-issued revision or commit fence.
+     */
+    getSceneRevision(): Promise<string>;
+    /** Wait until the renderer has produced a frame after this API's latest edit. */
+    waitForRenderer(): Promise<void>;
     editScene<T>(callback: (scene: SceneEdit) => T | Promise<T>): Promise<T>;
+    editSceneAndSave<T>(callback: (scene: SceneEdit) => T | Promise<T>): Promise<{
+        value: T;
+        save: SceneSaveResult;
+    }>;
+    private prepareDraft;
+    private runSceneEdit;
     private applyScenePatch;
     /** The scene's consumer-owned extension bag. Kakapo does not interpret it. */
     getSceneExt(): Record<string, JsonValue>;
     /** Apply JSON Patch operations rooted at the scene's `ext` bag. */
     patchSceneExt(operations: JsonPatchOperation[]): Scene;
+    /** Consumer-owned resources stored in the scene file. */
+    getSceneStorage(): Record<string, JsonValue>;
+    /** Apply JSON Patch operations rooted at the scene's `storage` bag. */
+    patchSceneStorage(operations: JsonPatchOperation[]): Scene;
     /** The scene's renderer/environment properties (HDR, background, and similar). */
     getSceneProperties(): Record<string, JsonValue>;
     /** Apply JSON Patch operations rooted at the scene's `properties` bag. */
     patchSceneProperties(operations: JsonPatchOperation[]): Scene;
+    private patchSceneBag;
     listNodes(options?: ListNodeOptions): KakapoNode[];
     findNodes(options: FindNodeOptions): KakapoNode[];
     getNode(id: number): KakapoNode;
@@ -102,9 +138,14 @@ export declare class KakapoAPI {
     private ensureRendererReady;
     private captureRendererFrame;
     private screenshotDirection;
+    private reserveNodeIds;
     private createNode;
     private cloneNode;
     private updateNode;
+    private curvePointDraft;
+    private updateCurvePoint;
+    private cloneCurvePoint;
+    private deleteCurvePoint;
     private deleteNode;
     private setNodeParent;
     private setNodeName;
@@ -127,6 +168,7 @@ export declare class KakapoAPI {
     listMaterials(): Material[];
     getMaterial(id: number): Material;
     private createMaterial;
+    private importMaterial;
     private updateMaterial;
     private deleteMaterial;
     listOpenScadScripts(): OpenScadScript[];

package/dist/api.js

@@ -1,9 +1,9 @@
-import { KakapoConnectionError, KakapoRpcError, KakapoValidationError, } from "./errors.js";
+import { KakapoConnectionError, KakapoRpcError, KakapoSceneCommitError, KakapoValidationError, } from "./errors.js";
 import jsonpatch from "fast-json-patch";
-import { applyJsonPatch, deepClone, defaultMaterialData, defaultNode, encodeTree, materialToWire, missingNode, nextId, nodeToWire, orderedChildren, parseSafePositiveId, parseJsonResult, toPublicScene, wireToMaterial, wireToNode, } from "./scene.js";
+import { applyJsonPatch, deepClone, defaultMaterialData, defaultNode, encodeTree, encodeCurvePoint, escapePointer, getSceneSnapshotRevision, materialToWire, missingNode, nextId, nodeToWire, orderedChildren, parseSafePositiveId, parseJsonResult, toPublicScene, wireToMaterial, wireToNode, } from "./scene.js";
 import { KakapoTransport } from "./transport.js";
 import { createNodeHandle } from "./node-handle.js";
-import { assertFont, assertId, assertMaterial, assertScene } from "./validation.js";
+import { assertFont, assertId, assertMaterial, assertNode, assertScene } from "./validation.js";
 const SCENE_MUTATING_RPCS = new Set([
     "scene_state_patch", "scene_state_set", "load_scene", "replace_scene", "undo", "redo", "convert_scene",
 ]);
@@ -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",
@@ -33,12 +34,14 @@ export class KakapoAPI {
     }
     get isConnected() { return this.transport.connected; }
     async connect() {
-        await this.transport.connect();
         try {
+            await this.transport.connect();
             await this.ping();
             await this.refreshScene();
         }
         catch (error) {
+            if (error instanceof KakapoConnectionError && error.code === "CONNECTION_IN_PROGRESS")
+                throw error;
             this.disconnect();
             throw error;
         }
@@ -75,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();
@@ -82,24 +86,107 @@ export class KakapoAPI {
     getScene() {
         return deepClone(toPublicScene(this.requireScene("getScene")));
     }
+    /** Fingerprint of the cached scene or active draft, including unknown native fields.
+     * Camera movement is excluded. This is not a server-issued revision or commit fence.
+     */
+    async getSceneRevision() {
+        return getSceneSnapshotRevision(this.requireScene("getSceneRevision"));
+    }
+    /** Wait until the renderer has produced a frame after this API's latest edit. */
+    async waitForRenderer() {
+        await this.ensureRendererReady();
+    }
     editScene(callback) {
+        return this.runSceneEdit(callback, false).then(({ value }) => value);
+    }
+    editSceneAndSave(callback) {
+        return this.runSceneEdit(callback, true);
+    }
+    async prepareDraft(baseline, callback) {
+        this.draftScene = deepClone(baseline);
+        this.draftDirty = false;
+        let active = true;
+        const edit = this.createSceneEdit(() => {
+            if (active)
+                return;
+            throw new KakapoValidationError("The scene draft has expired.", {
+                code: "EXPIRED_SCENE_DRAFT",
+                operation: "editScene",
+                expected: "a draft used only inside its own callback",
+            });
+        });
+        let value;
+        try {
+            value = await callback(edit);
+        }
+        finally {
+            active = false;
+        }
+        const scene = this.requireDraft("editScene");
+        assertScene(scene, "editScene");
+        const operations = jsonpatch.compare(baseline, scene);
+        return { value, operations, scene };
+    }
+    runSceneEdit(callback, saveAfterPatch) {
         const run = this.transactionTail.then(async () => {
             await this.refreshScene();
             const baseline = deepClone(this.requireScene("editScene"));
-            this.draftScene = deepClone(baseline);
-            this.draftDirty = false;
             try {
-                const result = await callback(this.createSceneEdit());
-                const draft = this.requireDraft("editScene");
-                assertScene(draft, "editScene");
-                const operations = jsonpatch.compare(baseline, draft);
+                const { value, operations, scene } = await this.prepareDraft(baseline, callback);
+                let save = { status: "not_needed" };
                 if (operations.length) {
-                    await this.sendPatch(operations);
+                    const addsRootField = operations.some((operation) => operation.op === "add" && operation.path.split("/").length === 2);
+                    const addsExtRoot = operations.some((operation) => operation.op === "add" && operation.path === "/ext");
+                    if (addsExtRoot) {
+                        throw new KakapoValidationError("Cannot safely add a missing scene extension root through a partitioned endpoint.", {
+                            code: "UNSUPPORTED_PATCH_GUARD",
+                            operation: "editScene",
+                            path: "/ext",
+                            expected: "an existing ext root",
+                        });
+                    }
+                    const changesCamera = operations.some((operation) => operation.path === "/camera" || operation.path.startsWith("/camera/"));
+                    const changesExt = operations.some((operation) => operation.path === "/ext" || operation.path.startsWith("/ext/"));
+                    const changesNonExt = operations.some((operation) => operation.path !== "/ext" && !operation.path.startsWith("/ext/"));
+                    const latest = parseJsonResult(await this.call("scene_state_get"), "scene_state_get");
+                    assertScene(latest, "editScene");
+                    const stale = jsonpatch.compare(baseline, latest).some((operation) => changesCamera || (operation.path !== "/camera" && !operation.path.startsWith("/camera/")));
+                    if (stale)
+                        throw new KakapoSceneCommitError("rolled_back", new Error("Scene changed during preparation. Read it again before editing."));
+                    // Raw renderers evaluate these together; wrappers may partition the patch.
+                    // A failed response cannot establish that no earlier group was applied.
+                    const guards = [];
+                    if (changesNonExt) {
+                        if (addsRootField)
+                            guards.push({ op: "test", path: "", value: baseline });
+                        else
+                            guards.push(...Object.entries(baseline)
+                                .filter(([key]) => key !== "ext" && (key !== "camera" || changesCamera))
+                                .map(([key, value]) => ({
+                                op: "test",
+                                path: `/${escapePointer(key)}`,
+                                value: value,
+                            })));
+                    }
+                    if (changesExt)
+                        guards.push({ op: "test", path: "/ext", value: baseline.ext });
+                    save = await this.sendPatch([...guards, ...operations], saveAfterPatch);
                     this.rendererSyncRequired = true;
                 }
-                this.rawScene = draft;
-                this.cacheValid = true;
-                return result;
+                if (operations.length) {
+                    this.cacheValid = false;
+                    try {
+                        await this.refreshScene();
+                    }
+                    catch {
+                        // Keep the acknowledged result; the next read must refresh the invalid cache.
+                    }
+                }
+                else {
+                    this.rawScene = scene;
+                    this.cacheValid = true;
+                }
+                return { value, save };
             }
             catch (error) {
                 this.cacheValid = false;
@@ -122,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();
@@ -133,7 +221,15 @@ export class KakapoAPI {
     }
     /** Apply JSON Patch operations rooted at the scene's `ext` bag. */
     patchSceneExt(operations) {
-        return this.applyScenePatch(operations.map((op) => ({ ...op, path: `/ext${op.path}` })));
+        return this.patchSceneBag("ext", operations);
+    }
+    /** Consumer-owned resources stored in the scene file. */
+    getSceneStorage() {
+        return deepClone(this.requireScene("getSceneStorage").storage);
+    }
+    /** Apply JSON Patch operations rooted at the scene's `storage` bag. */
+    patchSceneStorage(operations) {
+        return this.patchSceneBag("storage", operations);
     }
     /** The scene's renderer/environment properties (HDR, background, and similar). */
     getSceneProperties() {
@@ -142,7 +238,24 @@ export class KakapoAPI {
     }
     /** Apply JSON Patch operations rooted at the scene's `properties` bag. */
     patchSceneProperties(operations) {
-        return this.applyScenePatch(operations.map((op) => ({ ...op, path: `/properties${op.path}` })));
+        return this.patchSceneBag("properties", operations);
+    }
+    patchSceneBag(key, operations) {
+        const draft = this.requireDraft("patchSceneBag");
+        if (operations.length === 0)
+            return this.getScene();
+        const prefix = `/${key}`;
+        const patch = draft[key] === undefined
+            ? [{ op: "add", path: prefix, value: {} }]
+            : [];
+        for (const operation of operations) {
+            patch.push({
+                ...operation,
+                path: `${prefix}${operation.path}`,
+                ...("from" in operation ? { from: `${prefix}${operation.from}` } : {}),
+            });
+        }
+        return this.applyScenePatch(patch);
     }
     listNodes(options = {}) {
         const scene = this.requireScene("listNodes");
@@ -257,23 +370,35 @@ export class KakapoAPI {
             z: (bounds.max.z - bounds.min.z) * framePadding,
         };
         const distance = Math.max(Math.hypot(size.x, size.y, size.z), 1);
-        const current = parseJsonResult(await this.call("get_cam"), "get_cam");
-        await this.call("set_camera", [{
-                ...current,
-                cent: center,
-                dir: { x: direction.x, y: direction.y, z: direction.z },
-                up: view === "top" || view === "bottom" ? { x: 0, y: 0, z: 1 } : { x: 0, y: 1, z: 0 },
-                pos: {
-                    x: center.x - direction.x * distance,
-                    y: center.y - direction.y * distance,
-                    z: center.z - direction.z * distance,
-                },
-            }, true]);
-        const framed = await this.call("center_cam", [center, size]);
-        if (this.rawScene)
-            this.rawScene.camera = { ...this.rawScene.camera, ...framed };
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        const message = await this.captureRendererFrame(timeoutMs);
+        const originalCamera = parseJsonResult(await this.call("get_cam"), "get_cam");
+        let framedCamera;
+        let message;
+        try {
+            await this.call("set_camera", [{
+                    ...originalCamera,
+                    cent: center,
+                    dir: { x: direction.x, y: direction.y, z: direction.z },
+                    up: view === "top" || view === "bottom" ? { x: 0, y: 0, z: 1 } : { x: 0, y: 1, z: 0 },
+                    pos: {
+                        x: center.x - direction.x * distance,
+                        y: center.y - direction.y * distance,
+                        z: center.z - direction.z * distance,
+                    },
+                }, true]);
+            const framed = await this.call("center_cam", [center, size]);
+            if (this.rawScene)
+                this.rawScene.camera = { ...this.rawScene.camera, ...framed };
+            framedCamera = parseJsonResult(await this.call("get_cam"), "get_cam");
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            message = await this.captureRendererFrame(timeoutMs);
+        }
+        finally {
+            if (framedCamera !== undefined) {
+                const latestCamera = parseJsonResult(await this.call("get_cam"), "get_cam");
+                if (jsonpatch.compare(framedCamera, latestCamera).length === 0)
+                    await this.call("set_camera", [originalCamera, true]);
+            }
+        }
         return {
             data: message.payload,
             mediaType: "image/jpeg",
@@ -317,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);
@@ -349,12 +486,77 @@ export class KakapoAPI {
         const scene = this.requireDraft("updateNode");
         if (id === 0 && ("hidden" in changes || "transform" in changes))
             throw this.rootError("updateNode");
-        const updated = this.mergeNode(wireToNode(scene, id), changes);
-        scene.nodes[String(id)] = nodeToWire(updated);
+        const current = wireToNode(scene, id);
+        const updated = this.mergeNode(current, changes);
+        assertNode(updated, scene, "updateNode");
+        const before = nodeToWire(current);
+        const after = nodeToWire(updated);
+        // Only replace fields changed through the typed API. Re-encoding the whole
+        // node discards renderer fields this SDK version does not know about.
+        const raw = deepClone(scene.nodes[String(id)]);
+        for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            if (JSON.stringify(before[key]) === JSON.stringify(after[key]))
+                continue;
+            if (Object.hasOwn(after, key))
+                raw[key] = after[key];
+            else
+                delete raw[key];
+        }
+        scene.nodes[String(id)] = raw;
         scene.ext = this.extWithNode(scene, updated);
         this.draftDirty = true;
         return deepClone(wireToNode(scene, id));
     }
+    curvePointDraft(id, index, operation) {
+        const scene = this.requireDraft(operation);
+        const node = this.getNode(id);
+        if (node.kind !== "curve")
+            throw this.unsupported(operation, id, "curve points");
+        if (!Number.isInteger(index) || index < 0 || index >= node.points.length)
+            throw new KakapoValidationError("Curve point index is out of range.", {
+                code: "INVALID_CURVE_POINT_INDEX", operation, received: index,
+                expected: `integer from 0 through ${node.points.length - 1}`,
+            });
+        return { scene, node, points: scene.nodes[String(id)].points };
+    }
+    updateCurvePoint(id, index, changes) {
+        const { scene, node, points } = this.curvePointDraft(id, index, "updateCurvePoint");
+        const previous = node.points[index];
+        const next = { ...previous, ...deepClone(changes) };
+        node.points[index] = next;
+        assertNode(node, scene, "updateCurvePoint");
+        const before = encodeCurvePoint(previous);
+        const after = encodeCurvePoint(next);
+        // Edit only requested typed fields; retain opaque native data on this point.
+        for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            if (JSON.stringify(before[key]) === JSON.stringify(after[key]))
+                continue;
+            if (Object.hasOwn(after, key))
+                points[index][key] = after[key];
+            else
+                delete points[index][key];
+        }
+        this.draftDirty = true;
+    }
+    cloneCurvePoint(id, sourceIndex, index) {
+        const { points } = this.curvePointDraft(id, sourceIndex, "cloneCurvePoint");
+        if (!Number.isInteger(index) || index < 0 || index > points.length)
+            throw new KakapoValidationError("Curve insertion index is out of range.", {
+                code: "INVALID_CURVE_POINT_INDEX", operation: "cloneCurvePoint", received: index,
+                expected: `integer from 0 through ${points.length}`,
+            });
+        points.splice(index, 0, deepClone(points[sourceIndex]));
+        this.draftDirty = true;
+    }
+    deleteCurvePoint(id, index) {
+        const { points } = this.curvePointDraft(id, index, "deleteCurvePoint");
+        if (points.length <= 1)
+            throw new KakapoValidationError("A curve must keep at least one point.", {
+                code: "INVALID_CURVE_POINT_COUNT", operation: "deleteCurvePoint", expected: "at least one point",
+            });
+        points.splice(index, 1);
+        this.draftDirty = true;
+    }
     deleteNode(id, options = {}) {
         const scene = this.requireDraft("deleteNode");
         if (id === 0)
@@ -470,6 +672,25 @@ export class KakapoAPI {
         this.draftDirty = true;
         return deepClone(material);
     }
+    importMaterial(resource) {
+        const scene = this.requireDraft("importMaterial");
+        const source = deepClone(resource);
+        const materials = scene.storage.materials ?? (scene.storage.materials = {});
+        const id = nextId(materials);
+        assertMaterial(wireToMaterial(id, { data: source.data }).data, "importMaterial");
+        const shaders = scene.storage.shaders ?? (scene.storage.shaders = {});
+        const shaderIds = source.shaders.map((shader) => {
+            if (shader === null)
+                return 0;
+            const shaderId = nextId(shaders);
+            shaders[String(shaderId)] = shader;
+            return shaderId;
+        });
+        const material = { data: source.data, ...(shaderIds.length ? { shaders: shaderIds } : {}) };
+        materials[String(id)] = material;
+        this.draftDirty = true;
+        return deepClone(wireToMaterial(id, material));
+    }
     updateMaterial(id, data, shaderIds) {
         const scene = this.requireDraft("updateMaterial");
         const currentRaw = scene.storage.materials?.[String(id)];
@@ -478,10 +699,21 @@ export class KakapoAPI {
         const current = wireToMaterial(id, currentRaw);
         const updated = { id, data: this.mergeMaterialData(current.data, data), shaderIds: shaderIds ? [...shaderIds] : current.shaderIds };
         assertMaterial(updated.data, "updateMaterial");
+        const before = materialToWire(current);
         const next = materialToWire(updated);
-        scene.storage.materials[String(id)] = shaderIds === undefined
-            ? { ...currentRaw, data: next.data }
-            : next;
+        const raw = { ...currentRaw, data: { ...currentRaw.data } };
+        for (const [key, value] of Object.entries(next.data)) {
+            if (value !== before.data[key])
+                raw.data[key] = value;
+        }
+        if (shaderIds !== undefined) {
+            delete raw.shader;
+            if (next.shaders)
+                raw.shaders = next.shaders;
+            else
+                delete raw.shaders;
+        }
+        scene.storage.materials[String(id)] = raw;
         this.draftDirty = true;
         return deepClone(updated);
     }
@@ -542,10 +774,34 @@ export class KakapoAPI {
     async reloadTextures() { return this.call("reload_textures"); }
     async getPendingResources() { return parseJsonResult(await this.call("get_pending_resources"), "get_pending_resources"); }
     call(method, params = []) { return this.transport.rpc(method, params); }
-    async sendPatch(operations) {
-        const result = await this.call("scene_state_patch", [JSON.stringify(operations)]);
+    async sendPatch(operations, saveAfterPatch) {
+        let result;
+        try {
+            result = await this.call("scene_state_patch", [JSON.stringify(operations)]);
+        }
+        catch (cause) {
+            if (cause instanceof KakapoRpcError && cause.rpcCode === -32601)
+                throw new KakapoSceneCommitError("rolled_back", cause);
+            throw new KakapoSceneCommitError("unknown", cause);
+        }
         if (result !== undefined && result !== null && result !== "") {
-            throw new KakapoRpcError("scene_state_patch", String(result));
+            const message = typeof result === "object" && "message" in result && typeof result.message === "string"
+                ? result.message
+                : JSON.stringify(result);
+            // The wrapper can apply geometry before a later extension patch fails.
+            throw new KakapoSceneCommitError("unknown", new KakapoRpcError("scene_state_patch", message));
+        }
+        if (!saveAfterPatch)
+            return { status: "not_needed" };
+        try {
+            const saved = await this.call("save_scene");
+            // A filename acknowledges the save handler, not a new durable snapshot.
+            if (typeof saved === "string" && saved.length > 0 && !saved.startsWith("{") && !saved.startsWith("["))
+                return { status: "acknowledged", filename: saved };
+            return { status: "unknown", error: `Save was not confirmed: ${JSON.stringify(saved)}` };
+        }
+        catch (error) {
+            return { status: "unknown", error: error instanceof Error ? error.message : String(error) };
         }
     }
     saveNode(id, changes) {
@@ -586,19 +842,24 @@ export class KakapoAPI {
             hint: "Finish the transaction, then perform the engine-backed read.",
         });
     }
-    createSceneEdit() {
-        return {
+    createSceneEdit(assertActive) {
+        const edit = {
             getScene: () => this.getScene(),
             listNodes: (options) => this.listNodes(options),
             findNodes: (options) => this.findNodes(options),
             getNode: (id) => this.getNode(id),
-            node: ((id, kind) => this.node(id, kind)),
+            node: ((id, kind) => createNodeHandle({
+                readNode: (nodeId) => { assertActive(); return this.getNode(nodeId); },
+                saveNode: (nodeId, changes) => { assertActive(); return this.saveNode(nodeId, changes); },
+            }, id, kind)),
             getNodeName: (id) => this.getNodeName(id),
             getNodeParent: (id) => this.getNodeParent(id),
             getNodeChildren: (id) => this.getNodeChildren(id),
             applyScenePatch: (operations) => this.applyScenePatch(operations),
             getSceneExt: () => this.getSceneExt(),
             patchSceneExt: (operations) => this.patchSceneExt(operations),
+            getSceneStorage: () => this.getSceneStorage(),
+            patchSceneStorage: (operations) => this.patchSceneStorage(operations),
             getSceneProperties: () => this.getSceneProperties(),
             patchSceneProperties: (operations) => this.patchSceneProperties(operations),
             createNode: (input) => this.createNode(input),
@@ -617,6 +878,9 @@ export class KakapoAPI {
             setNodeOperation: (id, operation) => this.setNodeOperation(id, operation),
             setTextContent: (id, text) => this.setTextContent(id, text),
             setTextFont: (id, family, weight, italic) => this.setTextFont(id, family, weight, italic),
+            updateCurvePoint: (id, index, changes) => this.updateCurvePoint(id, index, changes),
+            cloneCurvePoint: (id, sourceIndex, index) => this.cloneCurvePoint(id, sourceIndex, index),
+            deleteCurvePoint: (id, index) => this.deleteCurvePoint(id, index),
             setSvgPaths: (id, paths) => this.setSvgPaths(id, paths),
             setMeshSource: (id, mesh, index) => this.setMeshSource(id, mesh, index),
             setFieldSource: (id, field) => this.setFieldSource(id, field),
@@ -626,6 +890,7 @@ export class KakapoAPI {
             listMaterials: () => this.listMaterials(),
             getMaterial: (id) => this.getMaterial(id),
             createMaterial: (data, shaderIds) => this.createMaterial(data, shaderIds),
+            importMaterial: (resource) => this.importMaterial(resource),
             updateMaterial: (id, data, shaderIds) => this.updateMaterial(id, data, shaderIds),
             deleteMaterial: (id) => this.deleteMaterial(id),
             listOpenScadScripts: () => this.listOpenScadScripts(),
@@ -634,6 +899,18 @@ export class KakapoAPI {
             updateOpenScadScript: (id, changes) => this.updateOpenScadScript(id, changes),
             deleteOpenScadScript: (id) => this.deleteOpenScadScript(id),
         };
+        return new Proxy(edit, {
+            get(target, property, receiver) {
+                assertActive();
+                const method = Reflect.get(target, property, receiver);
+                if (typeof method !== "function")
+                    return method;
+                return (...args) => {
+                    assertActive();
+                    return Reflect.apply(method, target, args);
+                };
+            },
+        });
     }
     treeArrays(scene) { return Object.fromEntries(Object.keys(scene.tree ?? {}).map((id) => [id, orderedChildren(scene, Number(id))])); }
     extWithName(scene, id, name) {
@@ -669,10 +946,10 @@ export class KakapoAPI {
         const common = ["transform", "pickable"];
         const byKind = {
             primitive: ["hidden", "materialId", "operation", "blend", "color", "primitive", "round", "thickness", "inflation", "materialNeutralCutout", "mirrors"],
-            union: ["hidden", "operation", "blend", "resolution", "thickness", "inflation", "materialNeutralCutout"],
+            union: ["hidden", "operation", "blend", "resolution", "thickness", "inflation", "materialNeutralCutout", "scriptInstanceId"],
             group: ["hidden"],
             light: ["color", "power", "collimation", "lightType", "size", "textureFile"],
-            curve: ["hidden", "materialId", "operation", "blend", "primitive", "density", "roundness", "smoothing", "points", "materialNeutralCutout", "mirrors"],
+            curve: ["hidden", "materialId", "operation", "blend", "primitive", "density", "roundness", "smoothing", "points", "materialNeutralCutout", "mirrors", "version", "curveType", "closed"],
             text: ["hidden", "materialId", "operation", "blend", "text", "fontFamily", "weight", "italic", "round", "width", "wrap", "align", "spacing", "lineHeight", "materialNeutralCutout"],
             svg: ["hidden", "materialId", "operation", "blend", "paths", "inflate", "outline", "outlineSize", "materialNeutralCutout"],
             mesh: ["hidden", "materialId", "mesh", "meshIndex", "smoothNormals", "colorSampling"],

package/dist/errors.d.ts

@@ -23,6 +23,10 @@ export declare class KakapoConnectionError extends KakapoError {
 }
 export declare class KakapoTimeoutError extends KakapoError {
 }
+export declare class KakapoSceneCommitError extends KakapoError {
+    readonly outcome: "rolled_back" | "unknown";
+    constructor(outcome: "rolled_back" | "unknown", cause: unknown);
+}
 export declare class KakapoRpcError extends KakapoError {
     readonly rpcCode?: number;
     readonly method: string;

package/dist/errors.js

@@ -35,6 +35,18 @@ export class KakapoConnectionError extends KakapoError {
 }
 export class KakapoTimeoutError extends KakapoError {
 }
+export class KakapoSceneCommitError extends KakapoError {
+    outcome;
+    constructor(outcome, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), {
+            code: "SCENE_COMMIT_FAILED",
+            operation: "editScene",
+            details: { outcome },
+            cause,
+        });
+        this.outcome = outcome;
+    }
+}
 export class KakapoRpcError extends KakapoError {
     rpcCode;
     method;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { KakapoAPI } from "./api.js";
-export type { SceneEdit } from "./api.js";
-export { KakapoError, KakapoConnectionError, KakapoTimeoutError, KakapoRpcError, KakapoValidationError, } from "./errors.js";
+export type { SceneEdit, SceneSaveResult } from "./api.js";
+export type { WireScene as NativeSceneSnapshot } from "./scene.js";
+export { getSceneSnapshotRevision } from "./scene.js";
+export { KakapoError, KakapoConnectionError, KakapoTimeoutError, KakapoSceneCommitError, KakapoRpcError, KakapoValidationError, } from "./errors.js";
 export { parseBinaryFrame } from "./transport.js";
 export type { NodeHandle, NodeHandleActions } from "./node-handle.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { KakapoAPI } from "./api.js";
-export { KakapoError, KakapoConnectionError, KakapoTimeoutError, KakapoRpcError, KakapoValidationError, } from "./errors.js";
+export { getSceneSnapshotRevision } from "./scene.js";
+export { KakapoError, KakapoConnectionError, KakapoTimeoutError, KakapoSceneCommitError, KakapoRpcError, KakapoValidationError, } from "./errors.js";
 export { parseBinaryFrame } from "./transport.js";

package/dist/scene.d.ts

@@ -1,5 +1,5 @@
 import { KakapoValidationError } from "./errors.js";
-import type { JsonPatchOperation, KakapoNode, Material, MaterialData, NodeKind, Scene, Transform } from "./types.js";
+import type { CurvePoint, JsonPatchOperation, KakapoNode, Material, MaterialData, NodeKind, Scene, Transform } from "./types.js";
 export interface WireNode {
     type: number;
     [key: string]: unknown;
@@ -8,7 +8,7 @@ export interface WireScene {
     version?: number;
     name?: string;
     nodes: Record<string, WireNode>;
-    tree: Record<string, Record<string, number>>;
+    tree: Record<string, Record<string, number> | number[]>;
     ext?: Record<string, unknown>;
     storage: {
         materials?: Record<string, {
@@ -30,6 +30,10 @@ export interface WireScene {
     camera?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/** Local scene fingerprint; camera navigation does not invalidate an editing baseline.
+ * This is not a server-issued revision or an atomic commit fence.
+ */
+export declare function getSceneSnapshotRevision(snapshot: WireScene): Promise<string>;
 export declare const identityTransform: () => Transform;
 export declare function deepClone<T>(value: T): T;
 export declare function parseJsonResult<T>(value: unknown, operation: string): T;
@@ -40,6 +44,7 @@ export declare function orderedChildren(scene: WireScene, parentId: number): num
 export declare function encodeTree(tree: Record<string, number[]>): WireScene["tree"];
 export declare function wireToNode(scene: WireScene, id: number): KakapoNode;
 export declare function defaultNode(kind: NodeKind, id: number, name?: string): KakapoNode;
+export declare function encodeCurvePoint(point: CurvePoint): Record<string, unknown>;
 export declare function nodeToWire(node: KakapoNode): WireNode;
 export declare const defaultMaterialData: () => MaterialData;
 export declare function wireToMaterial(id: number, raw: {

package/dist/scene.js

@@ -1,4 +1,17 @@
 import { KakapoValidationError } from "./errors.js";
+/** Local scene fingerprint; camera navigation does not invalidate an editing baseline.
+ * This is not a server-issued revision or an atomic commit fence.
+ */
+export async function getSceneSnapshotRevision(snapshot) {
+    const { camera: _camera, ...state } = snapshot;
+    const json = JSON.stringify(state, (_key, value) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+    });
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(json));
+    return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, "0")).join("");
+}
 const KINDS = [
     "primitive", "union", "light", "curve", "group", "text", "field", "svg", "mesh", "decal", "openScad", "socket",
 ];
@@ -134,6 +147,8 @@ function decodeCurvePoint(value) {
     return {
         position: vec3(p.pos), rotation: vec3(p.rot), scale: vec3(p.size, v3(10)),
         materialId: materialId(p.material_id), round: num(p.round, 0), fixed: bool(p.fixed, false),
+        ...(p.handle_in !== undefined ? { handleIn: vec3(p.handle_in) } : {}),
+        ...(p.handle_out !== undefined ? { handleOut: vec3(p.handle_out) } : {}),
     };
 }
 function decodeSvgPaths(value) {
@@ -160,10 +175,17 @@ export function wireToNode(scene, id) {
     const material = materialId(raw.material_id);
     switch (base.kind) {
         case "primitive": return { ...base, kind: "primitive", hidden, operation, blend: num(raw.blend, 0), color: vec3(raw.color, v3(1)), primitive: PRIMITIVES[num(raw.prim, 2)] ?? "box", round: num(raw.round, 0), thickness: num(raw.thickness, -1), inflation: num(raw.inflation, 0), materialId: material, materialNeutralCutout: bool(raw.material_neutral_cutout, false), mirrors: mirrorPlanes(scene, id, raw) };
-        case "union": return { ...base, kind: "union", hidden, operation, blend: num(raw.blend, 0), resolution: num(raw.resolution, 0.3), thickness: num(raw.thickness, -1), inflation: num(raw.inflation, 0), materialNeutralCutout: bool(raw.material_neutral_cutout, false) };
+        case "union": {
+            const scriptInstanceId = num(raw.script_id, 0xffffffff);
+            return {
+                ...base, kind: "union", hidden, operation, blend: num(raw.blend, 0), resolution: num(raw.resolution, 0.3),
+                thickness: num(raw.thickness, -1), inflation: num(raw.inflation, 0), materialNeutralCutout: bool(raw.material_neutral_cutout, false),
+                ...(Number.isSafeInteger(scriptInstanceId) && scriptInstanceId >= 0 && scriptInstanceId < 0xffffffff ? { scriptInstanceId } : {}),
+            };
+        }
         case "group": return { ...base, kind: "group", hidden };
         case "light": return { ...base, kind: "light", color: vec3(raw.color, { x: 1, y: 1, z: 0.9 }), power: num(raw.power, 80), collimation: num(raw.collimation, 0), lightType: LIGHT_TYPES[num(raw.lightType, 1)] ?? "sphere", size: vec2(raw.size, v2(1, 1)), textureFile: str(raw.texture_file) };
-        case "curve": return { ...base, kind: "curve", hidden, materialId: material, operation, blend: num(raw.blend, 20), primitive: PRIMITIVES[num(raw.prim, 0)] ?? "sphere", density: num(raw.density, 100), roundness: num(raw.roundness, 1), smoothing: num(raw.smoothing, 0.02), materialNeutralCutout: bool(raw.material_neutral_cutout, false), points: Array.isArray(raw.points) ? raw.points.map(decodeCurvePoint) : [], mirrors: mirrorPlanes(scene, id, raw) };
+        case "curve": return { ...base, kind: "curve", version: num(raw.version, 2), curveType: raw.curve_type === 1 ? "bezier" : "spline", closed: bool(raw.closed, false), hidden, materialId: material, operation, blend: num(raw.blend, 20), primitive: PRIMITIVES[num(raw.prim, 0)] ?? "sphere", density: num(raw.density, 100), roundness: num(raw.roundness, 1), smoothing: num(raw.smoothing, 0.02), materialNeutralCutout: bool(raw.material_neutral_cutout, false), points: Array.isArray(raw.points) ? raw.points.map(decodeCurvePoint) : [], mirrors: mirrorPlanes(scene, id, raw) };
         case "text": return { ...base, kind: "text", hidden, materialId: material, operation, blend: num(raw.blend, 0), text: str(raw.text, "Text"), fontFamily: str(raw.font, "OpenSans"), weight: num(raw.weight, 400), italic: bool(raw.italic, false), round: num(raw.round, 0), width: num(raw.width, 20), wrap: TEXT_WRAP[num(raw.wrap, 0)] ?? "disabled", align: TEXT_ALIGN[num(raw.align, 0)] ?? "left", spacing: num(raw.spacing, 0), lineHeight: num(raw.line_height, 1), materialNeutralCutout: bool(raw.material_neutral_cutout, false) };
         case "svg": return { ...base, kind: "svg", hidden, materialId: material, operation, blend: num(raw.blend, 0), paths: decodeSvgPaths(raw.paths), inflate: bool(raw.inflate, false), outline: bool(raw.outline, false), outlineSize: num(raw.outline_size, 0.1), materialNeutralCutout: bool(raw.material_neutral_cutout, false) };
         case "mesh": return { ...base, kind: "mesh", hidden, materialId: material, mesh: str(raw.mesh), meshIndex: num(raw.mesh_index, 0), smoothNormals: bool(raw.smooth_normals, false), colorSampling: FIELD_SAMPLING[num(raw.color_option, 2)] ?? "override" };
@@ -198,8 +220,13 @@ export function defaultNode(kind, id, name = "") {
         case "socket": return { ...base, kind, hidden: false, tag: "" };
     }
 }
-function encodeCurvePoint(point) {
-    return { pos: point.position, rot: point.rotation, size: point.scale, material_id: point.materialId ?? 0, round: point.round, fixed: point.fixed };
+export function encodeCurvePoint(point) {
+    return {
+        pos: point.position, rot: point.rotation, size: point.scale,
+        material_id: point.materialId ?? 0, round: point.round, fixed: point.fixed,
+        ...(point.handleIn !== undefined ? { handle_in: point.handleIn } : {}),
+        ...(point.handleOut !== undefined ? { handle_out: point.handleOut } : {}),
+    };
 }
 function encodeSvgPaths(paths) {
     return paths.map((path) => ({ closed: path.closed, segments: path.segments.map((s) => ({ point: s.point, handle_in: s.handleIn, handle_out: s.handleOut })) }));
@@ -221,13 +248,17 @@ export function nodeToWire(node) {
             Object.assign(raw, { color: node.color, prim: PRIMITIVES.indexOf(node.primitive), round: node.round, thickness: node.thickness, inflation: node.inflation, material_neutral_cutout: node.materialNeutralCutout, mirror_x: -1, mirror_y: -1, mirror_z: -1 }, encodeMirrorPlanes(node.mirrors));
             break;
         case "union":
-            Object.assign(raw, { resolution: node.resolution, thickness: node.thickness, inflation: node.inflation, material_neutral_cutout: node.materialNeutralCutout });
+            Object.assign(raw, {
+                resolution: node.resolution, thickness: node.thickness, inflation: node.inflation,
+                material_neutral_cutout: node.materialNeutralCutout,
+                ...(node.scriptInstanceId !== undefined ? { script_id: node.scriptInstanceId } : {}),
+            });
             break;
         case "light":
             Object.assign(raw, { color: node.color, power: node.power, collimation: node.collimation, lightType: LIGHT_TYPES.indexOf(node.lightType), size: node.size, texture_file: node.textureFile });
             break;
         case "curve":
-            Object.assign(raw, { prim: PRIMITIVES.indexOf(node.primitive), density: node.density, roundness: node.roundness, smoothing: node.smoothing, material_neutral_cutout: node.materialNeutralCutout, points: node.points.map(encodeCurvePoint), version: 2, mirror_x: -1, mirror_y: -1, mirror_z: -1 }, encodeMirrorPlanes(node.mirrors));
+            Object.assign(raw, { prim: PRIMITIVES.indexOf(node.primitive), density: node.density, roundness: node.roundness, smoothing: node.smoothing, material_neutral_cutout: node.materialNeutralCutout, points: node.points.map(encodeCurvePoint), version: node.version ?? 2, curve_type: node.curveType === "bezier" ? 1 : 0, closed: node.closed ?? false, mirror_x: -1, mirror_y: -1, mirror_z: -1 }, encodeMirrorPlanes(node.mirrors));
             break;
         case "text":
             Object.assign(raw, { text: node.text, font: node.fontFamily, weight: node.weight, italic: node.italic, round: node.round, width: node.width, wrap: TEXT_WRAP.indexOf(node.wrap), align: TEXT_ALIGN.indexOf(node.align), spacing: node.spacing, line_height: node.lineHeight, material_neutral_cutout: node.materialNeutralCutout });

package/dist/types.d.ts

@@ -70,6 +70,7 @@ export interface UnionNode extends TransformNode, OperationNode {
     thickness: number;
     inflation: number;
     materialNeutralCutout: boolean;
+    scriptInstanceId?: number;
 }
 export interface GroupNode extends TransformNode {
     kind: "group";
@@ -90,9 +91,14 @@ export interface CurvePoint {
     materialId: number | null;
     round: number;
     fixed: boolean;
+    handleIn?: Vec3;
+    handleOut?: Vec3;
 }
 export interface CurveNode extends NodeBase, MaterialNode, OperationNode, MirrorNode {
     kind: "curve";
+    version?: number;
+    curveType?: "spline" | "bezier";
+    closed?: boolean;
     hidden: boolean;
     primitive: PrimitiveType;
     density: number;
@@ -186,6 +192,9 @@ export interface NodeUpdate {
     roundness?: number;
     smoothing?: number;
     points?: CurvePoint[];
+    version?: number;
+    curveType?: "spline" | "bezier";
+    closed?: boolean;
     text?: string;
     fontFamily?: string;
     weight?: number;
@@ -211,6 +220,7 @@ export interface NodeUpdate {
     enabled?: boolean;
     tag?: string;
     mirrors?: MirrorPlanes;
+    scriptInstanceId?: number;
 }
 export interface CreateNodeInput<K extends NodeKind = NodeKind> {
     kind: K;
@@ -239,6 +249,11 @@ export interface MaterialData {
     surfaceOpacity: number;
     volumetricEnabled: boolean;
 }
+/** Native renderer material data and shader slots supplied by an asset catalog. */
+export interface MaterialResource {
+    data: Record<string, JsonValue>;
+    shaders: readonly (Record<string, JsonValue> | null)[];
+}
 export interface Material {
     id: number;
     data: MaterialData;

package/dist/validation.js

@@ -1,7 +1,7 @@
 import { KakapoValidationError } from "./errors.js";
 import { kindFromWire, parentMap, wireToNode } from "./scene.js";
 const CONTAINERS = new Set(["union", "group"]);
-const GEOMETRY = new Set(["primitive", "curve", "text", "field", "svg", "mesh", "decal", "openScad"]);
+const GEOMETRY = new Set(["primitive", "curve", "text", "field", "svg", "mesh", "openScad"]);
 function fail(message, operation, path, received, expected, hint, code = "VALIDATION_ERROR") {
     throw new KakapoValidationError(message, { code, operation, path, received, expected, hint });
 }
@@ -79,6 +79,9 @@ export function assertNode(node, scene, operation) {
             assertFinite(node.resolution, operation, "resolution", 0.01, 1);
             assertFinite(node.thickness, operation, "thickness", -1, 10);
             assertFinite(node.inflation, operation, "inflation", -10, 10);
+            if (node.scriptInstanceId !== undefined && (!Number.isSafeInteger(node.scriptInstanceId) || node.scriptInstanceId < 0 || node.scriptInstanceId >= 0xffffffff)) {
+                fail("scriptInstanceId must identify a stored script instance.", operation, "scriptInstanceId", node.scriptInstanceId, "safe integer from 0 through 4294967294");
+            }
             break;
         case "light":
             assertColor(node.color, operation, "color");
@@ -92,9 +95,26 @@ export function assertNode(node, scene, operation) {
             assertFinite(node.density, operation, "density", 1);
             assertFinite(node.roundness, operation, "roundness", 0);
             assertFinite(node.smoothing, operation, "smoothing", 0, 1);
+            if (node.version !== undefined)
+                assertId(node.version, operation, "version");
+            if (node.curveType !== undefined && node.curveType !== "spline" && node.curveType !== "bezier") {
+                fail("Unknown curve type.", operation, "curveType", node.curveType, "spline or bezier");
+            }
+            if (node.closed !== undefined && typeof node.closed !== "boolean") {
+                fail("closed must be a boolean.", operation, "closed", node.closed, "boolean");
+            }
             if (!node.points.length)
                 fail("A curve requires at least one point.", operation, "points", node.points, "non-empty curve points");
-            node.points.forEach((p, i) => { assertVec3(p.position, operation, `points[${i}].position`); assertVec3(p.rotation, operation, `points[${i}].rotation`); assertVec3(p.scale, operation, `points[${i}].scale`); });
+            node.points.forEach((point, index) => {
+                assertVec3(point.position, operation, `points[${index}].position`);
+                assertVec3(point.rotation, operation, `points[${index}].rotation`);
+                assertVec3(point.scale, operation, `points[${index}].scale`);
+                assertFinite(point.round, operation, `points[${index}].round`, 0, 1);
+                if (point.handleIn !== undefined)
+                    assertVec3(point.handleIn, operation, `points[${index}].handleIn`);
+                if (point.handleOut !== undefined)
+                    assertVec3(point.handleOut, operation, `points[${index}].handleOut`);
+            });
             break;
         case "text":
             if (!node.text.length)

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "@womp/kakapo-sdk",
-  "version": "0.2.2",
-  "description": "Typed Node.js and browser SDK for controlling Kakapo over WebSocket",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wompxyz/kakapo-sdk.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "clean": "node -e \"const f=require('node:fs');for(const p of ['dist','dist-test'])f.rmSync(p,{recursive:true,force:true})\"",
-    "build": "yarn clean && tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "yarn typecheck",
-    "build:test": "tsc -p tsconfig.test.json",
-    "test": "yarn build && yarn build:test && node --test dist-test/test/unit.test.js",
-    "test:live": "yarn build && yarn build:test && node --test dist-test/test/live.test.js",
-    "test:all": "yarn test && yarn test:live",
-    "prepack": "yarn build"
-  },
-  "dependencies": {
-    "fast-json-patch": "^3.1.1",
-    "ws": "^8.18.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3"
-  },
-  "license": "MIT"
-}
+{
+  "name": "@womp/kakapo-sdk",
+  "version": "0.3.1",
+  "description": "Typed Node.js and browser SDK for controlling Kakapo over WebSocket",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wompxyz/kakapo-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"const f=require('node:fs');for(const p of ['dist','dist-test'])f.rmSync(p,{recursive:true,force:true})\"",
+    "build": "yarn clean && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "yarn typecheck",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "yarn build && yarn build:test && node --test dist-test/test/unit.test.js",
+    "test:live": "yarn build && yarn build:test && node --test dist-test/test/live.test.js",
+    "test:all": "yarn test && yarn test:live",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "fast-json-patch": "^3.1.1",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT"
+}