JS half of Edge Python: hosts compiler.wasm in a Web Worker, resolves and registers .py / .wasm modules, dispatches native calls. Drive it programmatically with createWorker, or declaratively with the <edge-python> HTML element.

Requires Deno v2 and Playwright's Chromium (installed on first run).

deno lint runtime/ # lint
deno run -A npm:playwright install --with-deps chromium # install Chromium (once)
deno test --allow-all runtime/tests/runtime.test.js # run tests

No install, the official CDN serves both the runtime and matching compiler.wasm:

import { createWorker } from "https://cdn.edgepython.com/runtime/src/index.js";
// Local checkout: import { createWorker } from "../../runtime/src/index.js";

const worker = await createWorker({
    wasmUrl: "https://cdn.edgepython.com/compiler.wasm",
    integrity: true, // default: IDB + lockfile CAS
    imports: { dom: "./dom.wasm" }, // bare-name shortcut, optional
    loaders: [], // opt-in module loaders, optional
});

worker.onOutput((line) => console.log(line));

const { out, ms } = await worker.run(`
    from dom import query, set_text
    set_text(query("#app"), "hello")
`);

worker.dispose();

Declarative alternative to createWorker: include the script, drop a tag, and a .py file runs. The element wraps createWorker on the page's main thread.

<script type="module" src="https://cdn.edgepython.com/runtime/src/element.js"></script>
<edge-python entry="./app/main.py" packages="./app/packages.json"></edge-python>

Importing element.js auto-registers the tag. On connect, the element reads its attributes and packages.json, spawns the worker, runs entry if present, then fires a ready event. compiler.wasm loads from the CDN automatically. Modules load lazily: only what a run actually imports is fetched, host libraries included.

The element keeps its worker on el.worker, so you can drive the same VM from JS after ready fires; run(src, opts?) and onOutput(cb) proxy the worker.

const el = document.querySelector("edge-python");
await new Promise((r) => el.addEventListener("ready", r, { once: true }));
el.onOutput((line) => console.log(line));
await el.run("print(1 + 1)"); // 2

Where customElements is absent (Cloudflare Workers, Deno, SSR), append ?setElement=false to the script URL to skip the auto-call, then register manually with the exported defineElement(tag = "edge-python"), where custom tags must contain a hyphen:

import { defineElement } from "https://cdn.edgepython.com/runtime/src/element.js?setElement=false";
defineElement("edge-py");

Host libraries (DOM, etc.) are plain-JS modules whose handlers run on the page's main thread, because they touch document / window, which the worker can't reach. Declare them in the host field of packages.json:

{
  "host": {
    "dom": "/host/dom/src/index.js"
  }
}

Each host entry maps a name to an ESM URL (resolved against the packages.json location). The element passes these to createWorker as hostModules; the module is import()ed lazily the first time a run imports that name, never at connect, so an unused host library is never fetched. The ESM exports its handler factory under the host name (or as default), so export const dom answers from dom import ...:

# app/main.py
from dom import query, set_text
set_text(query("#app"), "hello")

The element reads the same packages.json for the standard imports field too: those bare-name .py / .wasm modules are passed to createWorker's imports. So one manifest drives both directions, host to the main thread and imports to the worker. Together they are the declarative form of the mainThreadModules and imports options.

Spawns a Web Worker, loads compiler.wasm inside it, returns a proxy.

The returned object exposes:

A loader is a .js file with a default export:

export default {
    /** Inspect the compiled module; return true if this loader handles it. */
    match(module) {
        const names = WebAssembly.Module.exports(module).map(e => e.name);
        return names.includes('my_marker_export');
    },

    /** Load the module and return its callable surface. */
    async load(module, ctx) {
        /**
         * ctx.compilerExports, compiler.wasm instance exports (wasm_alloc, host_edge_*, etc.)
         * ctx.rt, handle codec helpers (decodeStr, encodeInt, ...)
         * ctx.fetchedSources, Map of already-fetched spec -> bytes
         * ctx.loaders, full loader list (in order)
         */

        return {
            kind: 'wasmpdk' | 'capability',
            names: ['fn1', 'fn2', ...],
            fns: [fn1Impl, fn2Impl, ...],
        };
    },
};

Two valid kind values:

• wasmpdk, each fn is a wasm export with signature (g_argv, argc, g_out) -> i32 reading from its own linear memory. Each fn must be annotated with __edge_alloc and __edge_memory (the built-in loader does this automatically). The dispatcher stages argv in guest memory and copies the result handle back.

• capability, each fn is a plain JS function (handles: number[]) => number taking u32 handles in compiler's memory and returning a u32 result handle. The dispatcher calls it directly without staging.

The built-in Path A wasm-pdk loader is always tried last as fallback; custom loaders run first in order.

Engine runs in a Web Worker, so handlers can't reach document / window. mainThreadModules: a pure-JS module declares its handlers, the runtime synthesises the native registration so Python can from <name> import ..., each call defers to main transparently. Python sees a regular synchronous call.

Factory (ctx) => handlers or {name: handler}. Factory form receives { pushEvent } so async callbacks (events, observers, file reads) can wake a paused receive().

const dom = ({ pushEvent }) => {
    const nodes = [];
    const alloc = (n) => { nodes.push(n); return nodes.length - 1; };
    return {
        query: (sel) => alloc(document.querySelector(sel)),
        set_text: (h, txt) => { nodes[h].textContent = txt; },
        // async handlers call pushEvent(jsonDetail) to wake a paused receive()
    };
};

const worker = await createWorker({ wasmUrl: "...", mainThreadModules: { dom } });

Supported tags: None, bool, int (i64, range-limited by JS Number), float, string bytes. Opaque references (DOM nodes, files, observers) -> integer IDs in a main-thread registry (the alloc / node pattern).

Per-call overhead: one postMessage round-trip (around 0.1 to 0.4 ms in modern browsers). Fine for UI-rate workloads. For tight per-frame loops over thousands of fine-grained ops, prefer a Worker-side capability (Path A .wasm).

When the runtime is cross-origin (page on demo.edgepython.com, runtime served from cdn.edgepython.com/runtime/), Chromium rejects new Worker(crossOriginUrl) even with type: 'module'. createWorker spawns from a same-origin Blob URL that dynamically import()s the cross-origin module. Same-origin imports use the direct path; createWorker auto-selects from import.meta.url. The Blob bootstrap buffers any postMessage arriving before worker.js installs its handler.

load runs once per Worker; run can be called many times. compiler.wasm is compiled once at load; a fresh instance is created per run so VM state cannot leak. Resolution is lazy: the compiler classifies each import and only the modules a run actually uses get fetched. Bare names resolve against the manifest chain (built-in defaults < user packages.json); manifests are resolution tables, not download lists, so a declared-but-unused package is never downloaded. Module bytes (.py / .wasm / packages.json) are cached across runs in the same Worker, prefetch skips fetched specs, 404'd manifests are remembered. Use clearCache() to drop both caches.

A spec the prefetch can't fetch or register (wrong scheme, a .wasm served as HTML, a malformed binary) aborts the run before it starts with a clear error, with an https:// hint for http:// or schemeless URL specs, instead of letting the VM fail later with not registered.

MIT OR Apache-2.0