@womp/kakapo-sdk 0.2.0 → 0.2.2

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.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,
@@ -211,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",
@@ -282,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);

package/dist/types.d.ts

@@ -322,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 {
@@ -330,7 +331,7 @@ export interface ScreenshotImage {
     mediaType: "image/jpeg";
     width: number;
     height: number;
-    view: ScreenshotView;
+    view: ScreenshotView | "current";
     targetId: number;
 }
 export type JsonPatchOperation = {
@@ -357,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/dist/validation.js

@@ -143,7 +143,7 @@ export function assertScene(scene, operation) {
         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))
+        if (Object.keys(children).length > 0 && !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)])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/kakapo-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Typed Node.js and browser SDK for controlling Kakapo over WebSocket",
   "type": "module",
   "main": "./dist/index.js",