@nodetool-ai/sandbox-runtime 0.0.0-stage → 0.8.9-beta.2

package/dist/sandbox-bytes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Host→guest byte marshaling.
+ *
+ * Binary crosses the sandbox boundary asymmetrically. Guest→host is handled by
+ * the typed-array serializers, so a guest `Uint8Array` reaches a host function
+ * as a native one. Host→guest is not: a returned `Uint8Array` arrives in the
+ * guest as a numeric-keyed plain object. Anything producing bytes therefore
+ * returns a tagged base64 marker that the guest prelude rebuilds into a real
+ * `Uint8Array`.
+ *
+ * It lives in its own module because both the sandbox itself and the host
+ * module dispatcher marshal results, and the dispatcher is imported *by* the
+ * sandbox.
+ */
+export declare const SANDBOX_SERIALIZE_MAX_DEPTH = 32;
+/** Marker key carrying base64 bytes from host to guest. */
+export declare const SANDBOX_BYTES_MARKER = "__nodetool_sandbox_bytes__";
+/** The base64 alphabet, also inlined into the guest prelude's own codec. */
+export declare const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** Base64 bytes tagged for the guest prelude to revive as a `Uint8Array`. */
+export type GuestBytes = {
+    readonly [SANDBOX_BYTES_MARKER]: string;
+};
+/**
+ * What a host bridge hands the guest: JSON-shaped data, with byte payloads
+ * carried as {@link GuestBytes} markers. Every host module export and every
+ * bridge return value satisfies this contract — a function, a class instance,
+ * or a live handle cannot cross the boundary.
+ */
+export type GuestValue = null | undefined | boolean | number | string | GuestBytes | readonly GuestValue[] | {
+    readonly [key: string]: GuestValue;
+};
+/** Tag bytes for the guest prelude to turn back into a real `Uint8Array`. */
+export declare function toGuestBytes(bytes: Uint8Array): GuestBytes;
+/**
+ * Same tagging, applied at any depth. A call that returns bytes inside a record
+ * (`image.decode`'s `{width, height, pixels}`, a zip's entry map) hands its
+ * result through this; the guest side pairs it with `__wrapDeep`, which revives
+ * every marker.
+ */
+export declare function toGuestBytesDeep(value: unknown, depth?: number): unknown;
+//# sourceMappingURL=sandbox-bytes.d.ts.map

package/dist/sandbox-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-bytes.d.ts","sourceRoot":"","sources":["../src/sandbox-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE,4EAA4E;AAC5E,eAAO,MAAM,eAAe,qEACwC,CAAC;AAErE,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYtD;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,IAAI,GACJ,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,UAAU,EAAE,GACrB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,CAAC;AAE3C,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAcnE"}

package/dist/sandbox-bytes.js

@@ -0,0 +1,61 @@
+/**
+ * Host→guest byte marshaling.
+ *
+ * Binary crosses the sandbox boundary asymmetrically. Guest→host is handled by
+ * the typed-array serializers, so a guest `Uint8Array` reaches a host function
+ * as a native one. Host→guest is not: a returned `Uint8Array` arrives in the
+ * guest as a numeric-keyed plain object. Anything producing bytes therefore
+ * returns a tagged base64 marker that the guest prelude rebuilds into a real
+ * `Uint8Array`.
+ *
+ * It lives in its own module because both the sandbox itself and the host
+ * module dispatcher marshal results, and the dispatcher is imported *by* the
+ * sandbox.
+ */
+/** How deep the marshaler walks before it stops rewriting. */
+import { isObjectLike } from "./utils/type-guards.js";
+export const SANDBOX_SERIALIZE_MAX_DEPTH = 32;
+/** Marker key carrying base64 bytes from host to guest. */
+export const SANDBOX_BYTES_MARKER = "__nodetool_sandbox_bytes__";
+/** The base64 alphabet, also inlined into the guest prelude's own codec. */
+export const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function encodeBase64(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const c = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        out +=
+            BASE64_ALPHABET[(c >> 18) & 63] +
+                BASE64_ALPHABET[(c >> 12) & 63] +
+                (i + 1 < bytes.length ? BASE64_ALPHABET[(c >> 6) & 63] : "=") +
+                (i + 2 < bytes.length ? BASE64_ALPHABET[c & 63] : "=");
+    }
+    return out;
+}
+/** Tag bytes for the guest prelude to turn back into a real `Uint8Array`. */
+export function toGuestBytes(bytes) {
+    return { [SANDBOX_BYTES_MARKER]: encodeBase64(bytes) };
+}
+/**
+ * Same tagging, applied at any depth. A call that returns bytes inside a record
+ * (`image.decode`'s `{width, height, pixels}`, a zip's entry map) hands its
+ * result through this; the guest side pairs it with `__wrapDeep`, which revives
+ * every marker.
+ */
+export function toGuestBytesDeep(value, depth = 0) {
+    if (value instanceof Uint8Array)
+        return toGuestBytes(value);
+    if (depth >= SANDBOX_SERIALIZE_MAX_DEPTH)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => toGuestBytesDeep(v, depth + 1));
+    }
+    if (isObjectLike(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = toGuestBytesDeep(v, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=sandbox-bytes.js.map

package/dist/sandbox-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-bytes.js","sourceRoot":"","sources":["../src/sandbox-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8DAA8D;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,4BAA4B,CAAC;AAEjE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAC1B,kEAAkE,CAAC;AAErE,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GACL,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,GAAG;YACD,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;gBAC/B,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;gBAC/B,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC7D,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAqBD,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC;IACxD,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,IAAI,2BAA2B;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/sandbox-canvas-api.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The Canvas 2D surface the sandbox exposes, named in one place.
+ *
+ * Two sides read these lists and must agree: the guest-side recorder in the
+ * sandbox prelude, which builds a context object with exactly these members,
+ * and the host-side replay in `sandbox-media.ts`, which refuses any op naming
+ * something outside them. Splitting them out of the media engine keeps that
+ * engine — and the native canvas behind it — lazily loaded, since the prelude
+ * needs the names long before anything draws.
+ */
+/** Context properties a recorded draw list may set. */
+export declare const CANVAS_PROPERTIES: readonly ["fillStyle", "strokeStyle", "lineWidth", "lineCap", "lineJoin", "miterLimit", "lineDashOffset", "globalAlpha", "globalCompositeOperation", "filter", "font", "textAlign", "textBaseline", "direction", "letterSpacing", "imageSmoothingEnabled", "imageSmoothingQuality", "shadowColor", "shadowBlur", "shadowOffsetX", "shadowOffsetY"];
+/**
+ * Context methods a recorded draw list may call. `drawImage` is deliberately
+ * absent: it is the one call carrying binary, and both sides special-case it.
+ */
+export declare const CANVAS_METHODS: readonly ["save", "restore", "translate", "rotate", "scale", "transform", "setTransform", "resetTransform", "beginPath", "closePath", "moveTo", "lineTo", "bezierCurveTo", "quadraticCurveTo", "arc", "arcTo", "ellipse", "rect", "roundRect", "fill", "stroke", "clip", "fillRect", "strokeRect", "clearRect", "fillText", "strokeText", "setLineDash"];
+/** Gradient factories the recorder offers; each returns a gradient handle. */
+export declare const CANVAS_GRADIENT_FACTORIES: {
+    readonly createLinearGradient: "linear";
+    readonly createRadialGradient: "radial";
+    readonly createConicGradient: "conic";
+};
+/**
+ * Marker key on a gradient handle. A gradient is a host object, so the guest
+ * holds a tag instead and the renderer swaps in the real one when the tag is
+ * assigned to `fillStyle` or `strokeStyle`.
+ */
+export declare const CANVAS_GRADIENT_MARKER = "__nodetool_canvas_gradient__";
+//# sourceMappingURL=sandbox-canvas-api.d.ts.map

package/dist/sandbox-canvas-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-canvas-api.d.ts","sourceRoot":"","sources":["../src/sandbox-canvas-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,YAC5B,WAAW,EACX,aAAa,EACb,WAAW,EACX,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,0BAA0B,EAC1B,QAAQ,EACR,MAAM,EACN,WAAW,EACX,cAAc,EACd,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,eAAe,CACP,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc,YACzB,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,OAAO,EACP,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,KAAK,EACL,OAAO,EACP,SAAS,EACT,MAAM,EACN,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,CACL,CAAC;AAEX,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB;aACpC,oBAAoB,EAAE,QAAQ;aAC9B,oBAAoB,EAAE,QAAQ;aAC9B,mBAAmB,EAAE,OAAO;CACpB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,iCAAiC,CAAC"}

package/dist/sandbox-canvas-api.js

@@ -0,0 +1,81 @@
+/**
+ * The Canvas 2D surface the sandbox exposes, named in one place.
+ *
+ * Two sides read these lists and must agree: the guest-side recorder in the
+ * sandbox prelude, which builds a context object with exactly these members,
+ * and the host-side replay in `sandbox-media.ts`, which refuses any op naming
+ * something outside them. Splitting them out of the media engine keeps that
+ * engine — and the native canvas behind it — lazily loaded, since the prelude
+ * needs the names long before anything draws.
+ */
+/** Context properties a recorded draw list may set. */
+export const CANVAS_PROPERTIES = [
+    "fillStyle",
+    "strokeStyle",
+    "lineWidth",
+    "lineCap",
+    "lineJoin",
+    "miterLimit",
+    "lineDashOffset",
+    "globalAlpha",
+    "globalCompositeOperation",
+    "filter",
+    "font",
+    "textAlign",
+    "textBaseline",
+    "direction",
+    "letterSpacing",
+    "imageSmoothingEnabled",
+    "imageSmoothingQuality",
+    "shadowColor",
+    "shadowBlur",
+    "shadowOffsetX",
+    "shadowOffsetY"
+];
+/**
+ * Context methods a recorded draw list may call. `drawImage` is deliberately
+ * absent: it is the one call carrying binary, and both sides special-case it.
+ */
+export const CANVAS_METHODS = [
+    "save",
+    "restore",
+    "translate",
+    "rotate",
+    "scale",
+    "transform",
+    "setTransform",
+    "resetTransform",
+    "beginPath",
+    "closePath",
+    "moveTo",
+    "lineTo",
+    "bezierCurveTo",
+    "quadraticCurveTo",
+    "arc",
+    "arcTo",
+    "ellipse",
+    "rect",
+    "roundRect",
+    "fill",
+    "stroke",
+    "clip",
+    "fillRect",
+    "strokeRect",
+    "clearRect",
+    "fillText",
+    "strokeText",
+    "setLineDash"
+];
+/** Gradient factories the recorder offers; each returns a gradient handle. */
+export const CANVAS_GRADIENT_FACTORIES = {
+    createLinearGradient: "linear",
+    createRadialGradient: "radial",
+    createConicGradient: "conic"
+};
+/**
+ * Marker key on a gradient handle. A gradient is a host object, so the guest
+ * holds a tag instead and the renderer swaps in the real one when the tag is
+ * assigned to `fillStyle` or `strokeStyle`.
+ */
+export const CANVAS_GRADIENT_MARKER = "__nodetool_canvas_gradient__";
+//# sourceMappingURL=sandbox-canvas-api.js.map

package/dist/sandbox-canvas-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-canvas-api.js","sourceRoot":"","sources":["../src/sandbox-canvas-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uDAAuD;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,WAAW;IACX,aAAa;IACb,WAAW;IACX,SAAS;IACT,UAAU;IACV,YAAY;IACZ,gBAAgB;IAChB,aAAa;IACb,0BAA0B;IAC1B,QAAQ;IACR,MAAM;IACN,WAAW;IACX,cAAc;IACd,WAAW;IACX,eAAe;IACf,uBAAuB;IACvB,uBAAuB;IACvB,aAAa;IACb,YAAY;IACZ,eAAe;IACf,eAAe;CACP,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM;IACN,SAAS;IACT,WAAW;IACX,QAAQ;IACR,OAAO;IACP,WAAW;IACX,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,eAAe;IACf,kBAAkB;IAClB,KAAK;IACL,OAAO;IACP,SAAS;IACT,MAAM;IACN,WAAW;IACX,MAAM;IACN,QAAQ;IACR,MAAM;IACN,UAAU;IACV,YAAY;IACZ,WAAW;IACX,UAAU;IACV,YAAY;IACZ,aAAa;CACL,CAAC;AAEX,8EAA8E;AAC9E,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,oBAAoB,EAAE,QAAQ;IAC9B,oBAAoB,EAAE,QAAQ;IAC9B,mBAAmB,EAAE,OAAO;CACpB,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,8BAA8B,CAAC"}

package/dist/sandbox-constants.d.ts

@@ -0,0 +1,5 @@
+/** Largest `crypto.getRandomValues` request the bridge will serve. */
+export declare const MAX_RANDOM_BYTES = 65536;
+/** Media member names, in the order the guest prelude re-wraps them. */
+export declare const MEDIA_REF_MEMBERS: readonly ["bytes", "text", "info", "toDocument", "toImage", "toAudio", "toVideo"];
+//# sourceMappingURL=sandbox-constants.d.ts.map

package/dist/sandbox-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-constants.d.ts","sourceRoot":"","sources":["../src/sandbox-constants.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,YAC5B,OAAO,EACP,MAAM,EACN,MAAM,EACN,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,CACD,CAAC"}

package/dist/sandbox-constants.js

@@ -0,0 +1,13 @@
+/** Largest `crypto.getRandomValues` request the bridge will serve. */
+export const MAX_RANDOM_BYTES = 65_536;
+/** Media member names, in the order the guest prelude re-wraps them. */
+export const MEDIA_REF_MEMBERS = [
+    "bytes",
+    "text",
+    "info",
+    "toDocument",
+    "toImage",
+    "toAudio",
+    "toVideo"
+];
+//# sourceMappingURL=sandbox-constants.js.map

package/dist/sandbox-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-constants.js","sourceRoot":"","sources":["../src/sandbox-constants.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO;IACP,MAAM;IACN,MAAM;IACN,YAAY;IACZ,SAAS;IACT,SAAS;IACT,SAAS;CACD,CAAC"}

package/dist/sandbox-json-transport.d.ts

@@ -0,0 +1,107 @@
+/**
+ * JSON transport for structured data across the QuickJS boundary.
+ *
+ * The wrapper marshals a value handle-by-handle: every object node costs four
+ * `evalCode` compilations inside the guest plus a `newFunction` allocation, and
+ * every property crosses as its own descriptor. Measured on this repo's engine
+ * that is ~150 µs per object node out of the guest and ~400 µs per object node
+ * into it — a Code node handed 5 000 rows spent 1.9 s reading them and another
+ * 0.8 s handing them back, before running a line of its own.
+ *
+ * Both directions carry JSON-shaped data, so the fast path is to move one
+ * string: the guest builds its answer with `JSON.stringify` and the host parses
+ * it, and the host encodes its globals here for the init prelude to parse.
+ * Measured on the same shapes, 20–25× either way.
+ *
+ * Two kinds of value would lose by that trade, and both ride *beside* the JSON
+ * in a sidecar the marshaler moves in one piece — a typed array (base64 inside
+ * the guest costs more than the marshal it replaces) and a string past
+ * {@link SIDECAR_STRING_THRESHOLD} (escaping a megabyte to unescape it again is
+ * two passes the primitive path never makes). A {@link JSON_SIDECAR_MARKER}
+ * holds its place by index.
+ *
+ * What JSON alone still cannot carry is carried by markers, so the round trip
+ * keeps the types the structured path preserved:
+ *
+ * - **dates** — an ISO string under {@link JSON_DATE_MARKER}, revived as a
+ *   `Date`. A `state.lastRun` that survives a Code node's invocations stays a
+ *   `Date` rather than degrading to a string on its first round trip.
+ * - **non-finite numbers** — `NaN` and the infinities under {@link
+ *   JSON_NUMBER_MARKER}. `JSON.stringify` writes them as `null`.
+ * - **undefined** — {@link JSON_UNDEFINED_MARKER}, so a property whose value is
+ *   `undefined` keeps its key. `JSON.stringify` drops it.
+ *
+ * Anything else — a function, a symbol, a bigint, a `Map`, a class instance —
+ * makes the encoder refuse that value, and its caller falls back to the
+ * wrapper's own marshaling, which is slow but total. The fast path never has to
+ * guess.
+ *
+ * A **cycle** is the one thing neither path carries: the wrapper's marshaler
+ * recurses until the runtime aborts with `list_empty(&rt->gc_obj_list)`, which
+ * kills the run with an assertion instead of an answer. So a cyclic global is
+ * refused by name, and a cyclic result becomes `String(value)` — the fallback
+ * `serializeResult` already documents for a value `JSON.stringify` rejects.
+ *
+ * Browser-safe: nothing here imports a Node builtin.
+ */
+/** Marker key carrying an ISO timestamp for a `Date`. */
+export declare const JSON_DATE_MARKER = "__nodetool_sandbox_date__";
+/** Marker key carrying `"NaN"`, `"Infinity"`, or `"-Infinity"`. */
+export declare const JSON_NUMBER_MARKER = "__nodetool_sandbox_number__";
+/** Marker key standing in for an `undefined` property value. */
+export declare const JSON_UNDEFINED_MARKER = "__nodetool_sandbox_undefined__";
+/** Marker key carrying an index into the payload's sidecar. */
+export declare const JSON_SIDECAR_MARKER = "__nodetool_sandbox_side__";
+/**
+ * Strings at least this long travel in the sidecar rather than inside the JSON.
+ * Below it the escape/unescape pass is noise next to the run's fixed cost; a
+ * megabyte of text is where it stops being.
+ */
+export declare const SIDECAR_STRING_THRESHOLD = 8192;
+/** The global the guest parks its encoder on. */
+export declare const GUEST_MARSHAL_GLOBAL = "__nodetool_marshal__";
+/** The global carrying the host's encoded globals for the prelude to read. */
+export declare const GUEST_GLOBALS_JSON_BINDING = "__nodetool_globals_json__";
+/** The global carrying the sidecar those encoded globals index into. */
+export declare const GUEST_GLOBALS_SIDECAR_BINDING = "__nodetool_globals_side__";
+/** What one encoded batch of host globals hands the guest prelude. */
+export interface HostRecordEncoding {
+    /** JSON for the guest to parse: `{name: value}` over the accepted entries. */
+    readonly json: string;
+    /** Values the JSON refers to by index, moved whole rather than escaped. */
+    readonly sidecar: readonly string[];
+    /** Entries no JSON representation covers. The caller marshals these itself. */
+    readonly skipped: readonly string[];
+    /** Entries that refer back to themselves. Neither path can carry these. */
+    readonly cyclic: readonly string[];
+}
+/**
+ * Encode a batch of named host values for the guest to `JSON.parse` and revive.
+ *
+ * One batch means one sidecar and one parse. An entry holding something JSON
+ * plus the markers cannot carry is reported in `skipped` instead of failing the
+ * batch, so one exotic global costs only itself; an entry that refers back to
+ * itself is reported in `cyclic`, which no path can carry.
+ */
+export declare function encodeHostRecord(values: Record<string, unknown>): HostRecordEncoding;
+/**
+ * Decode what the guest's encoder produced: either a JSON string plus the
+ * sidecar its markers index, or a value the guest handed over as-is (a
+ * primitive, or something `JSON.stringify` refused) under `raw`.
+ *
+ * The guest owns this string, so a body that overwrites the encoder can hand
+ * back nonsense. That is not an escalation — the guest owned its own result
+ * either way — so a payload that will not parse decodes as `undefined` rather
+ * than failing the run.
+ */
+export declare function decodeGuestPayload(payload: unknown): unknown;
+/**
+ * The guest half, spliced into the init prelude: the encoder the entry module
+ * and the sync extractor call, and the parse of whatever globals the host
+ * encoded.
+ *
+ * `__bytesMarker` and `fromBase64` are defined earlier in the prelude, so this
+ * source has to follow them.
+ */
+export declare const GUEST_JSON_TRANSPORT_SOURCE: string;
+//# sourceMappingURL=sandbox-json-transport.d.ts.map

package/dist/sandbox-json-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-json-transport.d.ts","sourceRoot":"","sources":["../src/sandbox-json-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AASH,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAE5D,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAEhE,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,mCAAmC,CAAC;AAEtE,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,8BAA8B,CAAC;AAEtE,wEAAwE;AACxE,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AAwFzE,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,kBAAkB,CAkBpB;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAgB5D;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QA4EvC,CAAC"}