@rybosome/tspice 0.0.3 → 0.0.8

package/backend-wasm/dist/codec/errors.js

@@ -1,5 +1,37 @@
+import { decodeWasmSpiceError, WASM_ERR_MAX_BYTES, withMalloc } from "./alloc.js";
+function readLastErrorField(module, which) {
+    const outMaxBytes = WASM_ERR_MAX_BYTES;
+    return withMalloc(module, outMaxBytes, (outPtr) => {
+        module.HEAPU8[outPtr] = 0;
+        if (which === "short")
+            module._tspice_get_last_error_short(outPtr, outMaxBytes);
+        if (which === "long")
+            module._tspice_get_last_error_long(outPtr, outMaxBytes);
+        if (which === "trace")
+            module._tspice_get_last_error_trace(outPtr, outMaxBytes);
+        const s = module.UTF8ToString(outPtr, outMaxBytes).trim();
+        return s || undefined;
+    });
+}
+/** Throw a JS Error for the last CSPICE error recorded in the WASM module. */
 export function throwWasmSpiceError(module, errPtr, errMaxBytes, code) {
-    const message = module.UTF8ToString(errPtr, errMaxBytes).trim();
-    throw new Error(message || `CSPICE call failed with code ${code}`);
+    const message = decodeWasmSpiceError(module, errPtr, errMaxBytes, code);
+    // Best-effort structured fields.
+    //
+    // The C shim stores SPICE fields out-of-band, so for non-CSPICE validation
+    // errors we must avoid accidentally attaching stale fields from a previous
+    // CSPICE failure.
+    const spiceShort = readLastErrorField(module, "short");
+    const shouldAttachSpiceFields = !!spiceShort && message.includes(spiceShort);
+    const spiceLong = shouldAttachSpiceFields ? readLastErrorField(module, "long") : undefined;
+    const spiceTrace = shouldAttachSpiceFields ? readLastErrorField(module, "trace") : undefined;
+    const err = new Error(message);
+    if (shouldAttachSpiceFields && spiceShort)
+        err.spiceShort = spiceShort;
+    if (shouldAttachSpiceFields && spiceLong)
+        err.spiceLong = spiceLong;
+    if (shouldAttachSpiceFields && spiceTrace)
+        err.spiceTrace = spiceTrace;
+    throw err;
 }
 //# sourceMappingURL=errors.js.map

package/backend-wasm/dist/codec/found.d.ts

@@ -1,8 +1,10 @@
 import type { Found } from "#backend-contract";
 import type { EmscriptenModule } from "../lowlevel/exports.js";
+/** Invoke a WASM function that follows the SPICE `found`-flag convention (int output + found flag). */
 export declare function tspiceCallFoundInt(module: EmscriptenModule, fn: (argPtr: number, outIntPtr: number, foundPtr: number, errPtr: number, errMaxBytes: number) => number, arg: string): Found<{
     value: number;
 }>;
+/** Invoke a WASM function that follows the SPICE `found`-flag convention (string output + found flag). */
 export declare function tspiceCallFoundString(module: EmscriptenModule, fn: (code: number, outStrPtr: number, outStrMaxBytes: number, foundPtr: number, errPtr: number, errMaxBytes: number) => number, code: number): Found<{
     value: string;
 }>;

package/backend-wasm/dist/codec/found.js

@@ -1,52 +1,34 @@
+import { WASM_ERR_MAX_BYTES, withAllocs } from "./alloc.js";
 import { throwWasmSpiceError } from "./errors.js";
 import { writeUtf8CString } from "./strings.js";
+/** Invoke a WASM function that follows the SPICE `found`-flag convention (int output + found flag). */
 export function tspiceCallFoundInt(module, fn, arg) {
-    const errMaxBytes = 2048;
-    const errPtr = module._malloc(errMaxBytes);
+    const errMaxBytes = WASM_ERR_MAX_BYTES;
     const argPtr = writeUtf8CString(module, arg);
-    const outPtr = module._malloc(4);
-    const foundPtr = module._malloc(4);
-    if (!errPtr || !argPtr || !outPtr || !foundPtr) {
-        for (const ptr of [foundPtr, outPtr, argPtr, errPtr]) {
-            if (ptr)
-                module._free(ptr);
-        }
-        throw new Error("WASM malloc failed");
-    }
     try {
-        module.HEAP32[outPtr >> 2] = 0;
-        module.HEAP32[foundPtr >> 2] = 0;
-        const result = fn(argPtr, outPtr, foundPtr, errPtr, errMaxBytes);
-        if (result !== 0) {
-            throwWasmSpiceError(module, errPtr, errMaxBytes, result);
-        }
-        const found = (module.HEAP32[foundPtr >> 2] ?? 0) !== 0;
-        if (!found) {
-            return { found: false };
-        }
-        return { found: true, value: module.HEAP32[outPtr >> 2] ?? 0 };
+        return withAllocs(module, [errMaxBytes, 4, 4], (errPtr, outPtr, foundPtr) => {
+            module.HEAP32[outPtr >> 2] = 0;
+            module.HEAP32[foundPtr >> 2] = 0;
+            const result = fn(argPtr, outPtr, foundPtr, errPtr, errMaxBytes);
+            if (result !== 0) {
+                throwWasmSpiceError(module, errPtr, errMaxBytes, result);
+            }
+            const found = (module.HEAP32[foundPtr >> 2] ?? 0) !== 0;
+            if (!found) {
+                return { found: false };
+            }
+            return { found: true, value: module.HEAP32[outPtr >> 2] ?? 0 };
+        });
     }
     finally {
-        module._free(foundPtr);
-        module._free(outPtr);
         module._free(argPtr);
-        module._free(errPtr);
     }
 }
+/** Invoke a WASM function that follows the SPICE `found`-flag convention (string output + found flag). */
 export function tspiceCallFoundString(module, fn, code) {
-    const errMaxBytes = 2048;
-    const errPtr = module._malloc(errMaxBytes);
+    const errMaxBytes = WASM_ERR_MAX_BYTES;
     const outMaxBytes = 256;
-    const outPtr = module._malloc(outMaxBytes);
-    const foundPtr = module._malloc(4);
-    if (!errPtr || !outPtr || !foundPtr) {
-        for (const ptr of [foundPtr, outPtr, errPtr]) {
-            if (ptr)
-                module._free(ptr);
-        }
-        throw new Error("WASM malloc failed");
-    }
-    try {
+    return withAllocs(module, [errMaxBytes, outMaxBytes, 4], (errPtr, outPtr, foundPtr) => {
         module.HEAPU8[outPtr] = 0;
         module.HEAP32[foundPtr >> 2] = 0;
         const result = fn(code, outPtr, outMaxBytes, foundPtr, errPtr, errMaxBytes);
@@ -58,11 +40,6 @@ export function tspiceCallFoundString(module, fn, code) {
             return { found: false };
         }
         return { found: true, value: module.UTF8ToString(outPtr, outMaxBytes).trim() };
-    }
-    finally {
-        module._free(foundPtr);
-        module._free(outPtr);
-        module._free(errPtr);
-    }
+    });
 }
 //# sourceMappingURL=found.js.map

package/backend-wasm/dist/codec/strings.d.ts

@@ -1,3 +1,33 @@
 import type { EmscriptenModule } from "../lowlevel/exports.js";
-export declare function writeUtf8CString(module: EmscriptenModule, value: string): number;
+type Utf8CStringWriteModule = Pick<EmscriptenModule, "_malloc" | "HEAPU8">;
+type Utf8CStringArrayWriteModule = Pick<EmscriptenModule, "_malloc" | "_free" | "HEAPU8" | "HEAPU32">;
+type Utf8CStringArrayFreeModule = Pick<EmscriptenModule, "_free">;
+type Utf8CStringArray = {
+    /** Pointer to a contiguous `char*[]` array (written via `HEAPU32`), or `0` for empty arrays. */
+    ptr: number;
+    /** Pointers to each allocated null-terminated string. */
+    itemPtrs: number[];
+};
+/** Allocate and write a null-terminated UTF-8 C string into the WASM heap; returns the pointer. */
+export declare function writeUtf8CString(module: Utf8CStringWriteModule, value: string): number;
+/**
+ * Allocate a `char*[]` array (4-byte pointers) and a null-terminated utf-8 string for each
+ * item.
+ *
+ * The caller owns the returned memory and must free it with {@link freeUtf8CStringArray}.
+ */
+export declare function writeUtf8CStringArray(module: Utf8CStringArrayWriteModule, values: string[]): Utf8CStringArray;
+/** Free memory allocated by {@link writeUtf8CStringArray} (idempotent). */
+export declare function freeUtf8CStringArray(module: Utf8CStringArrayFreeModule, arr: Utf8CStringArray): void;
+/**
+ * Reads a fixed-width C string (padded/truncated) from the WASM heap.
+ *
+ * - Decodes at most `width` bytes.
+ * - Treats the first `\0` byte as the terminator (embedded NUL ends the string).
+ * - Trims *right* whitespace only (SPICE commonly pads with trailing spaces).
+ */
+export declare function readFixedWidthCString(module: Pick<EmscriptenModule, "HEAPU8">, ptr: number, width: number): string;
+/** Read an array of fixed-width C strings from the WASM heap (see {@link readFixedWidthCString}). */
+export declare function readFixedWidthCStringArray(module: Pick<EmscriptenModule, "HEAPU8">, ptr: number, count: number, width: number): string[];
+export {};
 //# sourceMappingURL=strings.d.ts.map

package/backend-wasm/dist/codec/strings.js

@@ -1,12 +1,99 @@
+import { mallocOrThrow } from "./alloc.js";
+// Re-use a shared decoder to avoid allocating one per call.
+const UTF8_DECODER = new TextDecoder();
+// Re-use a shared encoder to avoid allocating one per call.
+const UTF8_ENCODER = new TextEncoder();
+/** Allocate and write a null-terminated UTF-8 C string into the WASM heap; returns the pointer. */
 export function writeUtf8CString(module, value) {
-    const encoder = new TextEncoder();
-    const encoded = encoder.encode(value);
-    const ptr = module._malloc(encoded.length + 1);
-    if (!ptr) {
-        throw new Error("WASM malloc failed");
-    }
+    const encoded = UTF8_ENCODER.encode(value);
+    const ptr = mallocOrThrow(module, encoded.length + 1);
     module.HEAPU8.set(encoded, ptr);
     module.HEAPU8[ptr + encoded.length] = 0;
     return ptr;
 }
+/**
+ * Allocate a `char*[]` array (4-byte pointers) and a null-terminated utf-8 string for each
+ * item.
+ *
+ * The caller owns the returned memory and must free it with {@link freeUtf8CStringArray}.
+ */
+export function writeUtf8CStringArray(module, values) {
+    if (values.length === 0) {
+        return { ptr: 0, itemPtrs: [] };
+    }
+    // This helper intentionally targets wasm32 (32-bit pointers).
+    // If we ever add wasm64, this should be revisited to use the correct pointer heap.
+    const ptrBytes = module.HEAPU32.BYTES_PER_ELEMENT;
+    if (ptrBytes !== 4) {
+        throw new Error('writeUtf8CStringArray assumes 32-bit pointers (wasm32).');
+    }
+    const arr = { ptr: 0, itemPtrs: [] };
+    arr.ptr = mallocOrThrow(module, values.length * ptrBytes);
+    try {
+        if (arr.ptr % ptrBytes !== 0) {
+            throw new Error(`Internal error: unaligned pointer array base pointer (ptr=${arr.ptr}, ptrBytes=${ptrBytes})`);
+        }
+        const baseIndex = arr.ptr / ptrBytes;
+        // IMPORTANT: With `ALLOW_MEMORY_GROWTH=1`, any allocation (including the `_malloc()`
+        // inside `writeUtf8CString()`) may grow the WASM memory and cause Emscripten to
+        // recreate the `HEAP*` typed array views. Do not cache `module.HEAPU8` /
+        // `module.HEAPU32` across allocations; always access them at point-of-use after
+        // the allocation completes.
+        for (let i = 0; i < values.length; i++) {
+            const itemPtr = writeUtf8CString(module, values[i]);
+            // Safety: HEAPU32 stores unsigned 32-bit pointers; guard against accidental truncation.
+            if (!Number.isInteger(itemPtr) || itemPtr < 0 || itemPtr > 0xffff_ffff) {
+                throw new Error(`Internal error: string item pointer out of u32 range (itemPtr=${itemPtr})`);
+            }
+            arr.itemPtrs.push(itemPtr);
+            module.HEAPU32[baseIndex + i] = itemPtr;
+        }
+        return arr;
+    }
+    catch (e) {
+        freeUtf8CStringArray(module, arr);
+        throw e;
+    }
+}
+/** Free memory allocated by {@link writeUtf8CStringArray} (idempotent). */
+export function freeUtf8CStringArray(module, arr) {
+    for (const itemPtr of arr.itemPtrs) {
+        if (itemPtr) {
+            module._free(itemPtr);
+        }
+    }
+    // Make the helper idempotent (safe to call twice).
+    arr.itemPtrs.length = 0;
+    if (arr.ptr) {
+        module._free(arr.ptr);
+    }
+    arr.ptr = 0;
+}
+/**
+ * Reads a fixed-width C string (padded/truncated) from the WASM heap.
+ *
+ * - Decodes at most `width` bytes.
+ * - Treats the first `\0` byte as the terminator (embedded NUL ends the string).
+ * - Trims *right* whitespace only (SPICE commonly pads with trailing spaces).
+ */
+export function readFixedWidthCString(module, ptr, width) {
+    if (width <= 0) {
+        return "";
+    }
+    const bytes = module.HEAPU8.subarray(ptr, ptr + width);
+    const nulIndex = bytes.indexOf(0);
+    const end = nulIndex === -1 ? bytes.length : nulIndex;
+    return UTF8_DECODER.decode(bytes.subarray(0, end)).trimEnd();
+}
+/** Read an array of fixed-width C strings from the WASM heap (see {@link readFixedWidthCString}). */
+export function readFixedWidthCStringArray(module, ptr, count, width) {
+    if (count <= 0 || width <= 0) {
+        return [];
+    }
+    const out = new Array(count);
+    for (let i = 0; i < count; i++) {
+        out[i] = readFixedWidthCString(module, ptr + i * width, width);
+    }
+    return out;
+}
 //# sourceMappingURL=strings.js.map

package/backend-wasm/dist/domains/cells-windows.d.ts

@@ -0,0 +1,9 @@
+import type { CellsWindowsApi } from "#backend-contract";
+import type { EmscriptenModule } from "../lowlevel/exports.js";
+/** Assert that a cell handle was allocated by (and is still owned by) this WASM backend instance. */
+export declare function assertWasmOwnedCellHandle(module: EmscriptenModule, handle: number, context: string): void;
+/** Assert that a window handle was allocated by (and is still owned by) this WASM backend instance. */
+export declare function assertWasmOwnedWindowHandle(module: EmscriptenModule, handle: number, context: string): void;
+/** Create a {@link CellsWindowsApi} implementation backed by a WASM Emscripten module. */
+export declare function createCellsWindowsApi(module: EmscriptenModule): CellsWindowsApi;
+//# sourceMappingURL=cells-windows.d.ts.map