el/engrams/el-wasm/js/runtime.js

// Engram-lang WASM runtime loader
// Include this in any web app to run .el programs natively in the browser.
//
// Usage:
//   import { initRuntime, runElc, evalSource } from '/js/runtime.js';
//
//   await initRuntime();
//   const result = await runElc('/programs/main.elc');

let wasmModule = null;

/**
 * Initialise the el WASM runtime. Safe to call multiple times —
 * subsequent calls return the already-loaded module immediately.
 *
 * @param {string} wasmUrl - Path to the .wasm file (default: /pkg/el_wasm_bg.wasm)
 * @returns {Promise<object>} The loaded runtime API
 */
export async function initRuntime(wasmUrl = '/pkg/el_wasm_bg.wasm') {
    if (wasmModule) return wasmModule;

    const { default: init, compile_source, load_and_run, eval: elEval, version } =
        await import('/pkg/el_wasm.js');

    await init(wasmUrl);

    wasmModule = { compile_source, load_and_run, eval: elEval, version };
    console.log(`el WASM runtime v${version()} loaded`);
    return wasmModule;
}

/**
 * Fetch a pre-compiled .elc file from the server and execute it.
 *
 * The browser caches the .elc file automatically based on Cache-Control
 * headers set by the server. New bytecode is available immediately on the
 * next fetch — no app-store review required.
 *
 * @param {string} elcUrl - URL of the .elc bytecode file
 * @returns {Promise<any>} The JSON-deserialised result value
 */
export async function runElc(elcUrl) {
    const rt = await initRuntime();
    const response = await fetch(elcUrl);
    if (!response.ok) throw new Error(`Failed to fetch ${elcUrl}: ${response.status}`);
    const bytes = new Uint8Array(await response.arrayBuffer());
    return JSON.parse(rt.load_and_run(bytes));
}

/**
 * Compile el source and run it immediately. Useful for REPL and
 * developer-mode execution where source is available at runtime.
 *
 * @param {string} source - Engram-lang source code
 * @returns {Promise<any>} The JSON-deserialised result value
 */
export async function evalSource(source) {
    const rt = await initRuntime();
    return JSON.parse(rt.eval(source));
}

/**
 * Compile el source to bytecode bytes without running it.
 * The returned Uint8Array can be stored or uploaded as a .elc file.
 *
 * @param {string} source - Engram-lang source code
 * @returns {Promise<Uint8Array>} Compiled bytecode bytes
 */
export async function compileSource(source) {
    const rt = await initRuntime();
    return rt.compile_source(source);
}