@womp/kakapo-sdk 0.1.0

package/dist/transport.d.ts

@@ -0,0 +1,28 @@
+import type { BinaryFrame, JsonValue, TokenMessage } from "./types.js";
+export interface TransportOptions {
+    url: string;
+    requestTimeoutMs: number;
+    connectTimeoutMs: number;
+}
+export declare class KakapoTransport {
+    private readonly options;
+    private socket?;
+    private browserSocket;
+    private nextRequestId;
+    private nextTokenId;
+    private readonly requests;
+    private readonly tokenWaiters;
+    private readonly tokenInbox;
+    constructor(options: TransportOptions);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    rpc<T>(method: string, params?: JsonValue[], timeoutMs?: number): Promise<T>;
+    newToken(): string;
+    waitForToken(token: string, timeoutMs?: number): Promise<TokenMessage>;
+    private handleMessage;
+    private deliverToken;
+    private handleClose;
+    private rejectAll;
+}
+export declare function parseBinaryFrame(bytes: Uint8Array): BinaryFrame;

package/dist/transport.js

@@ -0,0 +1,317 @@
+import { KakapoConnectionError, KakapoRpcError, KakapoTimeoutError, KakapoValidationError, } from "./errors.js";
+export class KakapoTransport {
+    options;
+    socket;
+    browserSocket = false;
+    nextRequestId = 1;
+    nextTokenId = 1;
+    requests = new Map();
+    tokenWaiters = new Map();
+    tokenInbox = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get connected() {
+        return this.socket?.readyState === 1;
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.socket && this.socket.readyState === 0) {
+            throw new KakapoConnectionError("A Kakapo WebSocket connection is already in progress.", {
+                code: "CONNECTION_IN_PROGRESS",
+                operation: "connect",
+            });
+        }
+        const BrowserWebSocket = globalThis.WebSocket;
+        let socket;
+        if (BrowserWebSocket) {
+            socket = new BrowserWebSocket(this.options.url);
+            this.browserSocket = true;
+        }
+        else {
+            const moduleName = "ws";
+            const module = await import(moduleName);
+            socket = new module.default(this.options.url, { perMessageDeflate: false });
+            this.browserSocket = false;
+        }
+        this.socket = socket;
+        socket.binaryType = this.browserSocket ? "arraybuffer" : "nodebuffer";
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                socket.terminate?.();
+                if (!socket.terminate)
+                    socket.close();
+                reject(new KakapoTimeoutError(`Timed out connecting to ${this.options.url}.`, {
+                    code: "CONNECT_TIMEOUT",
+                    operation: "connect",
+                    expected: `WebSocket open within ${this.options.connectTimeoutMs}ms`,
+                    hint: "Start Kakapo and confirm that its WebSocket server is listening on the configured URL.",
+                }));
+            }, this.options.connectTimeoutMs);
+            const onOpen = () => {
+                clearTimeout(timer);
+                socket.off?.("error", onNodeError);
+                socket.removeEventListener?.("error", onBrowserError);
+                resolve();
+            };
+            const rejectConnection = (cause) => {
+                clearTimeout(timer);
+                socket.off?.("open", onOpen);
+                socket.removeEventListener?.("open", onBrowserOpen);
+                reject(new KakapoConnectionError(`Could not connect to ${this.options.url}: ${cause.message}`, {
+                    code: "CONNECTION_FAILED",
+                    operation: "connect",
+                    cause,
+                    hint: "Start Kakapo or correct the WebSocket URL.",
+                }));
+            };
+            const onNodeError = (cause) => rejectConnection(cause);
+            const onBrowserOpen = () => onOpen();
+            const onBrowserError = (event) => rejectConnection(new Error(event.message ?? "WebSocket connection failed"));
+            if (this.browserSocket) {
+                socket.addEventListener?.("open", onBrowserOpen, { once: true });
+                socket.addEventListener?.("error", onBrowserError, { once: true });
+            }
+            else {
+                socket.once?.("open", onOpen);
+                socket.once?.("error", onNodeError);
+            }
+        });
+        if (this.browserSocket) {
+            socket.addEventListener?.("message", (event) => {
+                const data = event.data;
+                this.handleMessage(data, typeof data !== "string");
+            });
+            socket.addEventListener?.("close", () => this.handleClose());
+            socket.addEventListener?.("error", () => undefined);
+        }
+        else {
+            socket.on?.("message", ((data, isBinary) => this.handleMessage(data, isBinary)));
+            socket.on?.("close", (() => this.handleClose()));
+            socket.on?.("error", (() => undefined));
+        }
+    }
+    disconnect() {
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            socket.removeAllListeners?.();
+            if (socket.readyState === 1 || socket.readyState === 0) {
+                socket.close();
+            }
+        }
+        this.rejectAll("The Kakapo WebSocket was disconnected by the client.");
+    }
+    rpc(method, params = [], timeoutMs = this.options.requestTimeoutMs) {
+        if (!this.connected || !this.socket) {
+            return Promise.reject(new KakapoConnectionError(`Cannot call '${method}' while disconnected.`, {
+                code: "NOT_CONNECTED",
+                operation: method,
+                hint: "Call connect() before issuing Kakapo API operations.",
+            }));
+        }
+        if (!method.trim()) {
+            return Promise.reject(new KakapoValidationError("RPC method must be a non-empty string.", {
+                code: "INVALID_RPC_METHOD",
+                operation: "rpc",
+                path: "method",
+                received: method,
+                expected: "non-empty method name",
+            }));
+        }
+        const id = this.nextRequestId++;
+        const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.requests.delete(id);
+                reject(new KakapoTimeoutError(`Kakapo RPC '${method}' timed out after ${timeoutMs}ms.`, {
+                    code: "RPC_TIMEOUT",
+                    operation: method,
+                    expected: `reply to request ${id} within ${timeoutMs}ms`,
+                    hint: "The engine may be busy; retry after ping() confirms it is responsive.",
+                    details: { requestId: id },
+                }));
+            }, timeoutMs);
+            this.requests.set(id, { method, resolve: resolve, reject, timer });
+            if (this.browserSocket) {
+                try {
+                    this.socket.send(payload);
+                }
+                catch (error) {
+                    clearTimeout(timer);
+                    this.requests.delete(id);
+                    reject(new KakapoConnectionError(`Failed to send Kakapo RPC '${method}'.`, {
+                        code: "SEND_FAILED",
+                        operation: method,
+                        cause: error,
+                    }));
+                }
+                return;
+            }
+            this.socket.send(payload, (error) => {
+                if (!error)
+                    return;
+                const pending = this.requests.get(id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.requests.delete(id);
+                reject(new KakapoConnectionError(`Failed to send Kakapo RPC '${method}': ${error.message}`, {
+                    code: "SEND_FAILED",
+                    operation: method,
+                    cause: error,
+                }));
+            });
+        });
+    }
+    newToken() {
+        // Kakapo's fixed wire field is char[16], including the null terminator.
+        return `k${(this.nextTokenId++).toString(36)}`.slice(0, 15);
+    }
+    waitForToken(token, timeoutMs = this.options.requestTimeoutMs) {
+        if (!token || new TextEncoder().encode(token).byteLength > 15) {
+            return Promise.reject(new KakapoValidationError("Kakapo tokens must contain 1-15 UTF-8 bytes.", {
+                code: "INVALID_TOKEN",
+                operation: "waitForToken",
+                path: "token",
+                received: token,
+                expected: "1-15 UTF-8 bytes",
+            }));
+        }
+        const queued = this.tokenInbox.get(token);
+        if (queued) {
+            this.tokenInbox.delete(token);
+            return Promise.resolve(queued);
+        }
+        if (this.tokenWaiters.has(token)) {
+            return Promise.reject(new KakapoValidationError(`A waiter already exists for token '${token}'.`, {
+                code: "DUPLICATE_TOKEN_WAITER",
+                operation: "waitForToken",
+                path: "token",
+                received: token,
+                hint: "Create a distinct token with newToken() for each asynchronous operation.",
+            }));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.tokenWaiters.delete(token);
+                reject(new KakapoTimeoutError(`Timed out waiting for Kakapo token '${token}'.`, {
+                    code: "TOKEN_TIMEOUT",
+                    operation: "waitForToken",
+                    details: { token },
+                }));
+            }, timeoutMs);
+            this.tokenWaiters.set(token, { resolve, reject, timer });
+        });
+    }
+    handleMessage(data, isBinary) {
+        if (isBinary) {
+            const bytes = data instanceof Uint8Array
+                ? data
+                : data instanceof ArrayBuffer
+                    ? new Uint8Array(data)
+                    : undefined;
+            if (!bytes)
+                return;
+            if (bytes.length < 48)
+                return;
+            const frame = parseBinaryFrame(bytes);
+            this.deliverToken(frame.token, frame);
+            return;
+        }
+        let message;
+        try {
+            const text = typeof data === "string"
+                ? data
+                : data instanceof Uint8Array
+                    ? new TextDecoder().decode(data)
+                    : data instanceof ArrayBuffer
+                        ? new TextDecoder().decode(new Uint8Array(data))
+                        : "";
+            message = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        const isReply = Object.hasOwn(message, "result") || Object.hasOwn(message, "error") ||
+            (typeof message.method === "string" && !Object.hasOwn(message, "params"));
+        if (typeof message.id === "number" && isReply) {
+            const pending = this.requests.get(message.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.requests.delete(message.id);
+            if (message.error) {
+                const error = typeof message.error === "string" ? { message: message.error } : message.error;
+                pending.reject(new KakapoRpcError(pending.method, error.message ?? "Unknown RPC error", error.code, {
+                    requestId: message.id,
+                }));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        // Broadcast echoes include jsonrpc/method/id but no result/error and are intentionally ignored.
+        if (typeof message.token === "string") {
+            this.deliverToken(message.token, message);
+        }
+    }
+    deliverToken(token, value) {
+        const waiter = this.tokenWaiters.get(token);
+        if (!waiter) {
+            this.tokenInbox.set(token, value);
+            return;
+        }
+        clearTimeout(waiter.timer);
+        this.tokenWaiters.delete(token);
+        waiter.resolve(value);
+    }
+    handleClose() {
+        this.socket = undefined;
+        this.rejectAll("The Kakapo WebSocket connection closed unexpectedly.");
+    }
+    rejectAll(message) {
+        for (const pending of this.requests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new KakapoConnectionError(message, {
+                code: "CONNECTION_CLOSED",
+                operation: pending.method,
+                hint: "Reconnect and refresh the scene before retrying the operation.",
+            }));
+        }
+        this.requests.clear();
+        for (const [token, waiter] of this.tokenWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new KakapoConnectionError(message, {
+                code: "CONNECTION_CLOSED",
+                operation: "waitForToken",
+                details: { token },
+            }));
+        }
+        this.tokenWaiters.clear();
+    }
+}
+export function parseBinaryFrame(bytes) {
+    if (bytes.byteLength < 48) {
+        throw new KakapoValidationError(`Binary frame is ${bytes.byteLength} bytes; Kakapo requires a 48-byte header.`, {
+            code: "INVALID_BINARY_FRAME",
+            operation: "parseBinaryFrame",
+            received: bytes.byteLength,
+            expected: "at least 48 bytes",
+        });
+    }
+    const header = bytes.subarray(0, 16);
+    const tokenEnd = header.indexOf(0);
+    const token = new TextDecoder().decode(header.subarray(0, tokenEnd === -1 ? 16 : tokenEnd));
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return {
+        token,
+        version: view.getUint32(16, true),
+        width: view.getUint32(20, true),
+        height: view.getUint32(24, true),
+        type: view.getUint32(28, true),
+        payload: bytes.slice(48),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,359 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Transform {
+    position: Vec3;
+    rotation: Vec3;
+    scale: Vec3;
+}
+export type NodeKind = "primitive" | "union" | "light" | "curve" | "group" | "text" | "field" | "svg" | "mesh" | "decal" | "openScad" | "socket";
+export type PrimitiveOperation = "subtract" | "union" | "brush" | "intersect";
+export type PrimitiveType = "sphere" | "cylinder" | "box" | "cone" | "torus" | "link" | "hexagon" | "triangular" | "octahedron" | "pyramid" | "glyph" | "field" | "ellipsoid" | "capsule";
+export type FieldColorSampling = "ignore" | "average" | "override" | "overrideMaterial" | "multiply";
+export type TextWrap = "disabled" | "always" | "whiteSpace";
+export type TextAlign = "left" | "center" | "right";
+export type LightType = "rect" | "sphere" | "distant";
+export interface NodeBase {
+    id: number;
+    kind: NodeKind;
+    name: string;
+    parentId: number | null;
+    transform: Transform;
+    pickable: boolean;
+}
+export interface TransformNode extends NodeBase {
+    hidden: boolean;
+}
+export interface MaterialNode {
+    materialId: number | null;
+}
+export interface OperationNode {
+    operation: PrimitiveOperation;
+    blend: number;
+}
+export type MirrorPlaneConstraint = 0 | 1 | 2 | 3;
+export interface MirrorPlane {
+    position: Vec3;
+    rotation: Vec3;
+    value: number;
+    hide: number;
+    hideMirrorPlane: boolean;
+    constraint: MirrorPlaneConstraint;
+    customRotation?: Vec3;
+}
+export type MirrorPlanes = [MirrorPlane, MirrorPlane, MirrorPlane, MirrorPlane];
+export interface MirrorNode {
+    mirrors: MirrorPlanes;
+}
+export interface PrimitiveNode extends TransformNode, MaterialNode, OperationNode, MirrorNode {
+    kind: "primitive";
+    color: Vec3;
+    primitive: PrimitiveType;
+    round: number;
+    thickness: number;
+    inflation: number;
+    materialNeutralCutout: boolean;
+}
+export interface UnionNode extends TransformNode, OperationNode {
+    kind: "union";
+    resolution: number;
+    thickness: number;
+    inflation: number;
+    materialNeutralCutout: boolean;
+}
+export interface GroupNode extends TransformNode {
+    kind: "group";
+}
+export interface LightNode extends NodeBase {
+    kind: "light";
+    color: Vec3;
+    power: number;
+    collimation: number;
+    lightType: LightType;
+    size: Vec2;
+    textureFile: string;
+}
+export interface CurvePoint {
+    position: Vec3;
+    rotation: Vec3;
+    scale: Vec3;
+    materialId: number | null;
+    round: number;
+    fixed: boolean;
+}
+export interface CurveNode extends NodeBase, MaterialNode, OperationNode, MirrorNode {
+    kind: "curve";
+    hidden: boolean;
+    primitive: PrimitiveType;
+    density: number;
+    roundness: number;
+    smoothing: number;
+    materialNeutralCutout: boolean;
+    points: CurvePoint[];
+}
+export interface TextNode extends TransformNode, MaterialNode, OperationNode {
+    kind: "text";
+    text: string;
+    fontFamily: string;
+    weight: number;
+    italic: boolean;
+    round: number;
+    width: number;
+    wrap: TextWrap;
+    align: TextAlign;
+    spacing: number;
+    lineHeight: number;
+    materialNeutralCutout: boolean;
+}
+export interface SvgSegment {
+    point: Vec2;
+    handleIn: Vec2;
+    handleOut: Vec2;
+}
+export interface SvgPath {
+    segments: SvgSegment[];
+    closed: boolean;
+}
+export interface SvgNode extends TransformNode, MaterialNode, OperationNode {
+    kind: "svg";
+    paths: SvgPath[];
+    inflate: boolean;
+    outline: boolean;
+    outlineSize: number;
+    materialNeutralCutout: boolean;
+}
+export interface MeshNode extends TransformNode, MaterialNode {
+    kind: "mesh";
+    mesh: string;
+    meshIndex: number;
+    smoothNormals: boolean;
+    colorSampling: FieldColorSampling;
+}
+export interface FieldNode extends TransformNode, MaterialNode, OperationNode {
+    kind: "field";
+    field: string;
+    inflation: number;
+    colorSampling: FieldColorSampling;
+    materialNeutralCutout: boolean;
+}
+export interface DecalNode extends TransformNode, MaterialNode {
+    kind: "decal";
+    image: string;
+    global: boolean;
+    colorSampling: "texture" | "multiply" | "material";
+}
+export interface OpenScadNode extends TransformNode, MaterialNode, OperationNode {
+    kind: "openScad";
+    scriptId: number;
+    params: Record<string, JsonValue>;
+    enabled: boolean;
+}
+export interface SocketNode extends TransformNode {
+    kind: "socket";
+    tag: string;
+}
+export type KakapoNode = PrimitiveNode | UnionNode | LightNode | CurveNode | GroupNode | TextNode | FieldNode | SvgNode | MeshNode | DecalNode | OpenScadNode | SocketNode;
+export interface NodeUpdate {
+    transform?: Partial<Transform>;
+    pickable?: boolean;
+    hidden?: boolean;
+    materialId?: number | null;
+    operation?: PrimitiveOperation;
+    blend?: number;
+    primitive?: PrimitiveType;
+    round?: number;
+    thickness?: number;
+    inflation?: number;
+    materialNeutralCutout?: boolean;
+    resolution?: number;
+    color?: Vec3;
+    power?: number;
+    collimation?: number;
+    lightType?: LightType;
+    size?: Vec2;
+    textureFile?: string;
+    density?: number;
+    roundness?: number;
+    smoothing?: number;
+    points?: CurvePoint[];
+    text?: string;
+    fontFamily?: string;
+    weight?: number;
+    italic?: boolean;
+    width?: number;
+    wrap?: TextWrap;
+    align?: TextAlign;
+    spacing?: number;
+    lineHeight?: number;
+    paths?: SvgPath[];
+    inflate?: boolean;
+    outline?: boolean;
+    outlineSize?: number;
+    mesh?: string;
+    meshIndex?: number;
+    smoothNormals?: boolean;
+    colorSampling?: FieldColorSampling | "texture" | "material";
+    field?: string;
+    image?: string;
+    global?: boolean;
+    scriptId?: number;
+    params?: Record<string, JsonValue>;
+    enabled?: boolean;
+    tag?: string;
+    mirrors?: MirrorPlanes;
+}
+export interface CreateNodeInput<K extends NodeKind = NodeKind> {
+    kind: K;
+    parentId: number;
+    name?: string;
+    properties?: NodeUpdate;
+    index?: number;
+}
+export interface MaterialData {
+    color: Vec3;
+    metalness: number;
+    roughness: number;
+    transmittance: number;
+    translucency: number;
+    translucencyWeight: number;
+    secondaryColor: Vec3;
+    subsurface: Vec3;
+    indexOfRefraction: number;
+    iridescence: number;
+    emission: number;
+    absorption: number;
+    sheen: number;
+    sheenRoughness: number;
+    specularTint: number;
+    dispersion: number;
+    surfaceOpacity: number;
+    volumetricEnabled: boolean;
+}
+export interface Material {
+    id: number;
+    data: MaterialData;
+    shaderIds: number[];
+}
+export interface OpenScadScript {
+    id: number;
+    name: string;
+    source: string;
+}
+export interface FontFace {
+    path: string;
+    weight: number;
+    italic: boolean;
+    shared: boolean;
+}
+export interface FontFamily {
+    name: string;
+    fonts: FontFace[];
+}
+export interface Scene {
+    version: number;
+    name: string;
+    nodes: Record<string, KakapoNode>;
+    tree: Record<string, number[]>;
+    materials: Record<string, Material>;
+    openScadScripts: Record<string, OpenScadScript>;
+    properties: Record<string, JsonValue>;
+    camera: Record<string, JsonValue>;
+}
+export interface BoundingBox {
+    min: Vec3;
+    max: Vec3;
+    transform: Transform;
+}
+export interface OpenScadParameter {
+    name: string;
+    default_value: JsonValue;
+    value: JsonValue;
+    min: JsonValue;
+    max: JsonValue;
+    step: JsonValue;
+    enum_options: Array<{
+        value: JsonValue;
+        raw_value: JsonValue;
+        label: string;
+    }>;
+}
+export interface OpenScadValidationResult {
+    ok: boolean;
+    version: number;
+    error: string;
+    warnings: string[];
+    params: OpenScadParameter[];
+    materials: Array<{
+        material_id: number;
+        color: Vec3;
+    }>;
+    bounding_box: {
+        min: Vec3;
+        max: Vec3;
+    } | null;
+}
+export interface BinaryFrame {
+    token: string;
+    version: number;
+    width: number;
+    height: number;
+    type: number;
+    payload: Uint8Array;
+}
+export type TokenMessage = BinaryFrame | Record<string, JsonValue>;
+export type ScreenshotView = "front" | "back" | "left" | "right" | "top" | "bottom" | "isometric";
+export interface CaptureScreenshotOptions {
+    /** Omit both selectors to frame all visible top-level scene nodes. */
+    targetId?: number;
+    targetIds?: number[];
+    view?: ScreenshotView;
+    timeoutMs?: number;
+}
+export interface ScreenshotImage {
+    data: Uint8Array;
+    mediaType: "image/jpeg";
+    width: number;
+    height: number;
+    view: ScreenshotView;
+    targetId: number;
+}
+export type JsonPatchOperation = {
+    op: "add" | "replace" | "test";
+    path: string;
+    value: JsonValue;
+} | {
+    op: "remove";
+    path: string;
+} | {
+    op: "move" | "copy";
+    from: string;
+    path: string;
+};
+export interface FindNodeOptions {
+    name?: string;
+    kind?: NodeKind;
+    ancestorId?: number;
+}
+export interface ListNodeOptions {
+    kind?: NodeKind;
+    parentId?: number;
+}
+export interface DeleteNodeOptions {
+    recursive?: boolean;
+}
+export interface KakapoAPIOptions {
+    url?: string;
+    requestTimeoutMs?: number;
+    connectTimeoutMs?: number;
+}
+export type PendingResources = JsonValue;

package/dist/types.js

@@ -0,0 +1 @@
+export {};