@womp/kakapo-sdk 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+export interface KakapoErrorOptions {
+    code: string;
+    operation?: string;
+    path?: string;
+    received?: unknown;
+    expected?: string;
+    hint?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+export declare class KakapoError extends Error {
+    readonly code: string;
+    readonly operation?: string;
+    readonly path?: string;
+    readonly received?: unknown;
+    readonly expected?: string;
+    readonly hint?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options: KakapoErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export declare class KakapoConnectionError extends KakapoError {
+}
+export declare class KakapoTimeoutError extends KakapoError {
+}
+export declare class KakapoRpcError extends KakapoError {
+    readonly rpcCode?: number;
+    readonly method: string;
+    constructor(method: string, message: string, rpcCode?: number, details?: Record<string, unknown>);
+}
+export declare class KakapoValidationError extends KakapoError {
+    constructor(message: string, options?: Omit<KakapoErrorOptions, "code"> & {
+        code?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,56 @@
+export class KakapoError extends Error {
+    code;
+    operation;
+    path;
+    received;
+    expected;
+    hint;
+    details;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        this.code = options.code;
+        this.operation = options.operation;
+        this.path = options.path;
+        this.received = options.received;
+        this.expected = options.expected;
+        this.hint = options.hint;
+        this.details = options.details;
+    }
+    toJSON() {
+        return Object.fromEntries(Object.entries({
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            operation: this.operation,
+            path: this.path,
+            received: this.received,
+            expected: this.expected,
+            hint: this.hint,
+            details: this.details,
+        }).filter(([, value]) => value !== undefined));
+    }
+}
+export class KakapoConnectionError extends KakapoError {
+}
+export class KakapoTimeoutError extends KakapoError {
+}
+export class KakapoRpcError extends KakapoError {
+    rpcCode;
+    method;
+    constructor(method, message, rpcCode, details) {
+        super(`Kakapo RPC '${method}' failed: ${message}`, {
+            code: "RPC_ERROR",
+            operation: method,
+            details: { ...details, rpcCode },
+            hint: "Correct the parameters or inspect the engine log for the backend failure.",
+        });
+        this.method = method;
+        this.rpcCode = rpcCode;
+    }
+}
+export class KakapoValidationError extends KakapoError {
+    constructor(message, options = {}) {
+        super(message, { code: options.code ?? "VALIDATION_ERROR", ...options });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { KakapoAPI } from "./api.js";
+export type { SceneEdit } from "./api.js";
+export { KakapoError, KakapoConnectionError, KakapoTimeoutError, 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

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

package/dist/node-handle.d.ts

@@ -0,0 +1,32 @@
+import type { KakapoNode, NodeKind, NodeUpdate, Vec3 } from "./types.js";
+type NodeOfKind<K extends NodeKind> = Extract<KakapoNode, {
+    kind: K;
+}>;
+export interface NodeHandleActions<N extends KakapoNode> {
+    readonly dirty: boolean;
+    readonly value: N;
+    save(): N;
+    reset(): void;
+}
+type NodeHandleAliases<N extends KakapoNode> = {
+    position: Vec3;
+    rotation: Vec3;
+} & (N extends {
+    kind: "light";
+} ? {} : {
+    scale: Vec3;
+}) & (N extends {
+    hidden: boolean;
+} ? {
+    visible: boolean;
+} : {});
+export type NodeHandle<N extends KakapoNode = KakapoNode> = Omit<N, "id" | "kind"> & Readonly<Pick<N, "id" | "kind">> & NodeHandleAliases<N> & NodeHandleActions<N>;
+export interface NodeHandleOwner {
+    readNode(id: number): KakapoNode;
+    saveNode(id: number, changes: NodeUpdate & {
+        name?: string;
+        parentId?: number;
+    }): KakapoNode;
+}
+export declare function createNodeHandle<K extends NodeKind>(owner: NodeHandleOwner, id: number, expectedKind?: K): NodeHandle<NodeOfKind<K>>;
+export {};

package/dist/node-handle.js

@@ -0,0 +1,69 @@
+import { deepClone } from "./scene.js";
+const RESERVED_KEYS = new Set(["dirty", "value", "save", "reset"]);
+const TRANSFORM_KEYS = new Set(["position", "rotation", "scale"]);
+function same(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function createNodeHandle(owner, id, expectedKind) {
+    let original = owner.readNode(id);
+    if (expectedKind !== undefined && original.kind !== expectedKind) {
+        throw new TypeError(`Node ${id} is ${original.kind}, not ${expectedKind}.`);
+    }
+    let draft = deepClone(original);
+    const actions = {
+        get dirty() { return !same(original, draft); },
+        get value() { return deepClone(draft); },
+        save() {
+            const changes = {};
+            for (const key of Object.keys(draft)) {
+                if (key === "id" || key === "kind")
+                    continue;
+                if (same(original[key], draft[key]))
+                    continue;
+                changes[key] = deepClone(draft[key]);
+            }
+            const saved = owner.saveNode(id, changes);
+            original = deepClone(saved);
+            draft = deepClone(saved);
+            return deepClone(saved);
+        },
+        reset() {
+            original = owner.readNode(id);
+            draft = deepClone(original);
+        },
+    };
+    return new Proxy(actions, {
+        get(target, property, receiver) {
+            if (typeof property === "string" && TRANSFORM_KEYS.has(property)) {
+                return deepClone(draft.transform[property]);
+            }
+            if (property === "visible" && "hidden" in draft)
+                return !draft.hidden;
+            if (typeof property === "string" && property in draft) {
+                return deepClone(draft[property]);
+            }
+            return target[property];
+        },
+        set(_target, property, value) {
+            if (property === "id" || property === "kind") {
+                throw new TypeError(`Node ${String(property)} is immutable.`);
+            }
+            if (typeof property === "string" && TRANSFORM_KEYS.has(property)) {
+                if (property === "scale" && draft.kind === "light") {
+                    throw new TypeError("Light nodes use a 2D size instead of 3D scale.");
+                }
+                draft.transform[property] = deepClone(value);
+                return true;
+            }
+            if (property === "visible" && "hidden" in draft) {
+                draft.hidden = !value;
+                return true;
+            }
+            if (typeof property !== "string" || RESERVED_KEYS.has(property) || !(property in draft)) {
+                throw new TypeError(`Unknown or readonly node property '${String(property)}'.`);
+            }
+            draft[property] = deepClone(value);
+            return true;
+        },
+    });
+}

package/dist/scene.d.ts

@@ -0,0 +1,59 @@
+import { KakapoValidationError } from "./errors.js";
+import type { JsonPatchOperation, KakapoNode, Material, MaterialData, NodeKind, Scene, Transform } from "./types.js";
+export interface WireNode {
+    type: number;
+    [key: string]: unknown;
+}
+export interface WireScene {
+    version?: number;
+    name?: string;
+    nodes: Record<string, WireNode>;
+    tree: Record<string, Record<string, number>>;
+    ext?: Record<string, unknown>;
+    storage: {
+        materials?: Record<string, {
+            data?: Record<string, unknown>;
+            shaders?: number[];
+            shader?: number;
+        }>;
+        shaders?: Record<string, unknown>;
+        openscad?: {
+            scripts?: Record<string, {
+                name?: string;
+                source?: string;
+            }>;
+        };
+        scripts?: Record<string, unknown>;
+        animations?: Record<string, unknown>;
+    };
+    properties?: Record<string, unknown>;
+    camera?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare const identityTransform: () => Transform;
+export declare function deepClone<T>(value: T): T;
+export declare function parseJsonResult<T>(value: unknown, operation: string): T;
+export declare function kindFromWire(type: number): NodeKind;
+export declare function kindToWire(kind: NodeKind): number;
+export declare function parentMap(scene: WireScene): Map<number, number>;
+export declare function orderedChildren(scene: WireScene, parentId: number): number[];
+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 nodeToWire(node: KakapoNode): WireNode;
+export declare const defaultMaterialData: () => MaterialData;
+export declare function wireToMaterial(id: number, raw: {
+    data?: Record<string, unknown>;
+    shaders?: number[];
+    shader?: number;
+}): Material;
+export declare function materialToWire(material: Material): {
+    data: Record<string, unknown>;
+    shaders?: number[];
+};
+export declare function parseSafePositiveId(value: string): number | undefined;
+export declare function toPublicScene(raw: WireScene): Scene;
+export declare function missingNode(id: number, operation: string): KakapoValidationError;
+export declare function applyJsonPatch<T>(document: T, operations: readonly JsonPatchOperation[]): T;
+export declare function nextId(record: Record<string, unknown>): number;
+export declare function escapePointer(value: string): string;

package/dist/scene.js

@@ -0,0 +1,397 @@
+import { KakapoValidationError } from "./errors.js";
+const KINDS = [
+    "primitive", "union", "light", "curve", "group", "text", "field", "svg", "mesh", "decal", "openScad", "socket",
+];
+const OPERATIONS = ["subtract", "union", "brush", "intersect"];
+const PRIMITIVES = [
+    "sphere", "cylinder", "box", "cone", "torus", "link", "hexagon", "triangular", "octahedron", "pyramid", "glyph", "field", "ellipsoid", "capsule",
+];
+const FIELD_SAMPLING = ["ignore", "average", "override", "overrideMaterial", "multiply"];
+const TEXT_WRAP = ["disabled", "always", "whiteSpace"];
+const TEXT_ALIGN = ["left", "center", "right"];
+const LIGHT_TYPES = ["rect", "sphere", "distant"];
+const v2 = (x = 0, y = 0) => ({ x, y });
+const v3 = (x = 0, y = x, z = x) => ({ x, y, z });
+export const identityTransform = () => ({ position: v3(0), rotation: v3(0), scale: v3(1) });
+export function deepClone(value) {
+    return structuredClone(value);
+}
+export function parseJsonResult(value, operation) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch (cause) {
+        throw new KakapoValidationError(`Kakapo RPC '${operation}' returned invalid nested JSON.`, {
+            code: "INVALID_RPC_JSON",
+            operation,
+            received: value.slice(0, 300),
+            expected: "valid JSON string",
+            cause,
+        });
+    }
+}
+export function kindFromWire(type) {
+    const kind = KINDS[type];
+    if (!kind) {
+        throw new KakapoValidationError(`Unknown Kakapo node type '${type}'.`, {
+            code: "UNKNOWN_NODE_TYPE",
+            operation: "decodeScene",
+            path: "node.type",
+            received: type,
+            expected: "integer from 0 through 11",
+        });
+    }
+    return kind;
+}
+export function kindToWire(kind) {
+    return KINDS.indexOf(kind);
+}
+function num(value, fallback) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return fallback;
+}
+function bool(value, fallback) { return typeof value === "boolean" ? value : fallback; }
+function str(value, fallback = "") { return typeof value === "string" ? value : fallback; }
+function vec2(value, fallback = v2()) {
+    const o = value && typeof value === "object" ? value : {};
+    return { x: num(o.x, fallback.x), y: num(o.y, fallback.y) };
+}
+function vec3(value, fallback = v3()) {
+    const o = value && typeof value === "object" ? value : {};
+    return { x: num(o.x, fallback.x), y: num(o.y, fallback.y), z: num(o.z, fallback.z) };
+}
+export function parentMap(scene) {
+    const result = new Map();
+    for (const [parent, children] of Object.entries(scene.tree ?? {})) {
+        for (const child of Object.values(children))
+            result.set(child, Number(parent));
+    }
+    return result;
+}
+export function orderedChildren(scene, parentId) {
+    return Object.entries(scene.tree?.[String(parentId)] ?? {})
+        .sort(([a], [b]) => Number.parseInt(a, 16) - Number.parseInt(b, 16))
+        .map(([, id]) => id);
+}
+export function encodeTree(tree) {
+    const result = {};
+    for (const [parent, children] of Object.entries(tree)) {
+        if (children.length === 0)
+            continue;
+        result[parent] = Object.fromEntries(children.map((id, index) => [((index + 1) * 0x10000).toString(16).padStart(8, "0"), id]));
+    }
+    return result;
+}
+function nodeName(scene, id) {
+    const ext = scene.ext?.[String(id)];
+    return ext && typeof ext === "object" ? str(ext.name) : "";
+}
+function record(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function mirrorPlane(scene, id, raw, index) {
+    const plane = record(raw[`mirror_plane_${index}`]);
+    const ext = record(record(scene.ext?.[String(id)])[`mirror_plane_ext_${index}`]);
+    const constraint = Math.max(0, Math.min(3, Math.round(num(ext.constraint, 0))));
+    return {
+        position: vec3(plane.position),
+        rotation: vec3(plane.rotation),
+        value: num(plane.value, -1),
+        hide: num(plane.hide, 0),
+        hideMirrorPlane: bool(ext.hideMirrorPlane, false),
+        constraint,
+        ...(ext.customRotation ? { customRotation: vec3(ext.customRotation) } : {}),
+    };
+}
+function mirrorPlanes(scene, id, raw) {
+    return [0, 1, 2, 3].map((index) => mirrorPlane(scene, id, raw, index));
+}
+function baseNode(scene, id, raw) {
+    return {
+        id,
+        kind: kindFromWire(raw.type),
+        name: nodeName(scene, id),
+        parentId: parentMap(scene).get(id) ?? null,
+        transform: {
+            position: vec3(raw.pos),
+            rotation: vec3(raw.rot),
+            scale: raw.type === 2 ? v3(1) : vec3(raw.size, v3(1)),
+        },
+        pickable: !bool(raw.pick_disabled, false),
+    };
+}
+function materialId(value) {
+    const id = num(value, 0);
+    return id === 0 ? null : id;
+}
+function decodeCurvePoint(value) {
+    const p = value && typeof value === "object" ? 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),
+    };
+}
+function decodeSvgPaths(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((path) => {
+        const p = path && typeof path === "object" ? path : {};
+        return {
+            closed: bool(p.closed, true),
+            segments: Array.isArray(p.segments) ? p.segments.map((segment) => {
+                const s = segment && typeof segment === "object" ? segment : {};
+                return { point: vec2(s.point), handleIn: vec2(s.handle_in), handleOut: vec2(s.handle_out) };
+            }) : [],
+        };
+    });
+}
+export function wireToNode(scene, id) {
+    const raw = scene.nodes[String(id)];
+    if (!raw)
+        throw missingNode(id, "getNode");
+    const base = baseNode(scene, id, raw);
+    const hidden = num(raw.hide, 0) !== 0;
+    const operation = OPERATIONS[num(raw.op, 1)] ?? "union";
+    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 "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 "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" };
+        case "field": return { ...base, kind: "field", hidden, materialId: material, operation, blend: num(raw.blend, 0), field: str(raw.field, "empty"), inflation: num(raw.inflation, 0), colorSampling: FIELD_SAMPLING[num(raw.color_option, 2)] ?? "override", materialNeutralCutout: bool(raw.material_neutral_cutout, false) };
+        case "decal": return { ...base, kind: "decal", hidden, materialId: material, image: str(raw.image, "empty"), global: num(raw.global, 1) !== 0, colorSampling: ["texture", "multiply", "material"][num(raw.color_option, 0)] ?? "texture" };
+        case "openScad": return { ...base, kind: "openScad", hidden, materialId: material, operation, blend: num(raw.blend, 0), scriptId: num(raw.script_id, 0), params: (raw.params && typeof raw.params === "object" ? raw.params : {}), enabled: bool(raw.enabled, true) };
+        case "socket": return { ...base, kind: "socket", hidden, tag: str(raw.tag) };
+    }
+}
+export function defaultNode(kind, id, name = "") {
+    const base = { id, kind, name, parentId: null, transform: identityTransform(), pickable: true };
+    const mirrors = () => [0, 1, 2, 3].map(() => ({
+        position: v3(0),
+        rotation: v3(0),
+        value: -1,
+        hide: 0,
+        hideMirrorPlane: false,
+        constraint: 0,
+    }));
+    switch (kind) {
+        case "primitive": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 0, color: v3(1), primitive: "box", round: 0, thickness: -1, inflation: 0, materialNeutralCutout: false, mirrors: mirrors() };
+        case "union": return { ...base, kind, hidden: false, operation: "union", blend: 0, resolution: 0.3, thickness: -1, inflation: 0, materialNeutralCutout: false };
+        case "group": return { ...base, kind, hidden: false };
+        case "light": return { ...base, kind, color: { x: 1, y: 1, z: 0.9 }, power: 80, collimation: 0, lightType: "sphere", size: v2(1, 1), textureFile: "" };
+        case "curve": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 20, primitive: "sphere", density: 100, roundness: 1, smoothing: 0.02, materialNeutralCutout: false, points: [{ position: v3(0), rotation: v3(0), scale: v3(10), materialId: null, round: 0, fixed: false }], mirrors: mirrors() };
+        case "text": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 0, text: "Text", fontFamily: "OpenSans", weight: 400, italic: false, round: 0, width: 20, wrap: "disabled", align: "left", spacing: 0, lineHeight: 1, materialNeutralCutout: false };
+        case "svg": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 0, paths: [{ closed: true, segments: [{ point: v2(-1, 0), handleIn: v2(0, -1), handleOut: v2(0, 1) }, { point: v2(1, 0), handleIn: v2(0, 1), handleOut: v2(0, -1) }] }], inflate: false, outline: false, outlineSize: 0.1, materialNeutralCutout: false };
+        case "mesh": return { ...base, kind, hidden: false, materialId: null, mesh: "", meshIndex: 0, smoothNormals: false, colorSampling: "override" };
+        case "field": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 0, field: "empty", inflation: 0, colorSampling: "override", materialNeutralCutout: false };
+        case "decal": return { ...base, kind, hidden: false, materialId: null, image: "empty", global: true, colorSampling: "texture" };
+        case "openScad": return { ...base, kind, hidden: false, materialId: null, operation: "union", blend: 0, scriptId: 0, params: {}, enabled: true };
+        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 };
+}
+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 })) }));
+}
+export function nodeToWire(node) {
+    const raw = { type: kindToWire(node.kind), pos: node.transform.position, rot: node.transform.rotation, pick_disabled: !node.pickable };
+    if (node.kind !== "light")
+        raw.size = node.transform.scale;
+    if ("hidden" in node)
+        raw.hide = node.hidden ? 1 : 0;
+    if ("materialId" in node)
+        raw.material_id = node.materialId ?? 0;
+    if ("operation" in node)
+        raw.op = OPERATIONS.indexOf(node.operation);
+    if ("blend" in node)
+        raw.blend = node.blend;
+    switch (node.kind) {
+        case "primitive":
+            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 });
+            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));
+            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 });
+            break;
+        case "svg":
+            Object.assign(raw, { paths: encodeSvgPaths(node.paths), inflate: node.inflate, outline: node.outline, outline_size: node.outlineSize, material_neutral_cutout: node.materialNeutralCutout, flip_mask: 0 });
+            break;
+        case "mesh":
+            Object.assign(raw, { mesh: node.mesh, mesh_index: node.meshIndex, smooth_normals: node.smoothNormals, color_option: FIELD_SAMPLING.indexOf(node.colorSampling), flip_mask: 0 });
+            break;
+        case "field":
+            Object.assign(raw, { field: node.field, inflation: node.inflation, color_option: FIELD_SAMPLING.indexOf(node.colorSampling), material_neutral_cutout: node.materialNeutralCutout, flip_mask: 0 });
+            break;
+        case "decal":
+            Object.assign(raw, { image: node.image, global: node.global ? 1 : 0, color_option: ["texture", "multiply", "material"].indexOf(node.colorSampling), flip_mask: 0 });
+            break;
+        case "openScad":
+            Object.assign(raw, { script_id: node.scriptId, params: node.params, enabled: node.enabled });
+            break;
+        case "socket":
+            raw.tag = node.tag;
+            break;
+        case "group": break;
+    }
+    return raw;
+}
+function encodeMirrorPlanes(mirrors) {
+    return Object.fromEntries(mirrors.map((plane, index) => [
+        `mirror_plane_${index}`,
+        {
+            position: plane.position,
+            rotation: plane.rotation,
+            value: plane.value,
+            hide: plane.hide,
+        },
+    ]));
+}
+export const defaultMaterialData = () => ({
+    color: v3(1), metalness: 0, roughness: 0, transmittance: 0, translucency: 0,
+    translucencyWeight: 0, secondaryColor: v3(1), subsurface: v3(0), indexOfRefraction: 1.58,
+    iridescence: 0, emission: 0, absorption: 0, sheen: 0, sheenRoughness: 0, specularTint: 0,
+    dispersion: 0, surfaceOpacity: 1, volumetricEnabled: false,
+});
+export function wireToMaterial(id, raw) {
+    const d = raw.data ?? {};
+    return { id, data: { color: { x: num(d["color.x"], 1), y: num(d["color.y"], 1), z: num(d["color.z"], 1) }, metalness: num(d.metalness, 0), roughness: num(d.roughness, 0), transmittance: num(d.transmittance, 0), translucency: num(d.translucency, 0), translucencyWeight: num(d.translucency_weight, 0), secondaryColor: { x: num(d["secondary_color.x"], 1), y: num(d["secondary_color.y"], 1), z: num(d["secondary_color.z"], 1) }, subsurface: { x: num(d["subsurface.x"], 0), y: num(d["subsurface.y"], 0), z: num(d["subsurface.z"], 0) }, indexOfRefraction: num(d.index_of_refraction, 1.58), iridescence: num(d.iridescence, 0), emission: num(d.emission, 0), absorption: num(d.absorption, 0), sheen: num(d.sheen, 0), sheenRoughness: num(d.sheen_roughness, 0), specularTint: num(d.specular_tint, 0), dispersion: num(d.dispersion, 0), surfaceOpacity: num(d.surface_opacity, 1), volumetricEnabled: bool(d.volumetric_enabled, false) }, shaderIds: raw.shaders ?? (raw.shader ? [raw.shader] : []) };
+}
+export function materialToWire(material) {
+    const d = material.data;
+    const wire = { data: { "color.x": d.color.x, "color.y": d.color.y, "color.z": d.color.z, metalness: d.metalness, roughness: d.roughness, transmittance: d.transmittance, translucency: d.translucency, translucency_weight: d.translucencyWeight, "secondary_color.x": d.secondaryColor.x, "secondary_color.y": d.secondaryColor.y, "secondary_color.z": d.secondaryColor.z, "subsurface.x": d.subsurface.x, "subsurface.y": d.subsurface.y, "subsurface.z": d.subsurface.z, index_of_refraction: d.indexOfRefraction, iridescence: d.iridescence, emission: d.emission, absorption: d.absorption, sheen: d.sheen, sheen_roughness: d.sheenRoughness, specular_tint: d.specularTint, dispersion: d.dispersion, surface_opacity: d.surfaceOpacity, volumetric_enabled: d.volumetricEnabled } };
+    return material.shaderIds.length ? { ...wire, shaders: [...material.shaderIds] } : wire;
+}
+export function parseSafePositiveId(value) {
+    const id = Number(value);
+    return Number.isSafeInteger(id) && id > 0 && String(id) === value ? id : undefined;
+}
+export function toPublicScene(raw) {
+    const parents = parentMap(raw);
+    void parents;
+    const nodes = Object.fromEntries(Object.keys(raw.nodes).map((id) => [id, wireToNode(raw, Number(id))]));
+    const tree = Object.fromEntries(Object.keys(raw.tree ?? {}).map((id) => [id, orderedChildren(raw, Number(id))]));
+    const materials = Object.fromEntries(Object.entries(raw.storage.materials ?? {}).flatMap(([key, value]) => {
+        const id = parseSafePositiveId(key);
+        return id === undefined ? [] : [[key, wireToMaterial(id, value)]];
+    }));
+    const scripts = Object.fromEntries(Object.entries(raw.storage.openscad?.scripts ?? {}).map(([id, value]) => [id, { id: Number(id), name: str(value.name, "OpenSCAD Script"), source: str(value.source) }]));
+    return { version: raw.version ?? 0, name: raw.name ?? "", nodes, tree, materials, openScadScripts: scripts, properties: (raw.properties ?? {}), camera: (raw.camera ?? {}) };
+}
+export function missingNode(id, operation) {
+    return new KakapoValidationError(`Node ${id} does not exist.`, { code: "NODE_NOT_FOUND", operation, path: "nodeId", received: id, expected: "an existing node ID", hint: "Call listNodes() or refreshScene() and use a current node ID." });
+}
+function decodePointer(path) {
+    if (path === "")
+        return [];
+    if (!path.startsWith("/"))
+        throw new KakapoValidationError(`Invalid JSON Pointer '${path}'.`, { code: "INVALID_JSON_POINTER", operation: "applyScenePatch", path: "patch.path", received: path, expected: "RFC 6901 pointer beginning with '/'" });
+    return path.slice(1).split("/").map((p) => p.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+function getAt(root, path) {
+    let current = root;
+    for (const part of decodePointer(path)) {
+        if (!current || typeof current !== "object")
+            throw new Error(`Path does not exist: ${path}`);
+        current = current[part];
+    }
+    return current;
+}
+function setAt(root, path, value, add) {
+    const parts = decodePointer(path);
+    const key = parts.pop();
+    if (key === undefined)
+        throw new Error("Replacing the document root is not supported");
+    let parent = root;
+    for (const part of parts) {
+        const next = parent[part];
+        if (!next || typeof next !== "object")
+            throw new Error(`Path does not exist: ${path}`);
+        parent = next;
+    }
+    if (!add && !Object.hasOwn(parent, key))
+        throw new Error(`Path does not exist: ${path}`);
+    if (Array.isArray(parent)) {
+        const index = key === "-" ? parent.length : Number(key);
+        if (add)
+            parent.splice(index, 0, value);
+        else
+            parent[index] = value;
+    }
+    else
+        parent[key] = value;
+}
+function removeAt(root, path) {
+    const parts = decodePointer(path);
+    const key = parts.pop();
+    if (key === undefined)
+        throw new Error("Removing the document root is not supported");
+    let parent = root;
+    for (const part of parts) {
+        const next = parent[part];
+        if (!next || typeof next !== "object")
+            throw new Error(`Path does not exist: ${path}`);
+        parent = next;
+    }
+    if (!Object.hasOwn(parent, key))
+        throw new Error(`Path does not exist: ${path}`);
+    if (Array.isArray(parent))
+        return parent.splice(Number(key), 1)[0];
+    const old = parent[key];
+    delete parent[key];
+    return old;
+}
+export function applyJsonPatch(document, operations) {
+    const result = deepClone(document);
+    try {
+        for (const operation of operations) {
+            switch (operation.op) {
+                case "add":
+                    setAt(result, operation.path, deepClone(operation.value), true);
+                    break;
+                case "replace":
+                    setAt(result, operation.path, deepClone(operation.value), false);
+                    break;
+                case "remove":
+                    removeAt(result, operation.path);
+                    break;
+                case "copy":
+                    setAt(result, operation.path, deepClone(getAt(result, operation.from)), true);
+                    break;
+                case "move":
+                    setAt(result, operation.path, removeAt(result, operation.from), true);
+                    break;
+                case "test":
+                    if (JSON.stringify(getAt(result, operation.path)) !== JSON.stringify(operation.value))
+                        throw new Error(`Test failed at ${operation.path}`);
+                    break;
+            }
+        }
+    }
+    catch (cause) {
+        throw new KakapoValidationError(`Cannot apply scene patch: ${cause instanceof Error ? cause.message : String(cause)}`, { code: "INVALID_SCENE_PATCH", operation: "applyScenePatch", cause, hint: "Use an existing RFC 6901 path and a valid RFC 6902 operation." });
+    }
+    return result;
+}
+export function nextId(record) {
+    return Math.max(0, ...Object.keys(record).map(Number).filter(Number.isSafeInteger)) + 1;
+}
+export function escapePointer(value) { return value.replaceAll("~", "~0").replaceAll("/", "~1"); }