@womp/kakapo-sdk 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @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.
+
+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.

package/dist/api.d.ts

@@ -0,0 +1,151 @@
+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";
+export interface SceneEdit {
+    getScene(): Scene;
+    listNodes(options?: ListNodeOptions): KakapoNode[];
+    findNodes(options: FindNodeOptions): KakapoNode[];
+    getNode(id: number): KakapoNode;
+    node(id: number): NodeHandle;
+    node<K extends NodeKind>(id: number, kind: K): NodeHandle<Extract<KakapoNode, {
+        kind: K;
+    }>>;
+    getNodeName(id: number): string;
+    getNodeParent(id: number): KakapoNode | null;
+    getNodeChildren(id: number): KakapoNode[];
+    applyScenePatch(operations: JsonPatchOperation[]): Scene;
+    createNode(input: CreateNodeInput): KakapoNode;
+    cloneNode(id: number, options?: {
+        parentId?: number;
+        name?: string;
+        index?: number;
+    }): KakapoNode;
+    updateNode(id: number, changes: NodeUpdate): KakapoNode;
+    deleteNode(id: number, options?: DeleteNodeOptions): number[];
+    setNodeParent(id: number, parentId: number, index?: number): KakapoNode;
+    setNodeName(id: number, name: string): KakapoNode;
+    setNodeTransform(id: number, transform: Partial<Transform>): KakapoNode;
+    setNodePosition(id: number, position: Vec3): KakapoNode;
+    setNodeRotation(id: number, rotation: Vec3): KakapoNode;
+    setNodeScale(id: number, scale: Vec3): KakapoNode;
+    setNodeVisible(id: number, visible: boolean): KakapoNode;
+    setNodePickable(id: number, pickable: boolean): KakapoNode;
+    setNodeMaterial(id: number, materialId: number | null): KakapoNode;
+    setNodeOperation(id: number, operation: PrimitiveOperation): KakapoNode;
+    setTextContent(id: number, text: string): KakapoNode;
+    setTextFont(id: number, fontFamily: string, weight?: number, italic?: boolean): KakapoNode;
+    setSvgPaths(id: number, paths: SvgPath[]): KakapoNode;
+    setMeshSource(id: number, mesh: string, meshIndex?: number): KakapoNode;
+    setFieldSource(id: number, field: string): KakapoNode;
+    setDecalSource(id: number, image: string): KakapoNode;
+    setSocketTag(id: number, tag: string): KakapoNode;
+    setOpenScadScript(id: number, scriptId: number, params?: Record<string, JsonValue>): KakapoNode;
+    listMaterials(): Material[];
+    getMaterial(id: number): Material;
+    createMaterial(data?: Partial<MaterialData>, shaderIds?: number[]): Material;
+    updateMaterial(id: number, data: Partial<MaterialData>, shaderIds?: number[]): Material;
+    deleteMaterial(id: number): void;
+    listOpenScadScripts(): OpenScadScript[];
+    getOpenScadScript(id: number): OpenScadScript;
+    createOpenScadScript(name: string, source: string): OpenScadScript;
+    updateOpenScadScript(id: number, changes: {
+        name?: string;
+        source?: string;
+    }): OpenScadScript;
+    deleteOpenScadScript(id: number): void;
+}
+export declare class KakapoAPI {
+    private readonly transport;
+    private rawScene?;
+    private cacheValid;
+    private fonts?;
+    private transactionTail;
+    private draftScene?;
+    private draftDirty;
+    private rendererSyncRequired;
+    constructor(options?: KakapoAPIOptions);
+    get isConnected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    ping(): Promise<"pong">;
+    rpc<T = unknown>(method: string, params?: JsonValue[]): Promise<T>;
+    newToken(): string;
+    waitForToken(token: string, timeoutMs?: number): Promise<TokenMessage>;
+    refreshScene(): Promise<Scene>;
+    getScene(): Scene;
+    editScene<T>(callback: (scene: SceneEdit) => T | Promise<T>): Promise<T>;
+    private applyScenePatch;
+    listNodes(options?: ListNodeOptions): KakapoNode[];
+    findNodes(options: FindNodeOptions): KakapoNode[];
+    getNode(id: number): KakapoNode;
+    node(id: number): NodeHandle;
+    node<K extends NodeKind>(id: number, kind: K): NodeHandle<Extract<KakapoNode, {
+        kind: K;
+    }>>;
+    getNodeName(id: number): string;
+    getNodeParent(id: number): KakapoNode | null;
+    getNodeChildren(id: number): KakapoNode[];
+    getNodeBoundingBox(id: number): Promise<BoundingBox>;
+    getNodesBoundingBox(ids: number[]): Promise<BoundingBox>;
+    captureScreenshot(options: CaptureScreenshotOptions): Promise<ScreenshotImage>;
+    private ensureRendererReady;
+    private captureRendererFrame;
+    private screenshotDirection;
+    private createNode;
+    private cloneNode;
+    private updateNode;
+    private deleteNode;
+    private setNodeParent;
+    private setNodeName;
+    private setNodeTransform;
+    private setNodePosition;
+    private setNodeRotation;
+    private setNodeScale;
+    private setNodeVisible;
+    private setNodePickable;
+    private setNodeMaterial;
+    private setNodeOperation;
+    private setTextContent;
+    private setTextFont;
+    private setSvgPaths;
+    private setMeshSource;
+    private setFieldSource;
+    private setDecalSource;
+    private setSocketTag;
+    private setOpenScadScript;
+    listMaterials(): Material[];
+    getMaterial(id: number): Material;
+    private createMaterial;
+    private updateMaterial;
+    private deleteMaterial;
+    listOpenScadScripts(): OpenScadScript[];
+    getOpenScadScript(id: number): OpenScadScript;
+    private createOpenScadScript;
+    private updateOpenScadScript;
+    private deleteOpenScadScript;
+    validateOpenScad(source: string, params?: Record<string, JsonValue>): Promise<OpenScadValidationResult>;
+    listFonts(): Promise<FontFamily[]>;
+    reloadFonts(): Promise<void>;
+    reloadMeshes(): Promise<void>;
+    reloadFields(): Promise<void>;
+    reloadDecals(): Promise<void>;
+    reloadTextures(): Promise<unknown>;
+    getPendingResources(): Promise<PendingResources>;
+    private call;
+    private sendPatch;
+    private saveNode;
+    private requireScene;
+    private requireDraft;
+    private assertEngineReadAllowed;
+    private createSceneEdit;
+    private treeArrays;
+    private extWithName;
+    private extWithNode;
+    private mergeNode;
+    private mergeMaterialData;
+    private expectKind;
+    private unsupported;
+    private rootError;
+    private materialMissing;
+    private scriptMissing;
+    private assertOpenScadValid;
+}