@womp/kakapo-sdk 0.1.0

package/dist/validation.d.ts

@@ -0,0 +1,8 @@
+import { type WireScene } from "./scene.js";
+import type { FontFamily, KakapoNode, MaterialData, Transform } from "./types.js";
+export declare function assertId(value: number, operation: string, path?: string, allowZero?: boolean): void;
+export declare function assertTransform(value: Transform, operation: string): void;
+export declare function assertNode(node: KakapoNode, scene: WireScene, operation: string): void;
+export declare function assertScene(scene: WireScene, operation: string): void;
+export declare function assertMaterial(data: MaterialData, operation: string): void;
+export declare function assertFont(fonts: FontFamily[], family: string, weight: number, italic: boolean, operation: string): void;

package/dist/validation.js

@@ -0,0 +1,195 @@
+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"]);
+function fail(message, operation, path, received, expected, hint, code = "VALIDATION_ERROR") {
+    throw new KakapoValidationError(message, { code, operation, path, received, expected, hint });
+}
+export function assertId(value, operation, path = "nodeId", allowZero = false) {
+    if (!Number.isSafeInteger(value) || value < (allowZero ? 0 : 1)) {
+        fail(`${path} must be a ${allowZero ? "non-negative" : "positive"} safe integer.`, operation, path, value, allowZero ? "safe integer >= 0" : "safe integer >= 1", "Use an ID returned by a KakapoAPI create or list method.", "INVALID_ID");
+    }
+}
+function assertFinite(value, operation, path, min, max) {
+    if (!Number.isFinite(value) || (min !== undefined && value < min) || (max !== undefined && value > max)) {
+        const range = min !== undefined || max !== undefined ? ` in [${min ?? "-∞"}, ${max ?? "∞"}]` : "";
+        fail(`${path} must be a finite number${range}.`, operation, path, value, `finite number${range}`, "Use a numeric value inside Kakapo's supported range.", "INVALID_NUMBER");
+    }
+}
+function assertVec2(value, operation, path) {
+    assertFinite(value.x, operation, `${path}.x`);
+    assertFinite(value.y, operation, `${path}.y`);
+}
+function assertVec3(value, operation, path) {
+    assertFinite(value.x, operation, `${path}.x`);
+    assertFinite(value.y, operation, `${path}.y`);
+    assertFinite(value.z, operation, `${path}.z`);
+}
+function assertColor(value, operation, path) {
+    assertFinite(value.x, operation, `${path}.x`, 0, 1);
+    assertFinite(value.y, operation, `${path}.y`, 0, 1);
+    assertFinite(value.z, operation, `${path}.z`, 0, 1);
+}
+export function assertTransform(value, operation) {
+    assertVec3(value.position, operation, "transform.position");
+    assertVec3(value.rotation, operation, "transform.rotation");
+    assertVec3(value.scale, operation, "transform.scale");
+    if (value.scale.x <= 0 || value.scale.y <= 0 || value.scale.z <= 0) {
+        fail("Node scale components must be greater than zero.", operation, "transform.scale", value.scale, "positive finite Vec3", "Use scale components greater than zero.", "INVALID_SCALE");
+    }
+}
+function assertAssetName(value, operation, path) {
+    if (!value.trim() || value.includes("\0") || value.length > 1024) {
+        fail(`${path} must be a non-empty asset reference without null bytes.`, operation, path, value, "1-1024 character asset name", "Pass the asset name/path already available to the connected Kakapo instance.", "INVALID_ASSET_REFERENCE");
+    }
+}
+function assertSvgPaths(paths, operation) {
+    if (!Array.isArray(paths) || paths.length === 0)
+        fail("SVG paths cannot be empty.", operation, "paths", paths, "at least one path", "Provide one or more paths with at least two segments.", "INVALID_SVG_PATHS");
+    paths.forEach((path, pathIndex) => {
+        if (path.segments.length < 2)
+            fail("Each SVG path requires at least two segments.", operation, `paths[${pathIndex}].segments`, path.segments, "at least two SVG segments", undefined, "INVALID_SVG_PATHS");
+        path.segments.forEach((segment, segmentIndex) => {
+            assertVec2(segment.point, operation, `paths[${pathIndex}].segments[${segmentIndex}].point`);
+            assertVec2(segment.handleIn, operation, `paths[${pathIndex}].segments[${segmentIndex}].handleIn`);
+            assertVec2(segment.handleOut, operation, `paths[${pathIndex}].segments[${segmentIndex}].handleOut`);
+        });
+    });
+}
+export function assertNode(node, scene, operation) {
+    assertId(node.id, operation, "node.id", true);
+    assertTransform(node.transform, operation);
+    if (node.name.includes("\0"))
+        fail("Node names cannot contain null bytes.", operation, "name", node.name, "string without null bytes");
+    if ("materialId" in node && node.materialId !== null) {
+        assertId(node.materialId, operation, "materialId");
+        if (!scene.storage.materials?.[String(node.materialId)])
+            fail(`Material ${node.materialId} does not exist.`, operation, "materialId", node.materialId, "existing material ID", "Call createMaterial() or listMaterials() before assigning it.", "MATERIAL_NOT_FOUND");
+    }
+    if ("blend" in node)
+        assertFinite(node.blend, operation, "blend", 0, 500);
+    switch (node.kind) {
+        case "primitive":
+            assertColor(node.color, operation, "color");
+            assertFinite(node.round, operation, "round", 0, 1);
+            assertFinite(node.thickness, operation, "thickness", -1, 10);
+            assertFinite(node.inflation, operation, "inflation", -10, 10);
+            break;
+        case "union":
+            assertFinite(node.resolution, operation, "resolution", 0.01, 1);
+            assertFinite(node.thickness, operation, "thickness", -1, 10);
+            assertFinite(node.inflation, operation, "inflation", -10, 10);
+            break;
+        case "light":
+            assertColor(node.color, operation, "color");
+            assertFinite(node.power, operation, "power", 0, 100);
+            assertFinite(node.collimation, operation, "collimation", 0, 1);
+            assertVec2(node.size, operation, "size");
+            if (node.size.x < 0.01 || node.size.y < 0.01)
+                fail("Light size components must be at least 0.01.", operation, "size", node.size, "Vec2 components >= 0.01");
+            break;
+        case "curve":
+            assertFinite(node.density, operation, "density", 1);
+            assertFinite(node.roundness, operation, "roundness", 0);
+            assertFinite(node.smoothing, operation, "smoothing", 0, 1);
+            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`); });
+            break;
+        case "text":
+            if (!node.text.length)
+                fail("Text content cannot be empty.", operation, "text", node.text, "non-empty string");
+            assertFinite(node.weight, operation, "weight", 1, 1000);
+            assertFinite(node.width, operation, "width", 0, 50);
+            assertFinite(node.spacing, operation, "spacing", -2, 2);
+            assertFinite(node.lineHeight, operation, "lineHeight", 0, 2);
+            break;
+        case "svg":
+            assertSvgPaths(node.paths, operation);
+            assertFinite(node.outlineSize, operation, "outlineSize", 0.0000001, 5);
+            break;
+        case "mesh":
+            assertAssetName(node.mesh, operation, "mesh");
+            assertId(node.meshIndex, operation, "meshIndex", true);
+            break;
+        case "field":
+            assertAssetName(node.field, operation, "field");
+            assertFinite(node.inflation, operation, "inflation", 0, 10);
+            break;
+        case "decal":
+            assertAssetName(node.image, operation, "image");
+            break;
+        case "openScad":
+            assertId(node.scriptId, operation, "scriptId");
+            if (!scene.storage.openscad?.scripts?.[String(node.scriptId)])
+                fail(`OpenSCAD script ${node.scriptId} does not exist.`, operation, "scriptId", node.scriptId, "existing OpenSCAD script ID", "Create the script before assigning it to a node.", "SCRIPT_NOT_FOUND");
+            break;
+        case "socket":
+            if (node.tag.includes("\0"))
+                fail("Socket tags cannot contain null bytes.", operation, "tag", node.tag, "string without null bytes");
+            break;
+        case "group": break;
+    }
+}
+export function assertScene(scene, operation) {
+    if (!scene.nodes || !scene.nodes["0"] || kindFromWire(scene.nodes["0"].type) !== "group") {
+        fail("Scene root node 0 must exist and be a Group.", operation, "nodes.0", scene.nodes?.["0"], "root Group node", "Refresh the scene or restore node 0.", "INVALID_SCENE_ROOT");
+    }
+    const parents = parentMap(scene);
+    const occurrences = new Map();
+    for (const [parentIdText, children] of Object.entries(scene.tree ?? {})) {
+        const parentId = Number(parentIdText);
+        const parentRaw = scene.nodes[parentIdText];
+        if (!parentRaw)
+            fail(`Tree parent ${parentId} does not exist.`, operation, `tree.${parentId}`, parentId, "existing parent node", undefined, "MISSING_TREE_NODE");
+        const parentKind = kindFromWire(parentRaw.type);
+        if (!CONTAINERS.has(parentKind))
+            fail(`Node ${parentId} (${parentKind}) cannot contain children.`, operation, `tree.${parentId}`, parentKind, "Union or Group parent", "Reparent the children under a Union or Group.", "LEAF_NODE_HAS_CHILDREN");
+        for (const childId of Object.values(children)) {
+            if (!scene.nodes[String(childId)])
+                fail(`Tree child ${childId} does not exist.`, operation, `tree.${parentId}`, childId, "existing child node", undefined, "MISSING_TREE_NODE");
+            occurrences.set(childId, (occurrences.get(childId) ?? 0) + 1);
+        }
+    }
+    for (const idText of Object.keys(scene.nodes)) {
+        const id = Number(idText);
+        if (id === 0)
+            continue;
+        const count = occurrences.get(id) ?? 0;
+        if (count !== 1)
+            fail(`Node ${id} must appear exactly once in the scene tree; found ${count}.`, operation, `tree`, { nodeId: id, occurrences: count }, "exactly one parent", "Use setNodeParent() to repair the tree.", "INVALID_TREE_MEMBERSHIP");
+        const visited = new Set([id]);
+        let cursor = id;
+        let hasUnion = false;
+        while (parents.has(cursor)) {
+            cursor = parents.get(cursor);
+            if (visited.has(cursor))
+                fail(`Scene tree contains a cycle through node ${cursor}.`, operation, "tree", cursor, "acyclic hierarchy", undefined, "TREE_CYCLE");
+            visited.add(cursor);
+            if (scene.nodes[String(cursor)]?.type === 1)
+                hasUnion = true;
+        }
+        const kind = kindFromWire(scene.nodes[idText].type);
+        if (GEOMETRY.has(kind) && !hasUnion)
+            fail(`Node ${id} (${kind}) must be a child or descendant of a Union.`, operation, `nodes.${id}`, { id, kind }, "Union ancestor", "Create or select a Union and parent this geometry beneath it.", "UNION_ANCESTOR_REQUIRED");
+    }
+    for (const idText of Object.keys(scene.nodes))
+        assertNode(wireToNode(scene, Number(idText)), scene, operation);
+}
+export function assertMaterial(data, operation) {
+    assertColor(data.color, operation, "data.color");
+    assertColor(data.secondaryColor, operation, "data.secondaryColor");
+    assertColor(data.subsurface, operation, "data.subsurface");
+    for (const key of ["metalness", "roughness", "transmittance", "translucencyWeight", "iridescence", "emission", "absorption", "sheen", "sheenRoughness", "specularTint", "surfaceOpacity"])
+        assertFinite(data[key], operation, `data.${key}`, 0, 1);
+    assertFinite(data.translucency, operation, "data.translucency", 0, 100);
+    assertFinite(data.indexOfRefraction, operation, "data.indexOfRefraction", 1, 3);
+    assertFinite(data.dispersion, operation, "data.dispersion", 0, 11);
+}
+export function assertFont(fonts, family, weight, italic, operation) {
+    const group = fonts.find((font) => font.name === family);
+    if (!group)
+        fail(`Font family '${family}' is unavailable.`, operation, "fontFamily", family, "font returned by listFonts()", `Available families: ${fonts.map((f) => f.name).join(", ")}`, "FONT_NOT_FOUND");
+    if (!group.fonts.some((font) => font.weight === weight && font.italic === italic))
+        fail(`Font '${family}' has no ${weight}${italic ? " italic" : " regular"} face.`, operation, "font", { family, weight, italic }, "available font face", `Available faces: ${group.fonts.map((f) => `${f.weight}${f.italic ? " italic" : ""}`).join(", ")}`, "FONT_FACE_NOT_FOUND");
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@womp/kakapo-sdk",
+  "version": "0.1.0",
+  "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": ">=20"
+  },
+  "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"
+}