@womp/kakapo-sdk 0.1.0

package/dist/api.js

@@ -0,0 +1,671 @@
+import { KakapoConnectionError, KakapoRpcError, 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 { KakapoTransport } from "./transport.js";
+import { createNodeHandle } from "./node-handle.js";
+import { assertFont, assertId, assertMaterial, assertScene } from "./validation.js";
+const SCENE_MUTATING_RPCS = new Set([
+    "scene_state_patch", "scene_state_set", "load_scene", "replace_scene", "undo", "redo", "convert_scene",
+]);
+const SCREENSHOT_FRAME_PADDING = 2.4;
+const ISOMETRIC_SCREENSHOT_FRAME_PADDING = 2;
+function isBinaryFrame(message) {
+    return "payload" in message &&
+        message.payload instanceof Uint8Array &&
+        typeof message.width === "number" &&
+        typeof message.height === "number";
+}
+export class KakapoAPI {
+    transport;
+    rawScene;
+    cacheValid = false;
+    fonts;
+    transactionTail = Promise.resolve();
+    draftScene;
+    draftDirty = false;
+    rendererSyncRequired = false;
+    constructor(options = {}) {
+        this.transport = new KakapoTransport({
+            url: options.url ?? "ws://127.0.0.1:5502",
+            requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+            connectTimeoutMs: options.connectTimeoutMs ?? 30_000,
+        });
+    }
+    get isConnected() { return this.transport.connected; }
+    async connect() {
+        await this.transport.connect();
+        try {
+            await this.ping();
+            await this.refreshScene();
+        }
+        catch (error) {
+            this.disconnect();
+            throw error;
+        }
+    }
+    disconnect() {
+        this.transport.disconnect();
+        this.cacheValid = false;
+        this.rawScene = undefined;
+        this.fonts = undefined;
+    }
+    async ping() {
+        const result = await this.call("ping");
+        if (result !== "pong") {
+            throw new KakapoConnectionError(`Kakapo ping returned '${String(result)}' instead of 'pong'.`, {
+                code: "INVALID_PING_RESPONSE",
+                operation: "ping",
+                received: result,
+                expected: "pong",
+            });
+        }
+        return "pong";
+    }
+    async rpc(method, params = []) {
+        const result = await this.call(method, params);
+        if (SCENE_MUTATING_RPCS.has(method)) {
+            this.cacheValid = false;
+            this.rendererSyncRequired = true;
+        }
+        return result;
+    }
+    newToken() { return this.transport.newToken(); }
+    waitForToken(token, timeoutMs) { return this.transport.waitForToken(token, timeoutMs); }
+    async refreshScene() {
+        const result = await this.call("scene_state_get");
+        const scene = parseJsonResult(result, "scene_state_get");
+        assertScene(scene, "refreshScene");
+        this.rawScene = scene;
+        this.cacheValid = true;
+        return this.getScene();
+    }
+    getScene() {
+        return deepClone(toPublicScene(this.requireScene("getScene")));
+    }
+    editScene(callback) {
+        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);
+                if (operations.length) {
+                    await this.sendPatch(operations);
+                    this.rendererSyncRequired = true;
+                }
+                this.rawScene = draft;
+                this.cacheValid = true;
+                return result;
+            }
+            catch (error) {
+                this.cacheValid = false;
+                try {
+                    await this.refreshScene();
+                }
+                catch {
+                    // Preserve the transaction error. The next operation will report stale cache.
+                }
+                throw error;
+            }
+            finally {
+                this.draftScene = undefined;
+                this.draftDirty = false;
+            }
+        });
+        this.transactionTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    applyScenePatch(operations) {
+        const candidate = applyJsonPatch(this.requireDraft("applyScenePatch"), operations);
+        assertScene(candidate, "applyScenePatch");
+        this.draftScene = candidate;
+        this.draftDirty = true;
+        return this.getScene();
+    }
+    listNodes(options = {}) {
+        const scene = this.requireScene("listNodes");
+        return Object.keys(scene.nodes).map(Number).sort((a, b) => a - b).map((id) => wireToNode(scene, id)).filter((node) => (options.kind === undefined || node.kind === options.kind) && (options.parentId === undefined || node.parentId === options.parentId)).map(deepClone);
+    }
+    findNodes(options) {
+        const scene = this.requireScene("findNodes");
+        const nodes = this.listNodes({ kind: options.kind });
+        return nodes.filter((node) => {
+            if (options.name !== undefined && node.name !== options.name)
+                return false;
+            if (options.ancestorId === undefined)
+                return true;
+            let cursor = node.parentId;
+            while (cursor !== null) {
+                if (cursor === options.ancestorId)
+                    return true;
+                cursor = wireToNode(scene, cursor).parentId;
+            }
+            return false;
+        });
+    }
+    getNode(id) {
+        assertId(id, "getNode", "nodeId", true);
+        return deepClone(wireToNode(this.requireScene("getNode"), id));
+    }
+    node(id, kind) {
+        return createNodeHandle({
+            readNode: (nodeId) => this.getNode(nodeId),
+            saveNode: (nodeId, changes) => this.saveNode(nodeId, changes),
+        }, id, kind);
+    }
+    getNodeName(id) { return this.getNode(id).name; }
+    getNodeParent(id) { const parentId = this.getNode(id).parentId; return parentId === null ? null : this.getNode(parentId); }
+    getNodeChildren(id) { const scene = this.requireScene("getNodeChildren"); this.getNode(id); return orderedChildren(scene, id).map((child) => this.getNode(child)); }
+    getNodeBoundingBox(id) { return this.getNodesBoundingBox([id]); }
+    async getNodesBoundingBox(ids) {
+        this.assertEngineReadAllowed("getNodesBoundingBox");
+        if (!ids.length)
+            throw new KakapoValidationError("getNodesBoundingBox requires at least one node ID.", { code: "EMPTY_NODE_IDS", operation: "getNodesBoundingBox", path: "ids", received: ids, expected: "non-empty node ID array" });
+        ids.forEach((id) => this.getNode(id));
+        await this.ensureRendererReady();
+        const result = parseJsonResult(await this.call("get_bounding_box", ids), "get_bounding_box");
+        const bounds = {
+            min: result.p0,
+            max: result.p1,
+            transform: { position: result.pos, rotation: result.rot, scale: result.size },
+        };
+        const values = [
+            bounds.min.x, bounds.min.y, bounds.min.z,
+            bounds.max.x, bounds.max.y, bounds.max.z,
+        ];
+        if (values.some((value) => !Number.isFinite(value)) ||
+            bounds.min.x > bounds.max.x || bounds.min.y > bounds.max.y || bounds.min.z > bounds.max.z) {
+            throw new KakapoValidationError("Kakapo did not return renderable bounds for the requested nodes.", {
+                code: "EMPTY_BOUNDING_BOX",
+                operation: "getNodesBoundingBox",
+                path: "ids",
+                received: ids,
+                expected: "visible renderer geometry",
+                hint: "Use a visible top-level Area containing Union geometry.",
+            });
+        }
+        return bounds;
+    }
+    async captureScreenshot(options) {
+        this.assertEngineReadAllowed("captureScreenshot");
+        const { targetId, timeoutMs } = options;
+        if (targetId !== undefined && options.targetIds !== undefined) {
+            throw new KakapoValidationError("captureScreenshot accepts targetId or targetIds, not both.", {
+                code: "AMBIGUOUS_SCREENSHOT_TARGET",
+                operation: "captureScreenshot",
+                expected: "one target selector",
+            });
+        }
+        const targetIds = options.targetIds ?? (targetId !== undefined
+            ? [targetId]
+            : this.listNodes({ parentId: 0 })
+                .filter((node) => node.kind !== "light" && (!("hidden" in node) || !node.hidden))
+                .map(({ id }) => id));
+        if (!targetIds.length) {
+            throw new KakapoValidationError("There is no visible scene geometry to capture.", {
+                code: "EMPTY_SCREENSHOT_TARGET",
+                operation: "captureScreenshot",
+                expected: "at least one visible node",
+            });
+        }
+        targetIds.forEach((id) => this.getNode(id));
+        const view = options.view ?? "isometric";
+        const bounds = await this.getNodesBoundingBox(targetIds);
+        const direction = this.screenshotDirection(view);
+        const framePadding = view === "isometric" ? ISOMETRIC_SCREENSHOT_FRAME_PADDING : SCREENSHOT_FRAME_PADDING;
+        const center = {
+            x: (bounds.min.x + bounds.max.x) * 0.5,
+            y: (bounds.min.y + bounds.max.y) * 0.5,
+            z: (bounds.min.z + bounds.max.z) * 0.5,
+        };
+        const size = {
+            x: (bounds.max.x - bounds.min.x) * framePadding,
+            y: (bounds.max.y - bounds.min.y) * framePadding,
+            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);
+        return {
+            data: message.payload,
+            mediaType: "image/jpeg",
+            width: message.width,
+            height: message.height,
+            view,
+            targetId: targetId ?? (targetIds.length === 1 ? targetIds[0] : 0),
+        };
+    }
+    async ensureRendererReady() {
+        if (!this.rendererSyncRequired)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        await this.captureRendererFrame();
+        this.rendererSyncRequired = false;
+    }
+    async captureRendererFrame(timeoutMs) {
+        const token = this.newToken();
+        const waiting = this.waitForToken(token, timeoutMs);
+        await this.call("get_color_buffer", [[token]]);
+        const message = await waiting;
+        if (!isBinaryFrame(message)) {
+            const error = "error" in message ? String(message.error) : "Kakapo returned a non-binary renderer frame";
+            throw new KakapoRpcError("get_color_buffer", error);
+        }
+        return message;
+    }
+    screenshotDirection(view) {
+        // Kakapo's center_cam builds its framing basis with world Y as the up
+        // vector. Exact +/-Y directions make that basis singular, so match the
+        // editor's imperceptible axial offset for stable top and bottom framing.
+        const axialOffset = Math.cos(1.57);
+        const axialDirection = Math.sin(1.57);
+        const directions = {
+            front: { x: 1, y: 0, z: 0 },
+            back: { x: -1, y: 0, z: 0 },
+            left: { x: 0, y: 0, z: -1 },
+            right: { x: 0, y: 0, z: 1 },
+            top: { x: -axialOffset, y: -axialDirection, z: 0 },
+            bottom: { x: -axialOffset, y: axialDirection, z: 0 },
+            isometric: { x: -1 / Math.sqrt(3), y: -1 / Math.sqrt(3), z: -1 / Math.sqrt(3) },
+        };
+        return directions[view];
+    }
+    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 initial = defaultNode(input.kind, id, input.name ?? "");
+        const node = this.mergeNode(initial, input.properties ?? {});
+        const children = this.treeArrays(scene);
+        const siblings = children[String(input.parentId)] ?? [];
+        const index = input.index ?? siblings.length;
+        if (!Number.isSafeInteger(index) || index < 0 || index > siblings.length)
+            throw new KakapoValidationError(`Child index ${index} is outside the valid range.`, { code: "INVALID_CHILD_INDEX", operation: "createNode", path: "index", received: index, expected: `integer from 0 through ${siblings.length}` });
+        siblings.splice(index, 0, id);
+        children[String(input.parentId)] = siblings;
+        scene.nodes[String(id)] = nodeToWire(node);
+        scene.tree = encodeTree(children);
+        scene.ext = this.extWithNode(scene, node);
+        this.draftDirty = true;
+        return deepClone(wireToNode(scene, id));
+    }
+    cloneNode(id, options = {}) {
+        const node = this.getNode(id);
+        if (id === 0)
+            throw this.rootError("cloneNode");
+        const { id: _id, kind: _kind, name: _name, parentId: _parentId, ...properties } = deepClone(node);
+        return this.createNode({ kind: node.kind, parentId: options.parentId ?? node.parentId, name: options.name ?? (node.name ? `${node.name} Copy` : ""), properties, index: options.index });
+    }
+    updateNode(id, changes) {
+        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);
+        scene.ext = this.extWithNode(scene, updated);
+        this.draftDirty = true;
+        return deepClone(wireToNode(scene, id));
+    }
+    deleteNode(id, options = {}) {
+        const scene = this.requireDraft("deleteNode");
+        if (id === 0)
+            throw this.rootError("deleteNode");
+        const tree = this.treeArrays(scene);
+        const node = wireToNode(scene, id);
+        const toDelete = new Set([id]);
+        if (options.recursive !== false) {
+            const visit = (parent) => {
+                for (const child of tree[String(parent)] ?? []) {
+                    toDelete.add(child);
+                    visit(child);
+                }
+            };
+            visit(id);
+        }
+        if (node.parentId !== null) {
+            const siblings = tree[String(node.parentId)] ?? [];
+            const index = siblings.indexOf(id);
+            if (options.recursive === false)
+                siblings.splice(index, 1, ...(tree[String(id)] ?? []));
+            else
+                siblings.splice(index, 1);
+            tree[String(node.parentId)] = siblings;
+        }
+        for (const deleted of toDelete) {
+            delete scene.nodes[String(deleted)];
+            delete tree[String(deleted)];
+            if (scene.ext)
+                delete scene.ext[String(deleted)];
+        }
+        scene.tree = encodeTree(tree);
+        this.draftDirty = true;
+        return [...toDelete].sort((a, b) => a - b);
+    }
+    setNodeParent(id, parentId, index) {
+        const scene = this.requireDraft("setNodeParent");
+        if (id === 0)
+            throw this.rootError("setNodeParent");
+        const node = wireToNode(scene, id);
+        if (!scene.nodes[String(parentId)])
+            throw missingNode(parentId, "setNodeParent");
+        if (id === parentId)
+            throw new KakapoValidationError("A node cannot be its own parent.", { code: "TREE_CYCLE", operation: "setNodeParent", path: "parentId", received: parentId, expected: "different non-descendant node" });
+        let cursor = parentId;
+        while (cursor !== null) {
+            if (cursor === id)
+                throw new KakapoValidationError("A node cannot be parented below its descendant.", { code: "TREE_CYCLE", operation: "setNodeParent", path: "parentId", received: parentId, expected: "non-descendant node" });
+            cursor = wireToNode(scene, cursor).parentId;
+        }
+        const tree = this.treeArrays(scene);
+        if (node.parentId !== null)
+            tree[String(node.parentId)] = (tree[String(node.parentId)] ?? []).filter((child) => child !== id);
+        const siblings = tree[String(parentId)] ?? [];
+        const targetIndex = index ?? siblings.length;
+        if (!Number.isSafeInteger(targetIndex) || targetIndex < 0 || targetIndex > siblings.length)
+            throw new KakapoValidationError("Parent index is outside the child list.", { code: "INVALID_CHILD_INDEX", operation: "setNodeParent", path: "index", received: targetIndex, expected: `integer from 0 through ${siblings.length}` });
+        siblings.splice(targetIndex, 0, id);
+        tree[String(parentId)] = siblings;
+        scene.tree = encodeTree(tree);
+        this.draftDirty = true;
+        return deepClone(wireToNode(scene, id));
+    }
+    setNodeName(id, name) {
+        const scene = this.requireDraft("setNodeName");
+        wireToNode(scene, id);
+        if (typeof name !== "string" || name.includes("\0"))
+            throw new KakapoValidationError("Node name must be a string without null bytes.", { code: "INVALID_NODE_NAME", operation: "setNodeName", path: "name", received: name, expected: "string without null bytes" });
+        scene.ext = this.extWithName(scene, id, name);
+        this.draftDirty = true;
+        return deepClone(wireToNode(scene, id));
+    }
+    setNodeTransform(id, transform) { const current = this.getNode(id); return this.updateNode(id, { transform: { ...current.transform, ...transform } }); }
+    setNodePosition(id, position) { return this.setNodeTransform(id, { position }); }
+    setNodeRotation(id, rotation) { return this.setNodeTransform(id, { rotation }); }
+    setNodeScale(id, scale) { if (this.getNode(id).kind === "light")
+        throw new KakapoValidationError("Light nodes use a 2D light size instead of node scale.", { code: "UNSUPPORTED_NODE_PROPERTY", operation: "setNodeScale", path: "scale", received: scale, expected: "non-Light node", hint: "Use updateNode(id, { size: {x, y} }) for a Light." }); return this.setNodeTransform(id, { scale }); }
+    setNodeVisible(id, visible) { if (!("hidden" in this.getNode(id)))
+        throw this.unsupported("setNodeVisible", id, "visibility"); return this.updateNode(id, { hidden: !visible }); }
+    setNodePickable(id, pickable) { return this.updateNode(id, { pickable }); }
+    setNodeMaterial(id, materialId) { if (!("materialId" in this.getNode(id)))
+        throw this.unsupported("setNodeMaterial", id, "material"); return this.updateNode(id, { materialId }); }
+    setNodeOperation(id, operation) { if (!("operation" in this.getNode(id)))
+        throw this.unsupported("setNodeOperation", id, "CSG operation"); return this.updateNode(id, { operation }); }
+    setTextContent(id, text) { this.expectKind(id, "text", "setTextContent"); return this.updateNode(id, { text }); }
+    setTextFont(id, fontFamily, weight = 400, italic = false) { this.expectKind(id, "text", "setTextFont"); if (this.fonts)
+        assertFont(this.fonts, fontFamily, weight, italic, "setTextFont"); return this.updateNode(id, { fontFamily, weight, italic }); }
+    setSvgPaths(id, paths) { this.expectKind(id, "svg", "setSvgPaths"); return this.updateNode(id, { paths }); }
+    setMeshSource(id, mesh, meshIndex = 0) { this.expectKind(id, "mesh", "setMeshSource"); return this.updateNode(id, { mesh, meshIndex }); }
+    setFieldSource(id, field) { this.expectKind(id, "field", "setFieldSource"); return this.updateNode(id, { field }); }
+    setDecalSource(id, image) { this.expectKind(id, "decal", "setDecalSource"); return this.updateNode(id, { image }); }
+    setSocketTag(id, tag) { this.expectKind(id, "socket", "setSocketTag"); return this.updateNode(id, { tag }); }
+    setOpenScadScript(id, scriptId, params = {}) { this.expectKind(id, "openScad", "setOpenScadScript"); return this.updateNode(id, { scriptId, params }); }
+    listMaterials() {
+        const scene = this.requireScene("listMaterials");
+        return Object.entries(scene.storage.materials ?? {})
+            .flatMap(([key, raw]) => {
+            const id = parseSafePositiveId(key);
+            return id === undefined ? [] : [wireToMaterial(id, raw)];
+        })
+            .sort((a, b) => a.id - b.id)
+            .map(deepClone);
+    }
+    getMaterial(id) { assertId(id, "getMaterial", "materialId"); const raw = this.requireScene("getMaterial").storage.materials?.[String(id)]; if (!raw)
+        throw new KakapoValidationError(`Material ${id} does not exist.`, { code: "MATERIAL_NOT_FOUND", operation: "getMaterial", path: "materialId", received: id, expected: "existing material ID" }); return deepClone(wireToMaterial(id, raw)); }
+    createMaterial(data = {}, shaderIds = []) {
+        const scene = this.requireDraft("createMaterial");
+        const materials = scene.storage.materials ?? (scene.storage.materials = {});
+        const id = nextId(materials);
+        const material = { id, data: this.mergeMaterialData(defaultMaterialData(), data), shaderIds: [...shaderIds] };
+        assertMaterial(material.data, "createMaterial");
+        materials[String(id)] = materialToWire(material);
+        this.draftDirty = true;
+        return deepClone(material);
+    }
+    updateMaterial(id, data, shaderIds) {
+        const scene = this.requireDraft("updateMaterial");
+        const currentRaw = scene.storage.materials?.[String(id)];
+        if (!currentRaw)
+            throw this.materialMissing(id, "updateMaterial");
+        const current = wireToMaterial(id, currentRaw);
+        const updated = { id, data: this.mergeMaterialData(current.data, data), shaderIds: shaderIds ? [...shaderIds] : current.shaderIds };
+        assertMaterial(updated.data, "updateMaterial");
+        const next = materialToWire(updated);
+        scene.storage.materials[String(id)] = shaderIds === undefined
+            ? { ...currentRaw, data: next.data }
+            : next;
+        this.draftDirty = true;
+        return deepClone(updated);
+    }
+    deleteMaterial(id) {
+        const scene = this.requireDraft("deleteMaterial");
+        if (!scene.storage.materials?.[String(id)])
+            throw this.materialMissing(id, "deleteMaterial");
+        const references = Object.keys(scene.nodes).map(Number).map((nodeId) => wireToNode(scene, nodeId)).filter((node) => "materialId" in node && node.materialId === id).map((node) => node.id);
+        if (references.length)
+            throw new KakapoValidationError(`Material ${id} is still referenced by nodes ${references.join(", ")}.`, { code: "MATERIAL_IN_USE", operation: "deleteMaterial", path: "materialId", received: id, expected: "unreferenced material", hint: "Reassign or delete the listed nodes first.", details: { nodeIds: references } });
+        delete scene.storage.materials[String(id)];
+        this.draftDirty = true;
+    }
+    listOpenScadScripts() { const scripts = this.requireScene("listOpenScadScripts").storage.openscad?.scripts ?? {}; return Object.entries(scripts).map(([id, script]) => ({ id: Number(id), name: script.name ?? "OpenSCAD Script", source: script.source ?? "" })).sort((a, b) => a.id - b.id); }
+    getOpenScadScript(id) { assertId(id, "getOpenScadScript", "scriptId"); const script = this.requireScene("getOpenScadScript").storage.openscad?.scripts?.[String(id)]; if (!script)
+        throw this.scriptMissing(id, "getOpenScadScript"); return { id, name: script.name ?? "OpenSCAD Script", source: script.source ?? "" }; }
+    createOpenScadScript(name, source) {
+        const scene = this.requireDraft("createOpenScadScript");
+        const scripts = scene.storage.openscad?.scripts;
+        if (!scripts)
+            throw new KakapoValidationError("Scene has no OpenSCAD script storage.", { code: "MISSING_STORAGE", operation: "createOpenScadScript", path: "storage.openscad.scripts", expected: "OpenSCAD script object" });
+        const id = nextId(scripts);
+        scripts[String(id)] = { name, source };
+        this.draftDirty = true;
+        return { id, name, source };
+    }
+    updateOpenScadScript(id, changes) {
+        const scene = this.requireDraft("updateOpenScadScript");
+        const current = this.getOpenScadScript(id);
+        const updated = { ...current, ...changes };
+        if (!scene.storage.openscad?.scripts?.[String(id)])
+            throw this.scriptMissing(id, "updateOpenScadScript");
+        scene.storage.openscad.scripts[String(id)] = { name: updated.name, source: updated.source };
+        this.draftDirty = true;
+        return updated;
+    }
+    deleteOpenScadScript(id) {
+        const scene = this.requireDraft("deleteOpenScadScript");
+        if (!scene.storage.openscad?.scripts?.[String(id)])
+            throw this.scriptMissing(id, "deleteOpenScadScript");
+        const references = Object.keys(scene.nodes).map(Number).map((nodeId) => wireToNode(scene, nodeId)).filter((node) => node.kind === "openScad" && node.scriptId === id).map((node) => node.id);
+        if (references.length)
+            throw new KakapoValidationError(`OpenSCAD script ${id} is still referenced by nodes ${references.join(", ")}.`, { code: "SCRIPT_IN_USE", operation: "deleteOpenScadScript", path: "scriptId", received: id, expected: "unreferenced script", hint: "Reassign or delete the listed OpenSCAD nodes first.", details: { nodeIds: references } });
+        delete scene.storage.openscad.scripts[String(id)];
+        this.draftDirty = true;
+    }
+    async validateOpenScad(source, params = {}) {
+        if (typeof source !== "string")
+            throw new KakapoValidationError("OpenSCAD source must be a string.", { code: "INVALID_OPENSCAD_SOURCE", operation: "validateOpenScad", path: "source", received: source, expected: "string" });
+        return parseJsonResult(await this.call("openscad_validate", [{ source, params }]), "openscad_validate");
+    }
+    async listFonts() { if (!this.fonts)
+        this.fonts = parseJsonResult(await this.call("get_fonts"), "get_fonts"); return deepClone(this.fonts); }
+    async reloadFonts() { await this.call("reload_fonts"); this.fonts = undefined; }
+    async reloadMeshes() { await this.call("reload_meshes"); }
+    async reloadFields() { await this.call("reload_fields"); }
+    async reloadDecals() { await this.call("reload_decals"); }
+    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)]);
+        if (result !== undefined && result !== null && result !== "") {
+            throw new KakapoRpcError("scene_state_patch", String(result));
+        }
+    }
+    saveNode(id, changes) {
+        const current = this.getNode(id);
+        const { name, parentId, ...properties } = changes;
+        if (Object.keys(properties).length)
+            this.updateNode(id, properties);
+        if (name !== undefined && name !== current.name)
+            this.setNodeName(id, name);
+        if (parentId !== undefined && parentId !== current.parentId)
+            this.setNodeParent(id, parentId);
+        return this.getNode(id);
+    }
+    requireScene(operation) {
+        if (this.draftScene)
+            return this.draftScene;
+        if (!this.rawScene || !this.cacheValid)
+            throw new KakapoValidationError("The local scene cache is unavailable or stale.", { code: "STALE_SCENE", operation, expected: "fresh scene cache", hint: "Call connect() or refreshScene() before using high-level scene methods." });
+        return this.rawScene;
+    }
+    requireDraft(operation) {
+        if (this.draftScene)
+            return this.draftScene;
+        throw new KakapoValidationError(`${operation} must run inside editScene().`, {
+            code: "SCENE_EDIT_REQUIRED",
+            operation,
+            expected: "active editScene transaction",
+            hint: "Wrap scene mutations in await api.editScene((scene) => { ... }).",
+        });
+    }
+    assertEngineReadAllowed(operation) {
+        if (!this.draftDirty)
+            return;
+        throw new KakapoValidationError(`${operation} cannot run after draft mutations.`, {
+            code: "DIRTY_SCENE_ENGINE_READ",
+            operation,
+            expected: "engine read before the first mutation or after editScene commits",
+            hint: "Finish the transaction, then perform the engine-backed read.",
+        });
+    }
+    createSceneEdit() {
+        return {
+            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)),
+            getNodeName: (id) => this.getNodeName(id),
+            getNodeParent: (id) => this.getNodeParent(id),
+            getNodeChildren: (id) => this.getNodeChildren(id),
+            applyScenePatch: (operations) => this.applyScenePatch(operations),
+            createNode: (input) => this.createNode(input),
+            cloneNode: (id, options) => this.cloneNode(id, options),
+            updateNode: (id, changes) => this.updateNode(id, changes),
+            deleteNode: (id, options) => this.deleteNode(id, options),
+            setNodeParent: (id, parentId, index) => this.setNodeParent(id, parentId, index),
+            setNodeName: (id, name) => this.setNodeName(id, name),
+            setNodeTransform: (id, transform) => this.setNodeTransform(id, transform),
+            setNodePosition: (id, position) => this.setNodePosition(id, position),
+            setNodeRotation: (id, rotation) => this.setNodeRotation(id, rotation),
+            setNodeScale: (id, scale) => this.setNodeScale(id, scale),
+            setNodeVisible: (id, visible) => this.setNodeVisible(id, visible),
+            setNodePickable: (id, pickable) => this.setNodePickable(id, pickable),
+            setNodeMaterial: (id, materialId) => this.setNodeMaterial(id, materialId),
+            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),
+            setSvgPaths: (id, paths) => this.setSvgPaths(id, paths),
+            setMeshSource: (id, mesh, index) => this.setMeshSource(id, mesh, index),
+            setFieldSource: (id, field) => this.setFieldSource(id, field),
+            setDecalSource: (id, image) => this.setDecalSource(id, image),
+            setSocketTag: (id, tag) => this.setSocketTag(id, tag),
+            setOpenScadScript: (id, scriptId, params) => this.setOpenScadScript(id, scriptId, params),
+            listMaterials: () => this.listMaterials(),
+            getMaterial: (id) => this.getMaterial(id),
+            createMaterial: (data, shaderIds) => this.createMaterial(data, shaderIds),
+            updateMaterial: (id, data, shaderIds) => this.updateMaterial(id, data, shaderIds),
+            deleteMaterial: (id) => this.deleteMaterial(id),
+            listOpenScadScripts: () => this.listOpenScadScripts(),
+            getOpenScadScript: (id) => this.getOpenScadScript(id),
+            createOpenScadScript: (name, source) => this.createOpenScadScript(name, source),
+            updateOpenScadScript: (id, changes) => this.updateOpenScadScript(id, changes),
+            deleteOpenScadScript: (id) => this.deleteOpenScadScript(id),
+        };
+    }
+    treeArrays(scene) { return Object.fromEntries(Object.keys(scene.tree ?? {}).map((id) => [id, orderedChildren(scene, Number(id))])); }
+    extWithName(scene, id, name) {
+        const ext = deepClone(scene.ext ?? {});
+        const current = ext[String(id)];
+        ext[String(id)] = { ...(current && typeof current === "object" ? current : {}), name };
+        return ext;
+    }
+    extWithNode(scene, node) {
+        const ext = this.extWithName(scene, node.id, node.name);
+        if (!("mirrors" in node))
+            return ext;
+        const current = ext[String(node.id)];
+        ext[String(node.id)] = {
+            ...current,
+            ...Object.fromEntries(node.mirrors.map((plane, index) => [
+                `mirror_plane_ext_${index}`,
+                {
+                    hideMirrorPlane: plane.hideMirrorPlane,
+                    constraint: plane.constraint,
+                    ...(plane.customRotation ? { customRotation: plane.customRotation } : {}),
+                },
+            ])),
+        };
+        return ext;
+    }
+    mergeNode(node, changes) {
+        const unsafe = changes;
+        if (unsafe.id !== undefined && unsafe.id !== node.id)
+            throw new KakapoValidationError("Node IDs cannot be changed.", { code: "IMMUTABLE_NODE_ID", operation: "updateNode", path: "id", received: unsafe.id, expected: String(node.id) });
+        if (unsafe.kind !== undefined && unsafe.kind !== node.kind)
+            throw new KakapoValidationError("Node kinds cannot be changed.", { code: "IMMUTABLE_NODE_KIND", operation: "updateNode", path: "kind", received: unsafe.kind, expected: node.kind });
+        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"],
+            group: ["hidden"],
+            light: ["color", "power", "collimation", "lightType", "size", "textureFile"],
+            curve: ["hidden", "materialId", "operation", "blend", "primitive", "density", "roundness", "smoothing", "points", "materialNeutralCutout", "mirrors"],
+            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"],
+            field: ["hidden", "materialId", "operation", "blend", "field", "inflation", "colorSampling", "materialNeutralCutout"],
+            decal: ["hidden", "materialId", "image", "global", "colorSampling"],
+            openScad: ["hidden", "materialId", "operation", "blend", "scriptId", "params", "enabled"],
+            socket: ["hidden", "tag"],
+        };
+        const allowed = new Set([...common, ...byKind[node.kind]]);
+        for (const key of Object.keys(unsafe)) {
+            if (!allowed.has(key))
+                throw new KakapoValidationError(`${node.kind} nodes do not support '${key}'.`, { code: "UNSUPPORTED_NODE_PROPERTY", operation: "updateNode", path: key, received: unsafe[key], expected: `one of: ${[...allowed].join(", ")}`, hint: "Use a property supported by this node kind or create the correct node kind." });
+        }
+        const transform = changes.transform ? { ...node.transform, ...changes.transform } : node.transform;
+        return { ...node, ...changes, id: node.id, kind: node.kind, parentId: node.parentId, transform };
+    }
+    mergeMaterialData(current, changes) {
+        return { ...current, ...changes, color: { ...current.color, ...changes.color }, secondaryColor: { ...current.secondaryColor, ...changes.secondaryColor }, subsurface: { ...current.subsurface, ...changes.subsurface } };
+    }
+    expectKind(id, kind, operation) { const node = this.getNode(id); if (node.kind !== kind)
+        throw new KakapoValidationError(`${operation} requires a ${kind} node, but node ${id} is ${node.kind}.`, { code: "WRONG_NODE_KIND", operation, path: "nodeId", received: { id, kind: node.kind }, expected: `${kind} node ID` }); }
+    unsupported(operation, id, property) { const node = this.getNode(id); return new KakapoValidationError(`${node.kind} node ${id} does not support ${property}.`, { code: "UNSUPPORTED_NODE_PROPERTY", operation, path: "nodeId", received: { id, kind: node.kind }, expected: `node kind supporting ${property}` }); }
+    rootError(operation) { return new KakapoValidationError("Scene root node 0 is immutable.", { code: "IMMUTABLE_ROOT", operation, path: "nodeId", received: 0, expected: "non-root node ID" }); }
+    materialMissing(id, operation) { return new KakapoValidationError(`Material ${id} does not exist.`, { code: "MATERIAL_NOT_FOUND", operation, path: "materialId", received: id, expected: "existing material ID" }); }
+    scriptMissing(id, operation) { return new KakapoValidationError(`OpenSCAD script ${id} does not exist.`, { code: "SCRIPT_NOT_FOUND", operation, path: "scriptId", received: id, expected: "existing OpenSCAD script ID" }); }
+    assertOpenScadValid(result, operation) { if (!result.ok)
+        throw new KakapoValidationError(`OpenSCAD validation failed: ${result.error}`, { code: "INVALID_OPENSCAD", operation, path: "source", expected: "compilable OpenSCAD source", hint: "Fix the compiler error and validate the source again.", details: { error: result.error, warnings: result.warnings } }); }
+}