@pooriaarab/foxden 0.0.0-stage → 0.1.0

package/dist/den.d.ts

@@ -0,0 +1,77 @@
+import type { RunErrorKind, RunReply, RunRequest } from "./protocol.js";
+import { type ShellOptions, type ShellResult } from "./shell.js";
+export interface RuntimeInfo {
+    /** The adapter, for example "pyodide-iframe". */
+    kind: string;
+    /** How the runtime is cut off from the page, for example "manifest-sandbox". */
+    isolation: string;
+    loadMs: number;
+}
+/** A runtime adapter. foxden ships iframeRuntime; other adapters can plug in here. */
+export interface DenRuntime {
+    start(): Promise<RuntimeInfo>;
+    run(request: RunRequest): Promise<RunReply>;
+    close(): void;
+}
+/** Where a den keeps its files between page loads. */
+export interface DenStore {
+    load(name: string): Promise<Map<string, Uint8Array> | null>;
+    save(name: string, files: ReadonlyMap<string, Uint8Array>): Promise<void>;
+    remove(name: string): Promise<void>;
+}
+export interface OpenDenOptions {
+    /** 1-64 characters: ASCII letters, digits, - and _. */
+    name: string;
+    /** Makes a new runtime. The den calls it again after a timeout. */
+    runtime: () => DenRuntime;
+    /** Default: memoryStore(). Use idbStore() to keep files across page loads. */
+    store?: DenStore;
+    /** Start from these snapshot bytes instead of the stored files. */
+    snapshot?: Uint8Array;
+    /** The most bytes all files of the den can hold. Default 256 MiB. */
+    maxDenBytes?: number;
+    /** How long past timeoutMs to wait for the runtime before the den kills it. Default 5000. */
+    killGraceMs?: number;
+}
+export interface RunOptions {
+    /** Default 30000. */
+    timeoutMs?: number;
+    /** The most characters of stdout and of stderr to keep. Default 1 MiB. */
+    maxOutputBytes?: number;
+}
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    result: string | null;
+    error: {
+        kind: RunErrorKind;
+        message: string;
+    } | null;
+    truncated: boolean;
+    /** Paths that the run created, changed or deleted. */
+    files: string[];
+    durationMs: number;
+}
+export interface Den {
+    readonly name: string;
+    readonly info: RuntimeInfo;
+    run(code: string, options?: RunOptions): Promise<RunResult>;
+    sh(command: string, options?: ShellOptions): Promise<ShellResult>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    deleteFile(path: string): Promise<void>;
+    list(): Promise<{
+        path: string;
+        size: number;
+    }[]>;
+    snapshot(): Promise<Uint8Array>;
+    restore(snapshot: Uint8Array): Promise<void>;
+    fork(options: {
+        name: string;
+    }): Promise<Den>;
+    close(): Promise<void>;
+}
+/** A store that keeps files in memory only. */
+export declare function memoryStore(): DenStore;
+/** Open a den by name. It loads the stored files and starts the runtime. */
+export declare function openDen(options: OpenDenOptions): Promise<Den>;

package/dist/den.js

@@ -0,0 +1,227 @@
+// The den: a named set of files plus a runtime that runs code over them.
+// The den object owns the files. The runtime (by default a sandboxed iframe
+// with Pyodide) gets a copy for each run and sends back what changed, so a
+// runtime that hangs or crashes can be thrown away without losing files.
+import { DenError, DenLoadError, PathError } from "./errors.js";
+import { normalizePath } from "./paths.js";
+import { runShell } from "./shell.js";
+import { decodeSnapshot, encodeSnapshot } from "./snapshot.js";
+const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+const NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const open = new Set();
+const size = (files) => [...files.values()].reduce((sum, b) => sum + b.length, 0);
+// The one size check for every way files enter a den: writes, runs,
+// restore() and openDen({ snapshot }).
+function checkSize(name, files, max) {
+    if (size(files) > max)
+        throw new DenError(`The den ${name} would hold more than maxDenBytes (${max} bytes).`);
+}
+/** A store that keeps files in memory only. */
+export function memoryStore() {
+    const dens = new Map();
+    return {
+        load: async (name) => (dens.has(name) ? new Map(dens.get(name)) : null),
+        save: async (name, files) => void dens.set(name, new Map(files)),
+        remove: async (name) => void dens.delete(name),
+    };
+}
+/** Open a den by name. It loads the stored files and starts the runtime. */
+export async function openDen(options) {
+    const { name } = options;
+    if (typeof name !== "string" || !NAME.test(name))
+        throw new DenError(`The den name ${JSON.stringify(name)} must be 1-64 ASCII letters, digits, - or _.`);
+    if (open.has(name))
+        throw new DenError(`The den ${name} is already open in this page. Close it first.`);
+    open.add(name);
+    try {
+        const store = options.store ?? memoryStore();
+        let files = (await store.load(name)) ?? new Map();
+        if (options.snapshot) {
+            files = (await decodeSnapshot(options.snapshot)).files;
+            checkSize(name, files, options.maxDenBytes ?? DEFAULT_MAX_BYTES);
+            await store.save(name, files);
+        }
+        const runtime = options.runtime();
+        let info;
+        try {
+            info = await runtime.start();
+        }
+        catch (error) {
+            runtime.close();
+            throw new DenLoadError(`The den runtime did not start: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return new DenImpl(options, store, files, runtime, info);
+    }
+    catch (error) {
+        open.delete(name);
+        throw error;
+    }
+}
+class DenImpl {
+    options;
+    store;
+    name;
+    info;
+    #files;
+    #runtime;
+    #queue = Promise.resolve();
+    #closed = false;
+    #nextId = 1;
+    #maxBytes;
+    #graceMs;
+    constructor(options, store, files, runtime, info) {
+        this.options = options;
+        this.store = store;
+        this.name = options.name;
+        this.#files = files;
+        this.#runtime = runtime;
+        this.info = info;
+        this.#maxBytes = options.maxDenBytes ?? DEFAULT_MAX_BYTES;
+        this.#graceMs = options.killGraceMs ?? 5000;
+    }
+    #check() {
+        if (this.#closed)
+            throw new DenError(`The den ${this.name} is closed.`);
+    }
+    // Run fn after every earlier run and write, so changes apply in call order.
+    #enqueue(fn) {
+        if (this.#closed)
+            return Promise.reject(new DenError(`The den ${this.name} is closed.`));
+        const next = this.#queue.then(fn);
+        this.#queue = next.catch(() => { });
+        return next;
+    }
+    // Save first, then switch, so a failed save leaves the den as it was.
+    async #commit(files) {
+        checkSize(this.name, files, this.#maxBytes);
+        await this.store.save(this.name, files);
+        this.#files = files;
+    }
+    async #liveRuntime() {
+        if (this.#runtime)
+            return this.#runtime;
+        const runtime = this.options.runtime();
+        try {
+            this.info = await runtime.start();
+        }
+        catch (error) {
+            runtime.close();
+            throw new DenLoadError(`The den runtime did not restart: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.#runtime = runtime;
+        return runtime;
+    }
+    run(code, options = {}) {
+        return this.#enqueue(async () => {
+            if (typeof code !== "string")
+                throw new DenError("run() needs the code as a string.");
+            const timeoutMs = options.timeoutMs ?? 30_000;
+            const max = options.maxOutputBytes ?? 1024 * 1024;
+            const request = { id: this.#nextId++, code, files: [...this.#files], timeoutMs, maxOutputBytes: max };
+            const started = Date.now();
+            const runtime = await this.#liveRuntime();
+            let timer;
+            const late = new Promise((done) => {
+                timer = setTimeout(() => done(null), timeoutMs + this.#graceMs);
+            });
+            const reply = await Promise.race([runtime.run(request), late]).finally(() => clearTimeout(timer));
+            if (!reply) {
+                runtime.close();
+                this.#runtime = null;
+                await this.#liveRuntime().catch(() => { });
+                return this.#result({ error: { kind: "timeout", message: `The code ran for more than ${timeoutMs} ms and was stopped.` } }, max, started);
+            }
+            const keep = reply.error === null || reply.error.kind === "python";
+            const { files, changed, notes } = keep ? this.#apply(reply.files) : { files: this.#files, changed: [], notes: "" };
+            try {
+                if (changed.length > 0)
+                    await this.#commit(files);
+            }
+            catch (error) {
+                return this.#result({ ...reply, files: [], error: { kind: "storage", message: error.message } }, max, started);
+            }
+            return this.#result({ ...reply, stderr: reply.stderr + notes, files: changed }, max, started);
+        });
+    }
+    #apply(changes) {
+        const files = new Map(this.#files);
+        const changed = [];
+        let notes = "";
+        for (const [raw, body] of changes) {
+            let path;
+            try {
+                path = normalizePath(raw);
+            }
+            catch (error) {
+                notes += `foxden: ignored a file with a bad path: ${error.message}\n`;
+                continue;
+            }
+            if (body)
+                files.set(path, body);
+            else
+                files.delete(path);
+            changed.push(path);
+        }
+        return { files, changed, notes };
+    }
+    #result(r, max, started) {
+        const stdout = r.stdout ?? "";
+        const stderr = r.stderr ?? "";
+        return {
+            stdout: stdout.slice(0, max),
+            stderr: stderr.slice(0, max),
+            result: r.result ?? null,
+            error: r.error ?? null,
+            truncated: (r.truncated ?? false) || stdout.length > max || stderr.length > max,
+            files: r.files ?? [],
+            durationMs: r.durationMs ?? Date.now() - started,
+        };
+    }
+    async sh(command, options) {
+        this.#check();
+        return runShell(command, this.#files, options);
+    }
+    async writeFile(path, data) {
+        const p = normalizePath(path);
+        const body = typeof data === "string" ? new TextEncoder().encode(data) : data.slice();
+        return this.#enqueue(() => this.#commit(new Map(this.#files).set(p, body)));
+    }
+    async readFile(path) {
+        this.#check();
+        const p = normalizePath(path);
+        const body = this.#files.get(p);
+        if (!body)
+            throw new DenError(`${p}: No such file in den ${this.name}.`);
+        return body.slice();
+    }
+    async deleteFile(path) {
+        const p = normalizePath(path);
+        return this.#enqueue(async () => {
+            const files = new Map(this.#files);
+            files.delete(p);
+            await this.#commit(files);
+        });
+    }
+    async list() {
+        this.#check();
+        return [...this.#files].map(([path, body]) => ({ path, size: body.length })).toSorted((a, b) => (a.path < b.path ? -1 : 1));
+    }
+    async snapshot() {
+        this.#check();
+        return encodeSnapshot(this.name, this.#files);
+    }
+    restore(snapshot) {
+        return this.#enqueue(async () => this.#commit((await decodeSnapshot(snapshot)).files));
+    }
+    async fork({ name }) {
+        return openDen({ ...this.options, name, snapshot: await this.snapshot() });
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#runtime?.close();
+        this.#runtime = null;
+        open.delete(this.name);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+declare class FoxdenError extends Error {
+    constructor(name: string, message: string);
+}
+/** A path is not a file path inside /drop, /out or /work. */
+export declare class PathError extends FoxdenError {
+    constructor(message: string);
+}
+/** Snapshot bytes are corrupt, cut short, or forged. */
+export declare class SnapshotError extends FoxdenError {
+    constructor(message: string);
+}
+/** A den is used in a wrong way: a bad name, a name already open, or a closed den. */
+export declare class DenError extends FoxdenError {
+    constructor(message: string);
+}
+/** The runtime could not start, for example because Pyodide files are missing. */
+export declare class DenLoadError extends FoxdenError {
+    constructor(message: string);
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,32 @@
+// The error classes foxden throws. Each has a stable `name`, so callers can
+// check `error.name` across realms (for example an extension page and a tab).
+class FoxdenError extends Error {
+    constructor(name, message) {
+        super(message);
+        this.name = name;
+    }
+}
+/** A path is not a file path inside /drop, /out or /work. */
+export class PathError extends FoxdenError {
+    constructor(message) {
+        super("PathError", message);
+    }
+}
+/** Snapshot bytes are corrupt, cut short, or forged. */
+export class SnapshotError extends FoxdenError {
+    constructor(message) {
+        super("SnapshotError", message);
+    }
+}
+/** A den is used in a wrong way: a bad name, a name already open, or a closed den. */
+export class DenError extends FoxdenError {
+    constructor(message) {
+        super("DenError", message);
+    }
+}
+/** The runtime could not start, for example because Pyodide files are missing. */
+export class DenLoadError extends FoxdenError {
+    constructor(message) {
+        super("DenLoadError", message);
+    }
+}

package/dist/idb-store.d.ts

@@ -0,0 +1,3 @@
+import type { DenStore } from "./den.js";
+/** A store in the IndexedDB database `dbName` (default "foxden"). */
+export declare function idbStore(dbName?: string): DenStore;

package/dist/idb-store.js

@@ -0,0 +1,35 @@
+import { DenError } from "./errors.js";
+function request(r) {
+    return new Promise((resolve, reject) => {
+        r.addEventListener("success", () => resolve(r.result));
+        r.addEventListener("error", () => reject(r.error ?? new DenError("An IndexedDB request failed.")));
+    });
+}
+/** A store in the IndexedDB database `dbName` (default "foxden"). */
+export function idbStore(dbName = "foxden") {
+    let db;
+    const open = () => {
+        if (typeof indexedDB === "undefined")
+            return Promise.reject(new DenError("IndexedDB is not available here, so idbStore cannot keep files. Use memoryStore()."));
+        if (!db) {
+            const r = indexedDB.open(dbName, 1);
+            r.addEventListener("upgradeneeded", () => r.result.createObjectStore("dens", { keyPath: "name" }));
+            db = request(r);
+            db.catch(() => (db = undefined));
+        }
+        return db;
+    };
+    const tx = async (mode) => (await open()).transaction("dens", mode).objectStore("dens");
+    return {
+        async load(name) {
+            const record = (await request((await tx("readonly")).get(name)));
+            return record ? new Map(record.files) : null;
+        },
+        async save(name, files) {
+            await request((await tx("readwrite")).put({ name, files: [...files] }));
+        },
+        async remove(name) {
+            await request((await tx("readwrite")).delete(name));
+        },
+    };
+}

package/dist/iframe-runtime.d.ts

@@ -0,0 +1,20 @@
+import type { DenRuntime } from "./den.js";
+export interface IframeRuntimeOptions {
+    /** URL of den.html (from @pooriaarab/foxden/dist/den/). */
+    denUrl: string | URL;
+    /** URL of a folder with pyodide.asm.wasm, python_stdlib.zip and pyodide-lock.json. */
+    pyodideUrl: string | URL;
+    /**
+     * "manifest-sandbox": a plain iframe of a page in the manifest `sandbox` key (Firefox 154+).
+     * "iframe-sandbox": an iframe with `sandbox="allow-scripts"` (websites, Firefox 153).
+     * "auto" (default): manifest-sandbox when the extension lists den.html there, else iframe-sandbox.
+     */
+    isolation?: Isolation | "auto";
+    /** Default 60000. */
+    loadTimeoutMs?: number;
+    /** Where to put the hidden iframe. Default document.body. */
+    container?: HTMLElement;
+}
+export type Isolation = "manifest-sandbox" | "iframe-sandbox";
+/** A runtime factory for openDen: Pyodide in a sandboxed iframe with no network. */
+export declare function iframeRuntime(options: IframeRuntimeOptions): () => DenRuntime;

package/dist/iframe-runtime.js

@@ -0,0 +1,109 @@
+import { parseDenMessage } from "./protocol.js";
+const cache = new Map();
+async function get(base, name) {
+    const response = await fetch(new URL(name, base));
+    if (!response.ok)
+        throw new Error(`${name}: HTTP ${response.status}`);
+    return response;
+}
+function assets(base) {
+    let pending = cache.get(base.href);
+    if (!pending) {
+        pending = Promise.all([get(base, "pyodide.asm.wasm"), get(base, "python_stdlib.zip"), get(base, "pyodide-lock.json")]).then(async ([wasm, stdlib, lock]) => ({ wasm: await wasm.arrayBuffer(), stdlib: await stdlib.arrayBuffer(), lock: (await lock.json()) }));
+        pending.catch(() => cache.delete(base.href));
+        cache.set(base.href, pending);
+    }
+    return pending;
+}
+function inManifestSandbox(den) {
+    if (location.protocol !== "moz-extension:" || den.origin !== location.origin)
+        return false;
+    const g = globalThis;
+    const pages = g.browser?.runtime?.getManifest?.().sandbox?.pages;
+    return Array.isArray(pages) && pages.some((p) => typeof p === "string" && new URL(p, `${location.origin}/`).pathname === den.pathname);
+}
+function within(promise, ms, message) {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+    });
+    return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+class IframeRuntime {
+    options;
+    #frame = null;
+    #port = null;
+    #pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        const den = new URL(this.options.denUrl, location.href);
+        const mode = this.options.isolation ?? "auto";
+        const first = mode === "auto" ? (inManifestSandbox(den) ? "manifest-sandbox" : "iframe-sandbox") : mode;
+        try {
+            return await this.#open(den, first);
+        }
+        catch (error) {
+            // Firefox 153 ignores the manifest sandbox key, so the den page refuses
+            // to start there. In auto mode, try again with the sandbox attribute.
+            if (mode !== "auto" || first !== "manifest-sandbox" || !String(error.message).startsWith("not isolated"))
+                throw error;
+            this.close();
+            return this.#open(den, "iframe-sandbox");
+        }
+    }
+    async #open(den, isolation) {
+        const timeout = this.options.loadTimeoutMs ?? 60_000;
+        const started = performance.now();
+        const files = await assets(new URL(this.options.pyodideUrl, location.href));
+        const frame = document.createElement("iframe");
+        this.#frame = frame;
+        if (isolation === "iframe-sandbox")
+            frame.setAttribute("sandbox", "allow-scripts");
+        frame.hidden = true;
+        frame.title = "foxden sandbox";
+        frame.src = den.href;
+        const loaded = new Promise((done) => frame.addEventListener("load", done, { once: true }));
+        (this.options.container ?? document.body).append(frame);
+        const { port1, port2 } = new MessageChannel();
+        this.#port = port1;
+        const ready = new Promise((resolve, reject) => {
+            port1.addEventListener("message", (e) => {
+                const m = parseDenMessage(e.data);
+                if (m?.t === "ready")
+                    resolve(m);
+                else if (m?.t === "load-error")
+                    reject(new Error(m.message));
+                else if (m?.t === "reply") {
+                    this.#pending.get(m.reply.id)?.(m.reply);
+                    this.#pending.delete(m.reply.id);
+                }
+            });
+            port1.start();
+        });
+        await within(loaded, timeout, `${den.href} did not load in ${timeout} ms.`);
+        frame.contentWindow?.postMessage({ t: "init", v: 1, assets: files }, "*", [port2]);
+        const m = await within(ready, timeout, `Pyodide did not load in ${timeout} ms.`);
+        if (m.origin !== "null" || m.extensionApi)
+            throw new Error(`not isolated: the den page has origin ${m.origin}.`);
+        return { kind: "pyodide-iframe", isolation, loadMs: Math.round(performance.now() - started) };
+    }
+    run(request) {
+        return new Promise((done) => {
+            this.#pending.set(request.id, done);
+            this.#port?.postMessage({ t: "run", v: 1, request });
+        });
+    }
+    close() {
+        this.#port?.close();
+        this.#frame?.remove();
+        this.#port = null;
+        this.#frame = null;
+        this.#pending.clear();
+    }
+}
+/** A runtime factory for openDen: Pyodide in a sandboxed iframe with no network. */
+export function iframeRuntime(options) {
+    return () => new IframeRuntime(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type Den, type DenRuntime, type DenStore, memoryStore, openDen, type OpenDenOptions, type RunOptions, type RunResult, type RuntimeInfo } from "./den.js";
+export { DenError, DenLoadError, PathError, SnapshotError } from "./errors.js";
+export { DEN_FOLDERS, normalizePath } from "./paths.js";
+export { type DenMessage, type FileChanges, type HostMessage, parseDenMessage, parseHostMessage, PROTOCOL_VERSION, type RunReply, type RunRequest } from "./protocol.js";
+export { runShell, type ShellOptions, type ShellResult } from "./shell.js";
+export { decodeSnapshot, encodeSnapshot } from "./snapshot.js";
+export { type IframeRuntimeOptions, type Isolation, iframeRuntime } from "./iframe-runtime.js";
+export { idbStore } from "./idb-store.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// The public API of foxden.
+export { memoryStore, openDen } from "./den.js";
+export { DenError, DenLoadError, PathError, SnapshotError } from "./errors.js";
+export { DEN_FOLDERS, normalizePath } from "./paths.js";
+export { parseDenMessage, parseHostMessage, PROTOCOL_VERSION } from "./protocol.js";
+export { runShell } from "./shell.js";
+export { decodeSnapshot, encodeSnapshot } from "./snapshot.js";
+export { iframeRuntime } from "./iframe-runtime.js";
+export { idbStore } from "./idb-store.js";

package/dist/paths.d.ts

@@ -0,0 +1,8 @@
+/** The folders a den can hold files in. */
+export declare const DEN_FOLDERS: readonly ["/drop", "/out", "/work"];
+/**
+ * Return the one canonical spelling of a den file path, or throw PathError.
+ * Repeated slashes collapse. `.`, `..`, NUL and backslash are refused, so a
+ * path can never leave its folder.
+ */
+export declare function normalizePath(path: unknown): string;

package/dist/paths.js

@@ -0,0 +1,33 @@
+// Path rules for den files. Every path that crosses a trust boundary (user,
+// sandbox, snapshot) goes through normalizePath before foxden uses it.
+import { PathError } from "./errors.js";
+/** The folders a den can hold files in. */
+export const DEN_FOLDERS = ["/drop", "/out", "/work"];
+const MAX_PATH = 1024;
+/**
+ * Return the one canonical spelling of a den file path, or throw PathError.
+ * Repeated slashes collapse. `.`, `..`, NUL and backslash are refused, so a
+ * path can never leave its folder.
+ */
+export function normalizePath(path) {
+    if (typeof path !== "string")
+        throw new PathError(`A path must be a string, not ${typeof path}.`);
+    if (path.length > MAX_PATH)
+        throw new PathError(`A path must be ${MAX_PATH} characters or fewer.`);
+    if (path.includes("\0") || path.includes("\\"))
+        throw new PathError(`The path ${JSON.stringify(path)} holds a NUL byte or a backslash.`);
+    if (!path.startsWith("/"))
+        throw new PathError(`The path ${JSON.stringify(path)} must start with /drop/, /out/ or /work/.`);
+    if (path.endsWith("/"))
+        throw new PathError(`The path ${JSON.stringify(path)} names a folder, not a file.`);
+    const parts = path.split("/").filter((part) => part !== "");
+    if (parts.some((part) => part === "." || part === ".."))
+        throw new PathError(`The path ${JSON.stringify(path)} holds a . or .. segment.`);
+    const folder = `/${parts[0] ?? ""}`;
+    if (!DEN_FOLDERS.includes(folder)) {
+        throw new PathError(`The path ${JSON.stringify(path)} must start with /drop/, /out/ or /work/.`);
+    }
+    if (parts.length < 2)
+        throw new PathError(`The path ${JSON.stringify(path)} names a folder, not a file.`);
+    return `/${parts.join("/")}`;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,52 @@
+export declare const PROTOCOL_VERSION = 1;
+/** File changes from a run: bytes for a new or changed file, null for a deleted one. */
+export type FileChanges = [path: string, body: Uint8Array | null][];
+export type RunErrorKind = "python" | "timeout" | "crashed" | "storage";
+export interface RunRequest {
+    id: number;
+    code: string;
+    /** Every den file, so the sandbox needs no state of its own. */
+    files: [path: string, body: Uint8Array][];
+    timeoutMs: number;
+    maxOutputBytes: number;
+}
+export interface RunReply {
+    id: number;
+    stdout: string;
+    stderr: string;
+    /** `repr()` of the last expression, or null. */
+    result: string | null;
+    error: {
+        kind: RunErrorKind;
+        message: string;
+    } | null;
+    truncated: boolean;
+    files: FileChanges;
+    durationMs: number;
+}
+/** Sandbox page to host. */
+export type DenMessage = {
+    t: "ready";
+    v: 1;
+    origin: string;
+    extensionApi: boolean;
+    loadMs: number;
+} | {
+    t: "load-error";
+    v: 1;
+    message: string;
+} | {
+    t: "reply";
+    v: 1;
+    reply: RunReply;
+};
+/** Host to sandbox page, over the MessagePort. */
+export interface HostMessage {
+    t: "run";
+    v: 1;
+    request: RunRequest;
+}
+/** Parse a message from the sandbox page. Returns null for anything unexpected. */
+export declare function parseDenMessage(data: unknown): DenMessage | null;
+/** Parse a message from the host. Returns null for anything unexpected. */
+export declare function parseHostMessage(data: unknown): HostMessage | null;