@arnilo/liveframe-runner-quickjs 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niloy Rahman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @arnilo/liveframe-runner-quickjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An isolated [Liveframe](https://github.com/ashiqrniloy/liveframe) runner. Widget code runs in [QuickJS](https://bellard.org/quickjs/) (WebAssembly, via `quickjs-emscripten`) inside a Bun child process that the runner owns and can kill. A host gets a real isolation boundary for hostile widget code without building a sandbox.
+
+Requires Bun ≥ 1.4.2 and `@arnilo/liveframe` `~0.3.0`. No Node runtime is supported.
+
+```ts
+import { quickjsRunner } from "@arnilo/liveframe-runner-quickjs";
+
+const runner = await quickjsRunner({ memoryBytes: 32 << 20, stackBytes: 256 << 10, timeoutMs: 250 });
+const result = await runner.render(pkg, inputs, { catalog, capabilities, surfaceId: "home", revision: 1 });
+runner.close(); // kills the child
+```
+
+It is a `Runner` (spec §7.5): use it wherever the app passes one, for example `renderPlacement({ runner, … })` from `/host`, or `runner:` in the `liveframe mcp` config. Call `close()` when done.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `memoryBytes` | 32 MiB | QuickJS heap limit per runtime |
+| `stackBytes` | 256 KiB | QuickJS stack limit. Not 1 MiB: QuickJS recurses on the host stack, and at 1 MiB some call shapes overflow it first, which aborts the engine |
+| `timeoutMs` | 250 | Soft deadline: QuickJS's interrupt handler stops the render. A render's `options.timeoutMs` overrides it |
+| `reuse` | `"none"` | `"none"`: every render gets a new runtime in a new wasm instance. `"package"`: one runtime per package hash is kept, so module state survives between renders. Faster; for code you trust to behave but have not tested, never for hostile code |
+| `maxRuntimes` | 16 | Runtimes kept with `reuse: "package"`, least recently used evicted first |
+
+## What it does
+
+- **No host API in the realm.** Widget code sees only ECMAScript built-ins. `fetch`, `process`, `Bun`, `Deno`, `require`, `WebAssembly`, timers and `console` are `undefined`; `globalThis.constructor.constructor("return this")()`, `eval` and `new Function` reach only the sandbox; `import()` goes to a loader that serves only the Liveframe kit, the package and its pinned libraries.
+- **A channel widget code cannot write to.** The parent–child channel is not reachable from the realm, so a widget cannot answer for another render.
+- **Law 2 on the host.** The host verifies the package hash and the library pins before anything is loaded and validates every tree the child returns. A malformed or forged answer is `render-failed`.
+- **Limits.** Heap, stack and time are `limit-exceeded`. A render stuck in one native call (QuickJS cannot interrupt those) is ended by killing the child 100 ms after the soft deadline; the next render starts a new child.
+- **Templates run on the host.** A template package runs no author code, so it needs no sandbox and renders in the parent.
+- **Pending jobs never run.** The runner never calls `executePendingJobs()`; a package whose top-level `await` does not settle is `render-failed`. A wasm instance whose engine throws to the host is dropped, never reused.
+
+## What it does not protect against
+
+- **The child runs with the host's privileges** (with an empty environment). Only QuickJS stands between widget code and the file system and network. A defect in QuickJS or in the wasm runtime is not covered. Run the child inside an OS sandbox (bubblewrap, a container) for defence in depth.
+- **CPU side channels and timing.**
+- **Memory pressure** on the host up to `memoryBytes` per runtime, plus the wasm instance and the child's baseline. With `reuse: "package"`, up to `maxRuntimes` runtimes at once. Measured (Linux, plan 031 Task 8): the child holds about 52 MiB resident at start, 74 MiB steady with `reuse: "none"` and about 90 MiB with `reuse: "package"` over five packages, with no growth across 500 and 1000 renders. The host parses at most what the heap allows, and a tree beyond the validator's limits is `invalid-prop` (a 14 MiB text node was).
+- **Renders run one at a time.** The runner owns one child, so a render waits for the one before it. A hostile widget that holds its render costs every render queued behind it up to `timeoutMs` + 100 ms plus about 250 ms to replace the child (measured: hold, kill, recover and next render 246 ms). Give untrusted authors their own runner, or keep their `timeoutMs` low.
+- **Only Linux has been measured.** macOS and Windows are expected to work (WebAssembly and `Bun.spawn`) and are not claimed.
+
+## Cost
+
+Measured on one Linux machine (Bun 1.4.4), agent-home (679 nodes): a fresh render is about 70 ms, of which about 30 ms is the fixed cost of a runtime and the kit; the child starts in about 21 ms; killing a stuck child and rendering the next request takes about 140–190 ms. See `plans/evidence/031-runner-options.md` in the repository. Templates and trusted code are cheaper with `templateRunner()` and `workerRunner()`.
+
+Prove a runner with `runnerSuite()` from `@arnilo/liveframe/conformance`; this package passes the contract and isolation cases.

package/dist/child.d.ts

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

package/dist/child.js

@@ -0,0 +1,18 @@
+// The child process entry: it holds the QuickJS wasm module and renders what its parent sends.
+// Run only by `quickjsRunner()`; the parent owns the channel, the deadline and `SIGKILL`.
+import { fileURLToPath } from "node:url";
+import { createEngine } from "./runtime.js";
+const send = (message) => {
+    process.send?.(message);
+};
+const wasm = await WebAssembly.compile(await Bun.file(fileURLToPath(import.meta.resolve("@jitl/quickjs-wasmfile-release-sync/wasm"))).arrayBuffer());
+const kit = await Bun.file(fileURLToPath(import.meta.resolve("@arnilo/liveframe/runner-kit.bundle.js"))).text();
+const engine = createEngine(wasm, kit, { maxRuntimes: Number(Bun.argv[2]) || 16 });
+process.on("disconnect", () => process.exit(0));
+process.on("message", async (message) => {
+    const request = message;
+    if (request.type !== "render")
+        return;
+    send({ type: "result", id: request.id, ...(await engine.render(request)) });
+});
+send({ type: "ready" });

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { Runner } from "@arnilo/liveframe/preview";
+export type QuickJsRunnerOptions = {
+    /** QuickJS's heap limit per runtime (default 32 MiB). */
+    readonly memoryBytes?: number;
+    /**
+     * QuickJS's stack limit (default 256 KiB). QuickJS recurses on the host stack: at 1 MiB some call
+     * shapes overflow it first, and the engine then aborts (decision 2026-11-08-2310).
+     */
+    readonly stackBytes?: number;
+    /** The default per-render limit in ms (default 250); a render's `options.timeoutMs` overrides it. */
+    readonly timeoutMs?: number;
+    /**
+     * `"none"` (default): every render gets a new runtime in a new wasm instance. `"package"`: a runtime
+     * per package hash is kept between renders, so module state survives. Faster; for code you trust
+     * to behave but have not tested, not for hostile code.
+     */
+    readonly reuse?: "none" | "package";
+    /** Runtimes kept with `reuse: "package"`, least recently used evicted first (default 16). */
+    readonly maxRuntimes?: number;
+};
+export type QuickJsRunner = Runner & {
+    close(): void;
+};
+/**
+ * An isolated runner: widget code runs in QuickJS (WebAssembly) inside a Bun child process this
+ * runner owns. The realm holds no host API, has a heap and stack limit and a soft deadline; a render
+ * that outlives the soft deadline plus 100 ms (one native call QuickJS cannot interrupt) is ended by
+ * killing the child, which the next render replaces. The host verifies the package hash and the
+ * library pins before anything is loaded, and validates every tree the child returns (law 2).
+ * Template packages run no author code and render on the host. `close()` kills the child.
+ *
+ * The child runs with the host's privileges and an empty environment; only QuickJS stands between
+ * widget code and the file system and network. Wrap it in an OS sandbox for defence in depth.
+ */
+export declare function quickjsRunner(options?: QuickJsRunnerOptions): Promise<QuickJsRunner>;

package/dist/index.js

@@ -0,0 +1,181 @@
+import { fileURLToPath } from "node:url";
+import { renderTemplatePackage } from "@arnilo/liveframe/runner-kit";
+import { hashMatches, prepare } from "./load.js";
+import { accept, failed, limitFailure } from "./result.js";
+/** The hard kill comes this long after the soft deadline: QuickJS cannot interrupt one native call. */
+const KILL_GRACE_MS = 100;
+const childEntry = fileURLToPath(new URL(`./child${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`, import.meta.url));
+function positive(name, value) {
+    if (!Number.isInteger(value) || value <= 0)
+        throw new RangeError(`${name} must be a positive integer`);
+    return value;
+}
+/**
+ * An isolated runner: widget code runs in QuickJS (WebAssembly) inside a Bun child process this
+ * runner owns. The realm holds no host API, has a heap and stack limit and a soft deadline; a render
+ * that outlives the soft deadline plus 100 ms (one native call QuickJS cannot interrupt) is ended by
+ * killing the child, which the next render replaces. The host verifies the package hash and the
+ * library pins before anything is loaded, and validates every tree the child returns (law 2).
+ * Template packages run no author code and render on the host. `close()` kills the child.
+ *
+ * The child runs with the host's privileges and an empty environment; only QuickJS stands between
+ * widget code and the file system and network. Wrap it in an OS sandbox for defence in depth.
+ */
+export async function quickjsRunner(options = {}) {
+    const memoryBytes = positive("memoryBytes", options.memoryBytes ?? 32 << 20);
+    const stackBytes = positive("stackBytes", options.stackBytes ?? 256 << 10);
+    const defaultTimeoutMs = positive("timeoutMs", options.timeoutMs ?? 250);
+    const maxRuntimes = positive("maxRuntimes", options.maxRuntimes ?? 16);
+    const reuse = options.reuse ?? "none";
+    let current;
+    let pending;
+    let nextId = 1;
+    let closed = false;
+    let chain = Promise.resolve();
+    function settle(answer) {
+        const active = pending;
+        pending = undefined;
+        active?.settle(answer);
+    }
+    /** Kills the child and forgets it; the next render starts a new one. */
+    function retire(child) {
+        if (current === child)
+            current = undefined;
+        child.proc.kill("SIGKILL");
+    }
+    function start() {
+        let ready;
+        let refuse;
+        const started = new Promise((resolve, reject) => {
+            ready = resolve;
+            refuse = reject;
+        });
+        const proc = Bun.spawn([process.execPath, childEntry, String(maxRuntimes)], {
+            env: {},
+            stdio: ["ignore", "ignore", "ignore"],
+            serialization: "json",
+            ipc(message) {
+                const reply = message;
+                if (current?.proc !== proc)
+                    return;
+                if (reply.type === "ready")
+                    ready();
+                else if (reply.type === "result" && pending?.id === reply.id)
+                    settle("json" in reply ? { json: reply.json } : { error: reply.error });
+                else if (reply.type === "result") {
+                    // An answer for a render nobody asked for: the child is not trusted any more.
+                    retire(child);
+                    settle({ error: "The sandbox answered a render it was not asked for" });
+                }
+            },
+            onExit(_, code) {
+                if (current?.proc !== proc)
+                    return;
+                current = undefined;
+                refuse(new Error(`The QuickJS child process exited before it was ready (code ${code})`));
+                settle({ error: `The QuickJS child process exited (code ${code})` });
+            },
+        });
+        // The child never keeps the host alive; its death with the host is `disconnect` in the child
+        // and, when the child is stuck in a native call, this hook.
+        proc.unref();
+        const child = { proc, ready: started };
+        current = child;
+        return child;
+    }
+    async function exchange(job, limits) {
+        let child = current ?? start();
+        try {
+            await child.ready;
+        }
+        catch (error) {
+            return { refused: error instanceof Error ? error.message : "The QuickJS child process did not start" };
+        }
+        // `closed` may have been set while the child started.
+        if (closed)
+            return { refused: "Runner closed" };
+        child = current ?? child;
+        const id = nextId++;
+        return new Promise((resolve) => {
+            const hard = setTimeout(() => {
+                retire(child);
+                settle({ killed: true });
+            }, limits.timeoutMs + KILL_GRACE_MS);
+            pending = {
+                id,
+                settle(answer) {
+                    clearTimeout(hard);
+                    resolve(answer);
+                },
+            };
+            child.proc.send({ type: "render", id, ...job, limits });
+        });
+    }
+    const killAtExit = () => current?.proc.kill("SIGKILL");
+    process.once("exit", killAtExit);
+    const first = start();
+    try {
+        await first.ready;
+    }
+    catch (error) {
+        process.off("exit", killAtExit);
+        throw error;
+    }
+    async function renderCode(pkg, inputs, runnerOptions) {
+        const linked = prepare(pkg, runnerOptions.libraries);
+        if (!linked.ok)
+            return linked;
+        const timeoutMs = runnerOptions.timeoutMs ?? defaultTimeoutMs;
+        const { catalog, capabilities, surfaceId, revision, limits } = runnerOptions;
+        let request;
+        try {
+            request = JSON.stringify({
+                inputs,
+                options: { catalog, capabilities, manifest: pkg.manifest, surfaceId, revision, ...(limits ? { limits } : {}) },
+            });
+        }
+        catch {
+            return failed("render-failed", "The render inputs must be JSON");
+        }
+        const answer = await exchange({
+            code: linked.value.code,
+            libraries: linked.value.libraries,
+            request,
+            ...(reuse === "package" ? { key: pkg.hash } : {}),
+        }, { memoryBytes, stackBytes, timeoutMs });
+        if ("refused" in answer)
+            return failed("render-failed", answer.refused);
+        if ("killed" in answer)
+            return failed("limit-exceeded", `Render stopped: timeout (killed after ${timeoutMs + KILL_GRACE_MS} ms)`);
+        if ("error" in answer)
+            return limitFailure(answer.error) ?? failed("render-failed", answer.error.slice(0, 500));
+        return accept(answer.json, { catalog, capabilities, manifest: pkg.manifest }, pkg.hash, limits ? { limits } : undefined);
+    }
+    return {
+        render(pkg, inputs, runnerOptions) {
+            if (closed)
+                return Promise.resolve(failed("render-failed", "Runner closed"));
+            if (!hashMatches(pkg))
+                return Promise.resolve(failed("hash-mismatch", "Package content does not match its hash", "/hash"));
+            if (pkg.template !== undefined)
+                return Promise.resolve(renderTemplate(pkg, pkg.template, inputs, runnerOptions, defaultTimeoutMs));
+            const run = chain.then(() => closed ? failed("render-failed", "Runner closed") : renderCode(pkg, inputs, runnerOptions));
+            chain = run.catch(() => undefined);
+            return run;
+        },
+        close() {
+            closed = true;
+            process.off("exit", killAtExit);
+            if (current)
+                retire(current);
+            settle({ error: "Runner closed" });
+        },
+    };
+}
+/** A template is data the library evaluates in bounded steps: no author code runs, so no sandbox is needed. */
+function renderTemplate(pkg, template, inputs, options, defaultTimeoutMs) {
+    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    const start = Date.now();
+    const result = renderTemplatePackage(template, inputs, { ...options, manifest: pkg.manifest });
+    return Date.now() - start > timeoutMs ? failed("limit-exceeded", `Render exceeded ${timeoutMs} ms`) : result;
+}

package/dist/load.d.ts

@@ -0,0 +1,11 @@
+import type { Result } from "@arnilo/liveframe";
+import { type WidgetPackage } from "@arnilo/liveframe/pack";
+/** What the sandbox is given: the package's linked code and its libraries' by specifier. */
+export type Linked = {
+    readonly code: string;
+    readonly libraries: Readonly<Record<string, string>>;
+};
+/** A package's hash against its content. The caller refuses a package that fails it before loading anything. */
+export declare function hashMatches(pkg: WidgetPackage): boolean;
+/** Links `pkg` and the libraries its pins name, or says why it cannot be loaded. */
+export declare function prepare(pkg: WidgetPackage, supplied: readonly WidgetPackage[] | undefined): Result<Linked>;

package/dist/load.js

@@ -0,0 +1,80 @@
+import { packageHash } from "@arnilo/liveframe/pack";
+import { linkPackage } from "@arnilo/liveframe/runner-kit";
+/** The bounds `verifyPackage` enforces on a package's library graph (spec §7.3). */
+const MAX_GRAPH_DEPTH = 4;
+const MAX_GRAPH_PACKAGES = 32;
+const keyOf = (id, version) => `${id}@${version}`;
+const specifierOf = (id, version) => `liveframe:lib/${keyOf(id, version)}`;
+function fail(kind, pointer, message) {
+    return { ok: false, errors: [{ kind, pointer, message }] };
+}
+/** A package's hash against its content. The caller refuses a package that fails it before loading anything. */
+export function hashMatches(pkg) {
+    try {
+        return packageHash(pkg) === pkg.hash;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The libraries `pkg` needs, dependencies first and each once: every pin must name a supplied library
+ * with that hash (`not-found`, `hash-mismatch`), each library's content is re-hashed, and the graph stays
+ * within the bounds `verifyPackage` enforces.
+ */
+function collect(pkg, supplied) {
+    if (!pkg.manifest.dependencies?.length)
+        return { ok: true, value: [] };
+    const byKey = new Map((supplied ?? []).map((lib) => [keyOf(lib.manifest.id, lib.manifest.version), lib]));
+    const ordered = new Map();
+    const visit = (owner, trail) => {
+        for (const [i, pin] of (owner.manifest.dependencies ?? []).entries()) {
+            const at = `/manifest/dependencies/${i}`;
+            const key = keyOf(pin.id, pin.version);
+            const lib = byKey.get(key);
+            if (!lib)
+                return fail("not-found", at, `No library package was supplied for ${key}`);
+            if (lib.hash !== pin.hash)
+                return fail("hash-mismatch", `${at}/hash`, `${key} does not match the pinned hash`);
+            if (trail.includes(key))
+                return fail("invalid-document", at, `Dependency cycle at ${key}`);
+            if (trail.length >= MAX_GRAPH_DEPTH)
+                return fail("limit-exceeded", at, `Expected dependencies at most ${MAX_GRAPH_DEPTH} deep`);
+            if (ordered.has(lib.hash))
+                continue;
+            if (!hashMatches(lib))
+                return fail("hash-mismatch", at, `${key} content does not match its hash`);
+            const inner = visit(lib, [...trail, key]);
+            if (!inner.ok)
+                return inner;
+            ordered.set(lib.hash, lib);
+            if (ordered.size > MAX_GRAPH_PACKAGES)
+                return fail("limit-exceeded", at, `Expected at most ${MAX_GRAPH_PACKAGES} libraries in all`);
+        }
+        return { ok: true, value: undefined };
+    };
+    const walked = visit(pkg, []);
+    return walked.ok ? { ok: true, value: [...ordered.values()] } : walked;
+}
+/** Sends the SDK specifiers to the kit module and leaves library specifiers for the sandbox's loader. */
+function link(code, at) {
+    const linked = linkPackage(code, (specifier) => specifier.startsWith("liveframe:lib/") ? specifier : "liveframe:kit");
+    return linked.ok ? linked : { ok: false, errors: linked.errors.map((error) => ({ ...error, pointer: at })) };
+}
+/** Links `pkg` and the libraries its pins name, or says why it cannot be loaded. */
+export function prepare(pkg, supplied) {
+    const libraries = collect(pkg, supplied);
+    if (!libraries.ok)
+        return libraries;
+    const code = link(pkg.code, "/code");
+    if (!code.ok)
+        return code;
+    const linkedLibraries = {};
+    for (const lib of libraries.value) {
+        const linked = link(lib.code, "/code");
+        if (!linked.ok)
+            return linked;
+        linkedLibraries[specifierOf(lib.manifest.id, lib.manifest.version)] = linked.value;
+    }
+    return { ok: true, value: { code: code.value, libraries: linkedLibraries } };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,36 @@
+/** The limits one render runs under inside the sandbox. */
+export type Limits = {
+    readonly memoryBytes: number;
+    readonly stackBytes: number;
+    /** The soft deadline: QuickJS's interrupt handler stops the render this long after it starts. */
+    readonly timeoutMs: number;
+};
+/** What the host asks the child to render. `libraries` maps `liveframe:lib/<id>@<version>` to linked code. */
+export type RenderRequest = {
+    readonly type: "render";
+    readonly id: number;
+    readonly code: string;
+    readonly libraries: Readonly<Record<string, string>>;
+    readonly request: string;
+    readonly limits: Limits;
+    /** Set when the runtime is kept between renders (`reuse: "package"`): the package hash. */
+    readonly key?: string;
+};
+export type ChildMessage = {
+    readonly type: "ready";
+} | {
+    readonly type: "result";
+    readonly id: number;
+    readonly json: string;
+} | {
+    readonly type: "result";
+    readonly id: number;
+    readonly error: string;
+};
+export type Reason = "timeout" | "memory" | "stack";
+/**
+ * Which limit a QuickJS message names. The engine reports a stopped render as an ordinary message
+ * (spike finding F7), so the host classifies by text: a widget that throws the same words only
+ * changes the kind of its own failure.
+ */
+export declare function limitOf(message: string): Reason | undefined;

package/dist/protocol.js

@@ -0,0 +1,14 @@
+/**
+ * Which limit a QuickJS message names. The engine reports a stopped render as an ordinary message
+ * (spike finding F7), so the host classifies by text: a widget that throws the same words only
+ * changes the kind of its own failure.
+ */
+export function limitOf(message) {
+    if (/\binterrupted\b/i.test(message))
+        return "timeout";
+    if (/stack overflow|maximum call stack/i.test(message))
+        return "stack";
+    if (/out of memory|string too long|too large|invalid array length/i.test(message))
+        return "memory";
+    return undefined;
+}

package/dist/result.d.ts

@@ -0,0 +1,18 @@
+import type { UiTree } from "@arnilo/liveframe";
+import { type Capabilities, type Catalog, type CompiledValidator, type LiveframeError, type Manifest, type Result } from "@arnilo/liveframe";
+export declare const failed: (kind: LiveframeError["kind"], message: string, pointer?: string) => Result<never>;
+/** The limit a stopped render hit, as the `limit-exceeded` it is reported as. */
+export declare function limitFailure(message: string): Result<never> | undefined;
+type Install = {
+    readonly catalog: Catalog;
+    readonly capabilities: Capabilities;
+    readonly manifest: Manifest;
+};
+export declare function validatorFor(install: Install, hash: string): CompiledValidator;
+/**
+ * The host's answer to the sandbox's one JSON string (law 2): the text is parsed here, a failure list is
+ * shape-checked and bounded, and a tree is validated by the host's own compiled validator before anyone
+ * sees it. Anything else is `render-failed`.
+ */
+export declare function accept(json: string, install: Install, hash: string, limits: Parameters<CompiledValidator["validateTree"]>[1]): Result<UiTree>;
+export {};

package/dist/result.js

@@ -0,0 +1,120 @@
+import { compileValidator, } from "@arnilo/liveframe";
+import { limitOf } from "./protocol.js";
+const KINDS = new Set([
+    "invalid-document",
+    "insufficient-contrast",
+    "unknown-name",
+    "incomplete-design-system",
+    "colour-outside-theme",
+    "catalog-mismatch",
+    "cyclic-extends",
+    "forbidden-import",
+    "transpile-failed",
+    "hash-mismatch",
+    "version-conflict",
+    "stale-patch",
+    "not-found",
+    "host-element",
+    "unknown-component",
+    "invalid-prop",
+    "invalid-children",
+    "missing-key",
+    "duplicate-key",
+    "undeclared-event",
+    "undeclared-action",
+    "function-prop",
+    "async-render",
+    "render-failed",
+    "limit-exceeded",
+]);
+/** One more than the validator's own bound: it appends a marker after the 20th error. */
+const MAX_ERRORS = 21;
+const MAX_TEXT = 1000;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const failed = (kind, message, pointer = "") => ({
+    ok: false,
+    errors: [{ kind, pointer, message }],
+});
+/** The limit a stopped render hit, as the `limit-exceeded` it is reported as. */
+export function limitFailure(message) {
+    const reason = limitOf(message);
+    return reason === undefined ? undefined : failed("limit-exceeded", `Render stopped: ${reason}`);
+}
+/** Failure messages from the sandbox are untrusted text: bounded, and no host paths can be in them. */
+function sanitized(errors) {
+    if (!Array.isArray(errors) || errors.length === 0 || errors.length > MAX_ERRORS)
+        return undefined;
+    const clean = [];
+    for (const error of errors) {
+        if (!isRecord(error) ||
+            typeof error.kind !== "string" ||
+            !KINDS.has(error.kind) ||
+            typeof error.pointer !== "string" ||
+            typeof error.message !== "string")
+            return undefined;
+        const limit = limitFailure(error.message);
+        if (limit)
+            return limit;
+        clean.push({
+            kind: error.kind,
+            pointer: error.pointer.slice(0, MAX_TEXT),
+            message: error.message.slice(0, MAX_TEXT),
+            ...(typeof error.expected === "string" ? { expected: error.expected.slice(0, MAX_TEXT) } : {}),
+            ...(typeof error.nodeId === "string" ? { nodeId: error.nodeId.slice(0, MAX_TEXT) } : {}),
+        });
+    }
+    return { ok: false, errors: clean };
+}
+/** Compiled validators per `(catalog, capabilities)` and verified package hash; the 64 most recent are kept. */
+const validators = new WeakMap();
+const MAX_VALIDATORS = 64;
+export function validatorFor(install, hash) {
+    let byCapabilities = validators.get(install.catalog);
+    if (!byCapabilities) {
+        byCapabilities = new WeakMap();
+        validators.set(install.catalog, byCapabilities);
+    }
+    let byHash = byCapabilities.get(install.capabilities);
+    if (!byHash) {
+        byHash = new Map();
+        byCapabilities.set(install.capabilities, byHash);
+    }
+    const known = byHash.get(hash);
+    if (known) {
+        byHash.delete(hash);
+        byHash.set(hash, known);
+        return known;
+    }
+    const validator = compileValidator(install);
+    byHash.set(hash, validator);
+    const oldest = byHash.keys().next();
+    if (byHash.size > MAX_VALIDATORS && !oldest.done)
+        byHash.delete(oldest.value);
+    return validator;
+}
+/**
+ * The host's answer to the sandbox's one JSON string (law 2): the text is parsed here, a failure list is
+ * shape-checked and bounded, and a tree is validated by the host's own compiled validator before anyone
+ * sees it. Anything else is `render-failed`.
+ */
+export function accept(json, install, hash, limits) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return failed("render-failed", "The sandbox returned a malformed result");
+    }
+    if (!isRecord(parsed))
+        return failed("render-failed", "The sandbox returned a malformed result");
+    if (parsed.ok === false)
+        return sanitized(parsed.errors) ?? failed("render-failed", "The sandbox returned a malformed result");
+    if (parsed.ok !== true || !("value" in parsed))
+        return failed("render-failed", "The sandbox returned a malformed result");
+    try {
+        return validatorFor(install, hash).validateTree(parsed.value, limits);
+    }
+    catch (error) {
+        return failed("render-failed", error instanceof Error ? error.message.slice(0, MAX_TEXT) : "Validation failed");
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,34 @@
+import type { Limits } from "./protocol.js";
+/** What one render needs inside the sandbox; the host linked `code` and the libraries already. */
+export type Job = {
+    readonly code: string;
+    readonly libraries: Readonly<Record<string, string>>;
+    readonly request: string;
+    readonly limits: Limits;
+    /** Keep the runtime under this key for the next render (`reuse: "package"`). */
+    readonly key?: string;
+};
+export type Outcome = {
+    readonly json: string;
+} | {
+    readonly error: string;
+};
+export type Engine = {
+    render(job: Job): Promise<Outcome>;
+    /** Runtimes kept for `reuse: "package"`. */
+    kept(): number;
+    /** Instances dropped because the engine threw to the host; a leaked handle shows up here. */
+    tainted(): number;
+    close(): void;
+};
+/**
+ * The QuickJS side of the runner. `wasm` is compiled once and shared; every sandbox gets its own
+ * instance of it, so no heap is shared between renders. `kit` is the runner-kit bundle's text.
+ *
+ * Rules (decision 2026-11-08-2310): `executePendingJobs()` is never called, so a hostile microtask
+ * loop never runs and a package whose top-level `await` does not settle is a failed render; a
+ * sandbox whose engine throws to the host, `dispose()` included, is dropped and never reused.
+ */
+export declare function createEngine(wasm: WebAssembly.Module, kit: string, options?: {
+    maxRuntimes?: number;
+}): Engine;

package/dist/runtime.js

@@ -0,0 +1,144 @@
+import releaseSyncModule from "@jitl/quickjs-wasmfile-release-sync";
+import { newQuickJSWASMModuleFromVariant, newVariant, shouldInterruptAfterDeadline, } from "quickjs-emscripten-core";
+/** The package types describe its CommonJS build; Bun loads the ESM build, whose default export is the variant. */
+const releaseSync = releaseSyncModule;
+/**
+ * The entry module: it holds the render function in the sandbox's own global. It is the only code that
+ * touches the request, as one JSON string in and one out; nothing of the host is exposed to the realm.
+ */
+const entry = `import { renderModule } from "liveframe:kit";
+import widget from "liveframe:pkg";
+globalThis.__render = (text) => {
+  const request = JSON.parse(text);
+  return JSON.stringify(renderModule(widget, request.inputs, request.options));
+};`;
+/**
+ * The QuickJS side of the runner. `wasm` is compiled once and shared; every sandbox gets its own
+ * instance of it, so no heap is shared between renders. `kit` is the runner-kit bundle's text.
+ *
+ * Rules (decision 2026-11-08-2310): `executePendingJobs()` is never called, so a hostile microtask
+ * loop never runs and a package whose top-level `await` does not settle is a failed render; a
+ * sandbox whose engine throws to the host, `dispose()` included, is dropped and never reused.
+ */
+export function createEngine(wasm, kit, options = {}) {
+    const variant = newVariant(releaseSync, { wasmModule: wasm });
+    const maxRuntimes = options.maxRuntimes ?? 16;
+    /** Kept sandboxes, least recently used first. */
+    const kept = new Map();
+    let taintedCount = 0;
+    function drop(sandbox) {
+        try {
+            sandbox.context.dispose();
+            sandbox.runtime.dispose();
+        }
+        catch {
+            taintedCount++;
+        }
+    }
+    async function open(job) {
+        const quickjs = await newQuickJSWASMModuleFromVariant(variant);
+        const runtime = quickjs.newRuntime();
+        runtime.setMemoryLimit(job.limits.memoryBytes);
+        runtime.setMaxStackSize(job.limits.stackBytes);
+        const sources = { ...job.libraries, "liveframe:kit": kit, "liveframe:pkg": job.code };
+        runtime.setModuleLoader((name) => sources[name] ?? { error: new Error("module not found") });
+        const context = runtime.newContext();
+        const sandbox = { runtime, context };
+        try {
+            runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + job.limits.timeoutMs));
+            const loaded = context.evalCode(entry, "entry.js", { type: "module" });
+            if (loaded.error) {
+                const message = describe(context, loaded.error);
+                drop(sandbox);
+                return message;
+            }
+            loaded.value.dispose();
+            const render = context.getProp(context.global, "__render");
+            const ready = context.typeof(render) === "function";
+            render.dispose();
+            if (!ready) {
+                drop(sandbox);
+                return "The package did not finish loading: top-level await is not supported";
+            }
+            return sandbox;
+        }
+        catch (error) {
+            taintedCount++;
+            return `QuickJS failed: ${describeHost(error)}`;
+        }
+    }
+    function call(sandbox, job) {
+        const { runtime, context } = sandbox;
+        runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + job.limits.timeoutMs));
+        const render = context.getProp(context.global, "__render");
+        const text = context.newString(job.request);
+        const result = context.callFunction(render, context.undefined, text);
+        text.dispose();
+        render.dispose();
+        if (result.error)
+            return { error: describe(context, result.error) };
+        const value = result.value;
+        const json = context.typeof(value) === "string" ? context.getString(value) : undefined;
+        value.dispose();
+        return json === undefined ? { error: "The render function did not return a string" } : { json };
+    }
+    return {
+        async render(job) {
+            let sandbox = job.key === undefined ? undefined : kept.get(job.key);
+            if (sandbox && job.key !== undefined) {
+                kept.delete(job.key);
+                kept.set(job.key, sandbox);
+            }
+            if (!sandbox) {
+                const opened = await open(job);
+                if (typeof opened === "string")
+                    return { error: opened };
+                sandbox = opened;
+                if (job.key !== undefined) {
+                    kept.set(job.key, sandbox);
+                    const oldest = kept.entries().next();
+                    if (kept.size > maxRuntimes && !oldest.done) {
+                        kept.delete(oldest.value[0]);
+                        drop(oldest.value[1]);
+                    }
+                }
+            }
+            let outcome;
+            try {
+                outcome = call(sandbox, job);
+            }
+            catch (error) {
+                taintedCount++;
+                outcome = { error: `QuickJS failed: ${describeHost(error)}` };
+                if (job.key !== undefined)
+                    kept.delete(job.key);
+                // The instance threw to the host: it is not disposed again and never reused.
+                return outcome;
+            }
+            // A kept runtime is only reused after a clean render: a stopped or failed one may hold half-built state.
+            if ("error" in outcome || job.key === undefined) {
+                if (job.key !== undefined)
+                    kept.delete(job.key);
+                drop(sandbox);
+            }
+            return outcome;
+        },
+        kept: () => kept.size,
+        tainted: () => taintedCount,
+        close() {
+            for (const sandbox of kept.values())
+                drop(sandbox);
+            kept.clear();
+        },
+    };
+}
+/** The message of an error value the engine produced, disposing the handle. */
+function describe(context, handle) {
+    const error = context.dump(handle);
+    handle.dispose();
+    const message = typeof error === "string" ? error : error?.message;
+    return String(message ?? "Render failed").slice(0, 500);
+}
+function describeHost(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 200);
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@arnilo/liveframe-runner-quickjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "An isolated Liveframe runner: widget code runs in QuickJS inside a child process the runner can kill, so a host gets a real isolation boundary without building a sandbox.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "author": "Niloy Rahman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashiqrniloy/liveframe.git",
+    "directory": "packages/runner-quickjs"
+  },
+  "homepage": "https://github.com/ashiqrniloy/liveframe#readme",
+  "bugs": {
+    "url": "https://github.com/ashiqrniloy/liveframe/issues"
+  },
+  "keywords": [
+    "liveframe",
+    "runner",
+    "sandbox",
+    "quickjs",
+    "bun"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/child.js"
+  ],
+  "peerDependencies": {
+    "@arnilo/liveframe": "~0.3.0"
+  },
+  "dependencies": {
+    "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
+    "quickjs-emscripten-core": "0.32.0"
+  }
+}