@womp/kakapo-sdk 0.1.0 → 0.2.1

package/README.md

@@ -51,6 +51,11 @@ kakapo.disconnect();
 The transport uses the browser's native `WebSocket` when bundled for the web and loads `ws`
 dynamically in Node.js.
 
+Applications that already own a renderer connection can pass a `KakapoAPITransport` as
+`new KakapoAPI({ transport })`. The adapter defines connection lifecycle, RPC, and token responses.
+`captureScreenshot({ view: "current" })` requests the renderer's JPEG without changing the camera
+or requiring a cached scene. Current-view captures cannot include `targetId` or `targetIds`.
+
 All public inputs are checked at runtime as well as by TypeScript. Invalid calls throw structured
 `KakapoValidationError` objects with a stable `code`, offending `path`, expected rule, and a
 correction `hint` intended for automated agents.

package/dist/api.d.ts

@@ -13,6 +13,10 @@ export interface SceneEdit {
     getNodeParent(id: number): KakapoNode | null;
     getNodeChildren(id: number): KakapoNode[];
     applyScenePatch(operations: JsonPatchOperation[]): Scene;
+    getSceneExt(): Record<string, JsonValue>;
+    patchSceneExt(operations: JsonPatchOperation[]): Scene;
+    getSceneProperties(): Record<string, JsonValue>;
+    patchSceneProperties(operations: JsonPatchOperation[]): Scene;
     createNode(input: CreateNodeInput): KakapoNode;
     cloneNode(id: number, options?: {
         parentId?: number;
@@ -74,6 +78,14 @@ export declare class KakapoAPI {
     getScene(): Scene;
     editScene<T>(callback: (scene: SceneEdit) => T | Promise<T>): Promise<T>;
     private applyScenePatch;
+    /** The scene's consumer-owned extension bag. Kakapo does not interpret it. */
+    getSceneExt(): Record<string, JsonValue>;
+    /** Apply JSON Patch operations rooted at the scene's `ext` bag. */
+    patchSceneExt(operations: JsonPatchOperation[]): Scene;
+    /** The scene's renderer/environment properties (HDR, background, and similar). */
+    getSceneProperties(): Record<string, JsonValue>;
+    /** Apply JSON Patch operations rooted at the scene's `properties` bag. */
+    patchSceneProperties(operations: JsonPatchOperation[]): Scene;
     listNodes(options?: ListNodeOptions): KakapoNode[];
     findNodes(options: FindNodeOptions): KakapoNode[];
     getNode(id: number): KakapoNode;

package/dist/api.js

@@ -25,7 +25,7 @@ export class KakapoAPI {
     draftDirty = false;
     rendererSyncRequired = false;
     constructor(options = {}) {
-        this.transport = new KakapoTransport({
+        this.transport = options.transport ?? new KakapoTransport({
             url: options.url ?? "ws://127.0.0.1:5502",
             requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
             connectTimeoutMs: options.connectTimeoutMs ?? 30_000,
@@ -126,6 +126,24 @@ export class KakapoAPI {
         this.draftDirty = true;
         return this.getScene();
     }
+    /** The scene's consumer-owned extension bag. Kakapo does not interpret it. */
+    getSceneExt() {
+        const scene = this.getScene();
+        return scene.ext ?? {};
+    }
+    /** Apply JSON Patch operations rooted at the scene's `ext` bag. */
+    patchSceneExt(operations) {
+        return this.applyScenePatch(operations.map((op) => ({ ...op, path: `/ext${op.path}` })));
+    }
+    /** The scene's renderer/environment properties (HDR, background, and similar). */
+    getSceneProperties() {
+        const scene = this.getScene();
+        return scene.properties ?? {};
+    }
+    /** Apply JSON Patch operations rooted at the scene's `properties` bag. */
+    patchSceneProperties(operations) {
+        return this.applyScenePatch(operations.map((op) => ({ ...op, path: `/properties${op.path}` })));
+    }
     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);
@@ -193,6 +211,17 @@ export class KakapoAPI {
     async captureScreenshot(options) {
         this.assertEngineReadAllowed("captureScreenshot");
         const { targetId, timeoutMs } = options;
+        if (options.view === "current") {
+            if (targetId !== undefined || options.targetIds !== undefined) {
+                throw new KakapoValidationError("A current-view screenshot cannot specify framing targets.", {
+                    code: "AMBIGUOUS_SCREENSHOT_TARGET",
+                    operation: "captureScreenshot",
+                    expected: "current view without target selectors",
+                });
+            }
+            const frame = await this.captureRendererFrame(timeoutMs);
+            return { data: frame.payload, mediaType: "image/jpeg", width: frame.width, height: frame.height, view: "current", targetId: 0 };
+        }
         if (targetId !== undefined && options.targetIds !== undefined) {
             throw new KakapoValidationError("captureScreenshot accepts targetId or targetIds, not both.", {
                 code: "AMBIGUOUS_SCREENSHOT_TARGET",
@@ -264,8 +293,7 @@ export class KakapoAPI {
     async captureRendererFrame(timeoutMs) {
         const token = this.newToken();
         const waiting = this.waitForToken(token, timeoutMs);
-        await this.call("get_color_buffer", [[token]]);
-        const message = await waiting;
+        const [, message] = await Promise.all([this.call("get_color_buffer", [[token]]), 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);
@@ -569,6 +597,10 @@ export class KakapoAPI {
             getNodeParent: (id) => this.getNodeParent(id),
             getNodeChildren: (id) => this.getNodeChildren(id),
             applyScenePatch: (operations) => this.applyScenePatch(operations),
+            getSceneExt: () => this.getSceneExt(),
+            patchSceneExt: (operations) => this.patchSceneExt(operations),
+            getSceneProperties: () => this.getSceneProperties(),
+            patchSceneProperties: (operations) => this.patchSceneProperties(operations),
             createNode: (input) => this.createNode(input),
             cloneNode: (id, options) => this.cloneNode(id, options),
             updateNode: (id, changes) => this.updateNode(id, changes),

package/dist/scene.js

@@ -294,7 +294,7 @@ export function toPublicScene(raw) {
         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 ?? {}) };
+    return { version: raw.version ?? 0, name: raw.name ?? "", nodes, tree, materials, openScadScripts: scripts, properties: (raw.properties ?? {}), camera: (raw.camera ?? {}), ext: (raw.ext ?? {}) };
 }
 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." });

package/dist/types.d.ts

@@ -268,6 +268,12 @@ export interface Scene {
     openScadScripts: Record<string, OpenScadScript>;
     properties: Record<string, JsonValue>;
     camera: Record<string, JsonValue>;
+    /**
+     * Consumer-owned extension bag carried in the scene file. Kakapo does not
+     * interpret its contents; Womp stores node and material metadata here
+     * (e.g. `ext[nodeId].locked`, `ext.materialsExt[materialId].tier`).
+     */
+    ext: Record<string, JsonValue>;
 }
 export interface BoundingBox {
     min: Vec3;
@@ -316,7 +322,8 @@ export interface CaptureScreenshotOptions {
     /** Omit both selectors to frame all visible top-level scene nodes. */
     targetId?: number;
     targetIds?: number[];
-    view?: ScreenshotView;
+    /** "current" captures the renderer's existing camera without framing or reading scene state. */
+    view?: ScreenshotView | "current";
     timeoutMs?: number;
 }
 export interface ScreenshotImage {
@@ -324,7 +331,7 @@ export interface ScreenshotImage {
     mediaType: "image/jpeg";
     width: number;
     height: number;
-    view: ScreenshotView;
+    view: ScreenshotView | "current";
     targetId: number;
 }
 export type JsonPatchOperation = {
@@ -351,7 +358,17 @@ export interface ListNodeOptions {
 export interface DeleteNodeOptions {
     recursive?: boolean;
 }
+/** An application can supply its existing connection; its adapter owns connection lifecycle. */
+export interface KakapoAPITransport {
+    readonly connected: boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    rpc<T>(method: string, params?: JsonValue[]): Promise<T>;
+    newToken(): string;
+    waitForToken(token: string, timeoutMs?: number): Promise<TokenMessage>;
+}
 export interface KakapoAPIOptions {
+    transport?: KakapoAPITransport;
     url?: string;
     requestTimeoutMs?: number;
     connectTimeoutMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/kakapo-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Typed Node.js and browser SDK for controlling Kakapo over WebSocket",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22.0.0"
   },
   "repository": {
     "type": "git",