@pieceful/ravel-js-live 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Taylor
+
+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

@@ -0,0 +1,91 @@
+# @pieceful/ravel-js-live
+
+The QuickJS/WebAssembly execution provider for [Ravel](https://github.com/jostylr/ravel) 0.2.
+It analyzes ordinary `js` and `javascript` chunks marked `.run`, resolves their
+declared `ch("...")` and `load("...")` inputs through Ravel core, and evaluates
+them without Node, filesystem, network, console, or output capabilities.
+
+```sh
+npm install @pieceful/ravel-core @pieceful/ravel-js-live
+```
+
+Register the provider with core after ordinary Ravel composition:
+
+```js
+import { executeLiveProgram } from "@pieceful/ravel-core";
+import { javascriptLiveProvider } from "@pieceful/ravel-js-live";
+
+const result = await executeLiveProgram(program, {
+  providers: [javascriptLiveProvider],
+  resources: { "cool.csv": "name,value\nalpha,1\n" },
+});
+```
+
+Live modules must end with exactly one `export default`. The value may be any
+JSON-compatible value, including an empty string, empty collection, `false`,
+`0`, or `null`. Inputs are copied and deeply frozen before evaluation.
+
+QuickJS runs in a persistent Node or browser worker so its compiled Wasm module
+stays warm. Every evaluation still creates a fresh QuickJS runtime. Timeout,
+cancellation, worker failure, or an unresponsive interrupt terminates the
+outer worker; the provider creates a replacement for a later run. Call
+`provider.dispose()` when a provider is no longer needed.
+
+## Approved modules
+
+Live code cannot resolve npm packages, paths, or URLs. A host may instead
+register immutable, QuickJS-compatible ES module source:
+
+```js
+import { createJavaScriptLiveProvider } from "@pieceful/ravel-js-live";
+
+const provider = createJavaScriptLiveProvider({
+  modules: {
+    "@ravel/csv": `
+      export const parseCsv = (text) =>
+        text.trim().split(/\\r?\\n/).map((line) => line.split(","));
+    `,
+  },
+});
+```
+
+The live block can then use a normal static import:
+
+```js
+import { parseCsv } from "@ravel/csv";
+export default parseCsv(load("cool.csv"));
+```
+
+For an npm CSV parser, the host must first bundle its pure-JavaScript dependency
+graph into one ESM source string and register that string under an approved
+specifier. Native addons, Node built-ins, dynamic imports, package resolution,
+and filesystem loading remain unavailable.
+
+Node hosts can bundle explicitly allowlisted, already-installed package exports
+without executing them:
+
+```js
+import { prepareJavaScriptModules } from "@pieceful/ravel-js-live/node";
+
+const modules = await prepareJavaScriptModules(
+  [{ specifier: "@ravel/csv", from: "csv-parse/browser/esm/sync" }],
+  { rootDirectory: projectDirectory },
+);
+```
+
+The `node` subpath is deliberately separate from the browser-safe provider
+entry. Ravel does not install packages or run package lifecycle scripts.
+
+Browser builds should emit `@pieceful/ravel-js-live/worker-browser` as a
+separate module-worker entry and place the release-sync
+`emscripten-module.wasm` asset beside that worker bundle. Supply the emitted
+worker through `workerFactory` when a bundler cannot preserve the package's
+default `new URL(..., import.meta.url)` worker location.
+
+The worker boundary, memory/stack/time/output limits, immutable data boundary,
+and closed module registry provide layered isolation. Pending-job quotas,
+broader adversarial review, transform modules, and a virtual filesystem are
+deferred to 0.3, so this package does not claim a complete hostile-code
+sandbox.
+
+MIT © James Taylor

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@pieceful/ravel-js-live",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "QuickJS/Wasm live JavaScript provider for Ravel.",
+  "license": "MIT",
+  "author": "James Taylor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/js-live"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
+  "homepage": "https://ravel.jostylr.com/",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "quickjs",
+    "webassembly",
+    "sandbox",
+    "live-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./node": {
+      "types": "./src/node.d.ts",
+      "default": "./src/node.js"
+    },
+    "./worker-browser": {
+      "types": "./src/worker-browser.d.ts",
+      "default": "./src/worker-browser.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
+    "acorn": "8.17.0",
+    "esbuild": "0.28.1",
+    "quickjs-emscripten": "0.32.0"
+  },
+  "peerDependencies": {
+    "@pieceful/ravel-core": "0.2.0"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,219 @@
+import { parse } from "acorn";
+
+const reservedBindings = new Set(["ch", "load"]);
+const dynamicCodeBindings = new Set(["eval", "Function"]);
+
+export const diagnostic = (code, message, source) => ({
+  code,
+  severity: "error",
+  message,
+  source
+});
+
+const advance = (start, text) => {
+  let line = start.line;
+  let column = start.column;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (character === "\n") {
+      line += 1;
+      column = 0;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column, offset: start.offset + text.length };
+};
+
+const sourceAt = (sourceLocation, source, start, end = start) => ({
+  uri: sourceLocation.uri,
+  range: {
+    start: advance(sourceLocation.range.start, source.slice(0, start)),
+    end: advance(sourceLocation.range.start, source.slice(0, end))
+  }
+});
+
+const bindingNames = (pattern, names = []) => {
+  if (!pattern || typeof pattern !== "object") return names;
+  if (pattern.type === "Identifier") names.push(pattern.name);
+  else if (pattern.type === "RestElement") bindingNames(pattern.argument, names);
+  else if (pattern.type === "AssignmentPattern") bindingNames(pattern.left, names);
+  else if (pattern.type === "ArrayPattern") {
+    for (const element of pattern.elements) bindingNames(element, names);
+  } else if (pattern.type === "ObjectPattern") {
+    for (const property of pattern.properties) {
+      bindingNames(property.type === "RestElement" ? property.argument : property.value, names);
+    }
+  }
+  return names;
+};
+
+const walk = (node, visit) => {
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  visit(node);
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "start" || key === "end" || key === "loc") continue;
+    if (Array.isArray(value)) {
+      for (const child of value) walk(child, visit);
+    } else {
+      walk(value, visit);
+    }
+  }
+};
+
+export const analyzeJavaScript = ({ source, sourceLocation, availableModules }) => {
+  const diagnostics = [];
+  let program;
+  try {
+    program = parse(source, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      locations: true
+    });
+  } catch (error) {
+    const start = Number.isInteger(error?.pos) ? error.pos : 0;
+    diagnostics.push(diagnostic(
+      "RJL100",
+      "JavaScript syntax error: " + (error?.message ?? String(error)),
+      sourceAt(sourceLocation, source, start, start + 1)
+    ));
+    return { version: 1, dependencies: [], resources: [], modules: [], diagnostics };
+  }
+
+  const defaults = program.body.filter((node) => node.type === "ExportDefaultDeclaration");
+  if (defaults.length !== 1) {
+    diagnostics.push(diagnostic(
+      "RJL101",
+      "A live JavaScript block must contain exactly one export default.",
+      sourceLocation
+    ));
+  } else if (program.body.at(-1) !== defaults[0]) {
+    diagnostics.push(diagnostic(
+      "RJL102",
+      "export default must be the final top-level statement.",
+      sourceAt(sourceLocation, source, defaults[0].start, defaults[0].end)
+    ));
+  }
+
+  const dependencies = new Map();
+  const resources = new Map();
+  const modules = new Map();
+  const reportedBindings = new Set();
+  const reportedDynamicCode = new Set();
+  const reportBinding = (name, node) => {
+    if (reservedBindings.has(name) || name.startsWith("__ravel")) {
+      const key = name + ":" + node.start + ":" + node.end;
+      if (reportedBindings.has(key)) return;
+      reportedBindings.add(key);
+      diagnostics.push(diagnostic(
+        "RJL103",
+        "Live JavaScript cannot declare, assign, or access the reserved binding " + name + ".",
+        sourceAt(sourceLocation, source, node.start, node.end)
+      ));
+    }
+  };
+  const reportDynamicCode = (node) => {
+    const key = node.start + ":" + node.end;
+    if (reportedDynamicCode.has(key)) return;
+    reportedDynamicCode.add(key);
+    diagnostics.push(diagnostic(
+      "RJL106",
+      "Dynamic code generation is unavailable in live JavaScript.",
+      sourceAt(sourceLocation, source, node.start, node.end)
+    ));
+  };
+
+  walk(program, (node) => {
+    if (node.type === "Identifier" && node.name.startsWith("__ravel")) {
+      reportBinding(node.name, node);
+    }
+    if (node.type === "Identifier" && dynamicCodeBindings.has(node.name)) {
+      reportDynamicCode(node);
+    }
+    if (node.type === "MemberExpression" && node.computed &&
+        node.property.type === "Literal" && dynamicCodeBindings.has(node.property.value)) {
+      reportDynamicCode(node);
+    }
+    if (node.type === "ImportDeclaration") {
+      const specifier = node.source.value;
+      const entry = {
+        specifier,
+        source: sourceAt(sourceLocation, source, node.source.start, node.source.end)
+      };
+      modules.set(specifier, entry);
+      if (availableModules && !availableModules.has(specifier)) {
+        diagnostics.push(diagnostic(
+          "RJL108",
+          "Live JavaScript module is not approved: " + specifier,
+          entry.source
+        ));
+      }
+      for (const imported of node.specifiers) reportBinding(imported.local.name, imported.local);
+    }
+    if (node.type === "ImportExpression" || node.type === "ExportNamedDeclaration" ||
+        node.type === "ExportAllDeclaration") {
+      diagnostics.push(diagnostic(
+        "RJL104",
+        "Dynamic imports, named exports, and export forwarding are unavailable in live JavaScript.",
+        sourceAt(sourceLocation, source, node.start, node.end)
+      ));
+    }
+    if (node.type === "AwaitExpression") {
+      diagnostics.push(diagnostic(
+        "RJL105",
+        "await is unavailable in the initial synchronous live JavaScript profile.",
+        sourceAt(sourceLocation, source, node.start, node.end)
+      ));
+    }
+    if (node.type === "VariableDeclarator") {
+      for (const name of bindingNames(node.id)) reportBinding(name, node.id);
+    }
+    if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") {
+      if (node.id) reportBinding(node.id.name, node.id);
+      for (const parameter of node.params) {
+        for (const name of bindingNames(parameter)) reportBinding(name, parameter);
+      }
+    }
+    if (node.type === "ClassDeclaration" || node.type === "ClassExpression") {
+      if (node.id) reportBinding(node.id.name, node.id);
+    }
+    if (node.type === "CatchClause") {
+      for (const name of bindingNames(node.param)) reportBinding(name, node.param);
+    }
+    if (node.type === "AssignmentExpression") {
+      for (const name of bindingNames(node.left)) reportBinding(name, node.left);
+    }
+    if (node.type === "UpdateExpression") {
+      for (const name of bindingNames(node.argument)) reportBinding(name, node.argument);
+    }
+
+    const callName = node.type === "CallExpression" && node.callee.type === "Identifier"
+      ? node.callee.name
+      : null;
+    if (callName !== "ch" && callName !== "load") return;
+    const argument = node.arguments[0];
+    if (node.arguments.length !== 1 || argument?.type !== "Literal" ||
+        typeof argument.value !== "string") {
+      diagnostics.push(diagnostic(
+        "RJL107",
+        callName + " requires one static string literal.",
+        sourceAt(sourceLocation, source, node.start, node.end)
+      ));
+      return;
+    }
+    const entry = {
+      ...(callName === "ch" ? { reference: argument.value } : { name: argument.value }),
+      source: sourceAt(sourceLocation, source, node.start, node.end)
+    };
+    (callName === "ch" ? dependencies : resources).set(argument.value, entry);
+  });
+
+  return {
+    version: 1,
+    dependencies: [...dependencies.values()],
+    resources: [...resources.values()],
+    modules: [...modules.values()],
+    diagnostics
+  };
+};

package/src/engine.js

@@ -0,0 +1,282 @@
+import { parse } from "acorn";
+import { getQuickJS } from "quickjs-emscripten";
+import { analyzeJavaScript, diagnostic } from "./analyzer.js";
+
+let quickJSPromise;
+
+export const prepareQuickJS = () => {
+  quickJSPromise ??= getQuickJS();
+  return quickJSPromise;
+};
+
+const bootstrapSource = (inputs, resources) => {
+  const inputJson = JSON.stringify(inputs);
+  const resourceJson = JSON.stringify(resources);
+  return `(() => {
+"use strict";
+const O = Object;
+const J = JSON;
+const keys = O.keys;
+const descriptor = O.getOwnPropertyDescriptor;
+const prototype = O.getPrototypeOf;
+const objectPrototype = O.prototype;
+const A = Array;
+const arrayPrototype = A.prototype;
+const isArray = A.isArray;
+const isFiniteNumber = Number.isFinite;
+const isSafeInteger = Number.isSafeInteger;
+const S = Set;
+const ownKeys = Reflect.ownKeys;
+const hasOwn = O.hasOwn;
+const stringify = J.stringify;
+const inputs = J.parse(${JSON.stringify(inputJson)});
+const resources = J.parse(${JSON.stringify(resourceJson)});
+const freeze = (value, seen = new S()) => {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const key of keys(value)) freeze(value[key], seen);
+  return O.freeze(value);
+};
+freeze(inputs);
+freeze(resources);
+const ch = (name) => {
+  if (typeof name !== "string" || !hasOwn(inputs, name)) {
+    throw new Error("Unknown live dependency: " + String(name));
+  }
+  return inputs[name];
+};
+const load = (name) => {
+  if (typeof name !== "string" || !hasOwn(resources, name)) {
+    throw new Error("Unknown live resource: " + String(name));
+  }
+  return resources[name];
+};
+const validate = (value, path = "$", seen = new S()) => {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!isFiniteNumber(value)) throw new TypeError(path + " must be a finite number.");
+    return;
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(path + " has unsupported type " + typeof value + ".");
+  }
+  if (seen.has(value)) throw new TypeError(path + " contains a cycle.");
+  seen.add(value);
+  if (!isArray(value) && prototype(value) !== objectPrototype && prototype(value) !== null) {
+    throw new TypeError(path + " must be a plain record.");
+  }
+  if (isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      if (!hasOwn(value, index)) throw new TypeError(path + " must not contain array holes.");
+      const itemDescriptor = descriptor(value, index);
+      if (!itemDescriptor || !itemDescriptor.enumerable ||
+          itemDescriptor.get || itemDescriptor.set) {
+        throw new TypeError(path + "[" + index + "] must be an enumerable data property.");
+      }
+      validate(value[index], path + "[" + index + "]", seen);
+    }
+    for (const key of ownKeys(value)) {
+      if (key === "length") continue;
+      const index = typeof key === "string" && /^(?:0|[1-9][0-9]*)$/.test(key)
+        ? Number(key)
+        : -1;
+      if (!isSafeInteger(index) || index < 0 || index >= value.length) {
+        throw new TypeError(path + " has a non-index array property.");
+      }
+    }
+    seen.delete(value);
+    return;
+  }
+  for (const key of ownKeys(value)) {
+    if (typeof key !== "string") throw new TypeError(path + " must not contain symbol keys.");
+    const valueDescriptor = descriptor(value, key);
+    if (!valueDescriptor || !valueDescriptor.enumerable ||
+        valueDescriptor.get || valueDescriptor.set) {
+      throw new TypeError(path + "." + key + " must be an enumerable data property.");
+    }
+    validate(value[key], path + "." + key, seen);
+  }
+  seen.delete(value);
+};
+const bridge = O.freeze({ ch, load, validate, stringify });
+for (const name of ["eval", "Function"]) {
+  try {
+    O.defineProperty(globalThis, name, {
+      value: undefined,
+      configurable: false,
+      enumerable: false,
+      writable: false
+    });
+  } catch {}
+}
+O.defineProperty(globalThis, "__ravelBridge", {
+  value: bridge,
+  configurable: false,
+  enumerable: false,
+  writable: false
+});
+O.freeze(objectPrototype);
+O.freeze(arrayPrototype);
+O.freeze(J);
+O.freeze(Number);
+O.freeze(Reflect);
+O.freeze(S.prototype);
+})()`;
+};
+
+const moduleSource = (source) => {
+  const program = parse(source, { ecmaVersion: "latest", sourceType: "module" });
+  const exportNode = program.body.at(-1);
+  if (!exportNode || exportNode.type !== "ExportDefaultDeclaration") return null;
+  const declaration = source.slice(exportNode.declaration.start, exportNode.declaration.end);
+  const beforeExport = source.slice(0, exportNode.start);
+  return `const {
+  ch,
+  load,
+  validate: __ravelValidate,
+  stringify: __ravelStringify
+} = globalThis.__ravelBridge;
+${beforeExport}
+const __ravelValue = (${declaration});
+__ravelValidate(__ravelValue);
+export default __ravelStringify(__ravelValue);`;
+};
+
+const quickJSError = (error) => {
+  if (error && typeof error === "object") {
+    const name = error.name ? String(error.name) + ": " : "";
+    return name + (error.message ?? JSON.stringify(error));
+  }
+  return String(error);
+};
+
+const unwrapResult = (context, runtime, result) => {
+  if (result.error) {
+    runtime.setMemoryLimit(-1);
+    const error = context.dump(result.error);
+    result.error.dispose();
+    throw error;
+  }
+  return result.value;
+};
+
+const utf8Bytes = (value) => new TextEncoder().encode(value).byteLength;
+
+export const executeQuickJS = async ({ request, options = {}, modules = {} }) => {
+  const started = performance.now();
+  const availableModules = new Set(Object.keys(modules));
+  const analysis = analyzeJavaScript({
+    source: request.source,
+    sourceLocation: request.sourceLocation,
+    availableModules
+  });
+  if (analysis.diagnostics.length) {
+    return {
+      ok: false,
+      version: 1,
+      status: "failed",
+      hasExport: false,
+      diagnostics: analysis.diagnostics,
+      durationMs: performance.now() - started
+    };
+  }
+  const entrySource = moduleSource(request.source);
+  if (!entrySource) {
+    return {
+      ok: false,
+      version: 1,
+      status: "failed",
+      hasExport: false,
+      diagnostics: [diagnostic(
+        "RJL101",
+        "A live JavaScript block must contain exactly one final export default.",
+        request.sourceLocation
+      )],
+      durationMs: performance.now() - started
+    };
+  }
+
+  const timeoutMs = request.limits?.timeoutMs ?? options.timeoutMs ?? 1000;
+  const deadline = Date.now() + timeoutMs;
+  const QuickJS = await prepareQuickJS();
+  const runtime = QuickJS.newRuntime();
+  runtime.setMemoryLimit(request.limits?.memoryBytes ?? options.memoryBytes ?? 32 * 1024 * 1024);
+  runtime.setMaxStackSize(request.limits?.stackBytes ?? options.stackBytes ?? 512 * 1024);
+  runtime.setInterruptHandler(() => Date.now() >= deadline);
+  runtime.setModuleLoader(
+    (moduleName) => {
+      if (!Object.hasOwn(modules, moduleName)) {
+        throw new Error("Live JavaScript module is not approved: " + moduleName);
+      }
+      return modules[moduleName];
+    },
+    (_baseModuleName, requestedName) => requestedName
+  );
+  const context = runtime.newContext();
+
+  try {
+    const bootstrap = context.evalCode(bootstrapSource(
+      request.inputs ?? {},
+      request.resources ?? {}
+    ), "ravel:bootstrap", { type: "global", strict: true });
+    unwrapResult(context, runtime, bootstrap).dispose();
+
+    const evaluated = context.evalCode(
+      entrySource,
+      request.sourceLocation?.uri ?? request.id ?? "ravel:entry",
+      { type: "module" }
+    );
+    const exportsHandle = unwrapResult(context, runtime, evaluated);
+    const exportsValue = context.dump(exportsHandle);
+    exportsHandle.dispose();
+    const serialized = exportsValue?.default;
+    if (typeof serialized !== "string") {
+      throw new TypeError("Live JavaScript module did not return a serialized default export.");
+    }
+    const maxOutputBytes = request.limits?.outputBytes ??
+      options.outputBytes ??
+      8 * 1024 * 1024;
+    if (utf8Bytes(serialized) > maxOutputBytes) {
+      return {
+        ok: false,
+        version: 1,
+        status: "failed",
+        hasExport: true,
+        diagnostics: [diagnostic(
+          "RJL122",
+          "Live JavaScript output exceeded " + maxOutputBytes + " bytes.",
+          request.sourceLocation
+        )],
+        durationMs: performance.now() - started
+      };
+    }
+    return {
+      ok: true,
+      version: 1,
+      status: "succeeded",
+      hasExport: true,
+      serialized,
+      diagnostics: [],
+      durationMs: performance.now() - started
+    };
+  } catch (error) {
+    const timedOut = Date.now() >= deadline;
+    return {
+      ok: false,
+      version: 1,
+      status: "failed",
+      hasExport: true,
+      diagnostics: [diagnostic(
+        timedOut ? "RJL120" : "RJL110",
+        timedOut
+          ? "Live JavaScript execution exceeded " + timeoutMs + " ms."
+          : "Live JavaScript failed: " + quickJSError(error),
+        request.sourceLocation
+      )],
+      durationMs: performance.now() - started
+    };
+  } finally {
+    context.dispose();
+    runtime.dispose();
+  }
+};

package/src/index.d.ts

@@ -0,0 +1,51 @@
+import type {
+  ExecutionProvider,
+  LiveAnalysis,
+  LiveExecutionOutcome,
+  LiveExecutionRequest,
+  SourceLocation
+} from "@pieceful/ravel-core";
+
+export interface JavaScriptLiveProviderOptions {
+  id?: string;
+  languages?: string[];
+  timeoutMs?: number;
+  memoryBytes?: number;
+  stackBytes?: number;
+  outputBytes?: number;
+  workerStartupTimeoutMs?: number;
+  workerTerminationGraceMs?: number;
+  moduleEntries?: number;
+  moduleBytes?: number;
+  modules?: Map<string, string | { source: string }> |
+    Record<string, string | { source: string }>;
+  workerFactory?: () => JavaScriptLiveWorker | Promise<JavaScriptLiveWorker>;
+}
+
+export interface JavaScriptLiveWorker {
+  postMessage(message: unknown): void;
+  terminate(): unknown;
+  addEventListener?(type: "message" | "error", listener: (event: any) => void): void;
+  removeEventListener?(type: "message" | "error", listener: (event: any) => void): void;
+  on?(type: "message" | "error", listener: (value: any) => void): void;
+  off?(type: "message" | "error", listener: (value: any) => void): void;
+  ref?(): void;
+  unref?(): void;
+}
+
+export interface JavaScriptLiveProvider extends ExecutionProvider {
+  id: string;
+  version: string;
+  languages: string[];
+  analyze(request: {
+    id?: string;
+    language?: string;
+    source: string;
+    sourceLocation: SourceLocation;
+  }): LiveAnalysis;
+  execute(request: LiveExecutionRequest): Promise<LiveExecutionOutcome>;
+  dispose(): Promise<void>;
+}
+
+export function createJavaScriptLiveProvider(options?: JavaScriptLiveProviderOptions): JavaScriptLiveProvider;
+export const javascriptLiveProvider: JavaScriptLiveProvider;

package/src/index.js

@@ -0,0 +1,336 @@
+import { analyzeJavaScript, diagnostic } from "./analyzer.js";
+
+const providerId = "quickjs-wasm-worker";
+const providerVersion = "0.2.0";
+
+const moduleEntries = (modules) => {
+  if (modules instanceof Map) return [...modules.entries()];
+  if (modules && typeof modules === "object") return Object.entries(modules);
+  return [];
+};
+
+const normalizeModules = (modules, options) => {
+  const entries = moduleEntries(modules).map(([specifier, value]) => {
+    const source = typeof value === "string" ? value : value?.source;
+    if (typeof specifier !== "string" || !specifier ||
+        typeof source !== "string") {
+      throw new TypeError("Live JavaScript modules require a non-empty specifier and source string.");
+    }
+    return [specifier, source];
+  });
+  const maximumEntries = options.moduleEntries ?? 100;
+  if (entries.length > maximumEntries) {
+    throw new RangeError("Live JavaScript module registry exceeds " + maximumEntries + " entries.");
+  }
+  const maximumBytes = options.moduleBytes ?? 8 * 1024 * 1024;
+  const bytes = entries.reduce(
+    (total, [specifier, source]) =>
+      total + new TextEncoder().encode(specifier).byteLength +
+      new TextEncoder().encode(source).byteLength,
+    0
+  );
+  if (bytes > maximumBytes) {
+    throw new RangeError("Live JavaScript module registry exceeds " + maximumBytes + " bytes.");
+  }
+  return Object.fromEntries(entries);
+};
+
+const engineOptions = (options) => ({
+  timeoutMs: options.timeoutMs,
+  memoryBytes: options.memoryBytes,
+  stackBytes: options.stackBytes,
+  outputBytes: options.outputBytes
+});
+
+const isNodeLike = () =>
+  globalThis.process?.release?.name === "node" ||
+  typeof globalThis.Bun?.version === "string";
+
+const createDefaultWorker = async () => {
+  if (isNodeLike()) {
+    const workerThreadsSpecifier = "node:" + "worker_threads";
+    const { Worker } = await import(workerThreadsSpecifier);
+    return new Worker(new URL("./worker-node.js", import.meta.url), {
+      type: "module",
+      name: "ravel-quickjs",
+      // Test runners, profilers, and `node --input-type` can inject flags that
+      // are invalid for file-backed workers. The sandbox worker needs none of
+      // the parent's Node execution flags.
+      execArgv: []
+    });
+  }
+  if (typeof globalThis.Worker === "function") {
+    return new globalThis.Worker(new URL("./worker-browser.js", import.meta.url), {
+      type: "module",
+      name: "ravel-quickjs"
+    });
+  }
+  throw new Error("This host does not provide a supported Worker implementation.");
+};
+
+const workerMessage = (worker, listener) => {
+  if (typeof worker.addEventListener === "function") {
+    const wrapped = (event) => listener(event.data);
+    worker.addEventListener("message", wrapped);
+    return () => worker.removeEventListener("message", wrapped);
+  }
+  worker.on("message", listener);
+  return () => worker.off("message", listener);
+};
+
+const workerError = (worker, listener) => {
+  if (typeof worker.addEventListener === "function") {
+    const wrapped = (event) => listener(event.error ?? new Error(event.message));
+    worker.addEventListener("error", wrapped);
+    return () => worker.removeEventListener("error", wrapped);
+  }
+  worker.on("error", listener);
+  return () => worker.off("error", listener);
+};
+
+const workerExit = (worker, listener) => {
+  if (typeof worker.on !== "function") return () => {};
+  worker.on("exit", listener);
+  return () => worker.off("exit", listener);
+};
+
+const postToWorker = (worker, message) => worker.postMessage(message);
+
+const stopWorker = async (worker) => {
+  try {
+    await worker.terminate();
+  } catch {
+    // A worker that already exited is already isolated from the host.
+  }
+};
+
+const waitForWorkerConfiguration = (worker, modules, options) => new Promise((resolve, reject) => {
+  let phase = "ready";
+  const timeout = setTimeout(() => {
+    cleanup();
+    reject(new Error("QuickJS worker startup timed out."));
+  }, options.workerStartupTimeoutMs ?? 15_000);
+  const removeMessage = workerMessage(worker, (message) => {
+    if (phase === "ready" && message?.type === "ready") {
+      phase = "configured";
+      postToWorker(worker, {
+        type: "configure",
+        modules,
+        options: engineOptions(options)
+      });
+    } else if (phase === "configured" && message?.type === "configured") {
+      cleanup();
+      resolve();
+    } else if (message?.type === "startup-error") {
+      cleanup();
+      reject(new Error(message.message));
+    }
+  });
+  const removeError = workerError(worker, (error) => {
+    cleanup();
+    reject(error);
+  });
+  const removeExit = workerExit(worker, (code) => {
+    cleanup();
+    reject(new Error("QuickJS worker exited during startup with code " + code + "."));
+  });
+  const cleanup = () => {
+    clearTimeout(timeout);
+    removeMessage();
+    removeError();
+    removeExit();
+  };
+});
+
+const failureOutcome = (code, message, source) => ({
+  ok: false,
+  version: 1,
+  status: "failed",
+  hasExport: false,
+  diagnostics: [diagnostic(code, message, source)]
+});
+
+export const createJavaScriptLiveProvider = (options = {}) => {
+  const modules = normalizeModules(options.modules, options);
+  const availableModules = new Set(Object.keys(modules));
+  let workerPromise;
+  let executionSequence = 0;
+  let tail = Promise.resolve();
+  let disposed = false;
+  let cancelCurrent;
+
+  const discardWorker = async () => {
+    const pending = workerPromise;
+    workerPromise = undefined;
+    if (!pending) return;
+    try {
+      const worker = await pending;
+      await stopWorker(worker);
+    } catch {
+      // Startup failures have no usable worker to retain.
+    }
+  };
+
+  const workerForExecution = () => {
+    if (!workerPromise) {
+      const created = (async () => {
+        const worker = await (options.workerFactory?.() ?? createDefaultWorker());
+        try {
+          await waitForWorkerConfiguration(worker, modules, options);
+          worker.unref?.();
+          return worker;
+        } catch (error) {
+          await stopWorker(worker);
+          throw error;
+        }
+      })();
+      workerPromise = created;
+      created.catch(() => {
+        if (workerPromise === created) workerPromise = undefined;
+      });
+    }
+    return workerPromise;
+  };
+
+  const executeInWorker = async (request) => {
+    if (disposed) {
+      return failureOutcome(
+        "RJL131",
+        "The QuickJS worker provider has been disposed.",
+        request.sourceLocation
+      );
+    }
+    if (request.signal?.aborted) {
+      return failureOutcome("RJL121", "Live JavaScript execution was cancelled.", request.sourceLocation);
+    }
+
+    let worker;
+    try {
+      worker = await workerForExecution();
+    } catch (error) {
+      return failureOutcome(
+        "RJL130",
+        "QuickJS worker could not start: " + (error?.message ?? String(error)),
+        request.sourceLocation
+      );
+    }
+    if (request.signal?.aborted) {
+      await discardWorker();
+      return failureOutcome(
+        "RJL121",
+        "Live JavaScript execution was cancelled and its worker was terminated.",
+        request.sourceLocation
+      );
+    }
+
+    worker.ref?.();
+    const executionId = ++executionSequence;
+    const timeoutMs = request.limits?.timeoutMs ?? options.timeoutMs ?? 1000;
+    const terminationGraceMs = options.workerTerminationGraceMs ?? 100;
+    const clonedRequest = { ...request };
+    delete clonedRequest.signal;
+
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (outcome, replaceWorker = false) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (cancelCurrent === cancelExecution) cancelCurrent = undefined;
+        worker.unref?.();
+        if (replaceWorker) void discardWorker();
+        resolve(outcome);
+      };
+      const removeMessage = workerMessage(worker, (message) => {
+        if (message?.type !== "result" || message.executionId !== executionId) return;
+        settle(message.outcome);
+      });
+      const removeError = workerError(worker, (error) => {
+        settle(failureOutcome(
+          "RJL130",
+          "QuickJS worker failed: " + (error?.message ?? String(error)),
+          request.sourceLocation
+        ), true);
+      });
+      const removeExit = workerExit(worker, (code) => {
+        settle(failureOutcome(
+          "RJL130",
+          "QuickJS worker exited unexpectedly with code " + code + ".",
+          request.sourceLocation
+        ), true);
+      });
+      const timeout = setTimeout(() => {
+        settle(failureOutcome(
+          "RJL120",
+          "QuickJS worker was terminated after exceeding " + timeoutMs + " ms.",
+          request.sourceLocation
+        ), true);
+      }, timeoutMs + terminationGraceMs);
+      const onAbort = () => {
+        settle(failureOutcome(
+          "RJL121",
+          "Live JavaScript execution was cancelled and its worker was terminated.",
+          request.sourceLocation
+        ), true);
+      };
+      const cancelExecution = () => {
+        settle(failureOutcome(
+          "RJL131",
+          "The QuickJS worker provider was disposed during execution.",
+          request.sourceLocation
+        ), true);
+      };
+      cancelCurrent = cancelExecution;
+      const cleanup = () => {
+        clearTimeout(timeout);
+        removeMessage();
+        removeError();
+        removeExit();
+        request.signal?.removeEventListener("abort", onAbort);
+      };
+      request.signal?.addEventListener("abort", onAbort, { once: true });
+      if (request.signal?.aborted) {
+        onAbort();
+        return;
+      }
+
+      try {
+        postToWorker(worker, {
+          type: "execute",
+          executionId,
+          request: clonedRequest
+        });
+      } catch (error) {
+        settle(failureOutcome(
+          "RJL130",
+          "QuickJS worker request failed: " + (error?.message ?? String(error)),
+          request.sourceLocation
+        ), true);
+      }
+    });
+  };
+
+  const provider = {
+    id: options.id ?? providerId,
+    version: providerVersion,
+    languages: options.languages ?? ["js", "javascript"],
+    analyze: (request) => analyzeJavaScript({ ...request, availableModules }),
+    execute: (request) => {
+      const scheduled = tail.then(
+        () => executeInWorker(request),
+        () => executeInWorker(request)
+      );
+      tail = scheduled.then(() => undefined, () => undefined);
+      return scheduled;
+    },
+    dispose: async () => {
+      disposed = true;
+      cancelCurrent?.();
+      await tail;
+      await discardWorker();
+    }
+  };
+  return provider;
+};
+
+export const javascriptLiveProvider = createJavaScriptLiveProvider();

package/src/node.d.ts

@@ -0,0 +1,20 @@
+import type { Diagnostic, SourceLocation } from "@pieceful/ravel-core";
+
+export interface JavaScriptModuleDeclaration {
+  specifier: string;
+  from: string;
+  source?: SourceLocation;
+}
+
+export class JavaScriptModulePreparationError extends Error {
+  diagnostics: Diagnostic[];
+}
+
+export function prepareJavaScriptModules(
+  declarations: JavaScriptModuleDeclaration[],
+  options: {
+    rootDirectory: string;
+    moduleEntries?: number;
+    moduleBytes?: number;
+  }
+): Promise<Record<string, string>>;

package/src/node.js

@@ -0,0 +1,100 @@
+import { Buffer } from "node:buffer";
+import { resolve } from "node:path";
+import { build as bundleWithEsbuild } from "esbuild";
+
+const packageExportPattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/i;
+
+const fallbackSource = (uri = "<ravel-config>") => ({
+  uri,
+  range: {
+    start: { line: 0, column: 0, offset: 0 },
+    end: { line: 0, column: 0, offset: 0 }
+  }
+});
+
+/** Expected failure while preparing a configured package for QuickJS. */
+export class JavaScriptModulePreparationError extends Error {
+  constructor(diagnostics) {
+    super(diagnostics.map((entry) => entry.message).join(" "));
+    this.name = "JavaScriptModulePreparationError";
+    this.diagnostics = diagnostics;
+  }
+}
+
+const preparationError = (message, source) => new JavaScriptModulePreparationError([{
+  code: "RJL140",
+  severity: "error",
+  message,
+  source: source?.uri ? source : fallbackSource()
+}]);
+
+/**
+ * Bundle explicitly allowlisted, already-installed package exports for a
+ * closed live-JavaScript module registry. Package code is read but not run.
+ */
+export const prepareJavaScriptModules = async (declarations, {
+  rootDirectory,
+  moduleEntries = 100,
+  moduleBytes = 8 * 1024 * 1024
+} = {}) => {
+  if (!Array.isArray(declarations)) throw new TypeError("Live module declarations must be an array.");
+  if (declarations.length > moduleEntries) {
+    throw preparationError(
+      "Live module count exceeds the configured limit of " + moduleEntries + ".",
+      declarations[0]?.source
+    );
+  }
+  if (typeof rootDirectory !== "string" || !rootDirectory) {
+    throw new TypeError("rootDirectory must be a non-empty string.");
+  }
+  const root = resolve(rootDirectory);
+  const modules = {};
+  let bytes = 0;
+
+  for (const declaration of declarations) {
+    const source = declaration?.source;
+    const specifier = declaration?.specifier;
+    const packageExport = declaration?.from;
+    if (typeof specifier !== "string" || !specifier ||
+        typeof packageExport !== "string" || !packageExportPattern.test(packageExport)) {
+      throw preparationError("Invalid live JavaScript module declaration.", source);
+    }
+    if (Object.hasOwn(modules, specifier)) {
+      throw preparationError("Duplicate live JavaScript module specifier: " + specifier, source);
+    }
+    let result;
+    try {
+      result = await bundleWithEsbuild({
+        absWorkingDir: root,
+        entryPoints: [packageExport],
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "neutral",
+        target: "es2023",
+        packages: "bundle",
+        legalComments: "none",
+        logLevel: "silent"
+      });
+    } catch (error) {
+      const detail = error?.errors?.[0]?.text ?? error?.message ?? String(error);
+      throw preparationError(
+        "Unable to prepare live module " + specifier + " from " + packageExport + ": " + detail,
+        source
+      );
+    }
+    if (result.outputFiles?.length !== 1) {
+      throw preparationError("Live module " + specifier + " did not produce one ESM bundle.", source);
+    }
+    const bundled = result.outputFiles[0].text;
+    bytes += Buffer.byteLength(bundled, "utf8");
+    if (bytes > moduleBytes) {
+      throw preparationError(
+        "Live module source exceeds the configured limit of " + moduleBytes + " bytes.",
+        source
+      );
+    }
+    modules[specifier] = bundled;
+  }
+  return modules;
+};

package/src/worker-browser.d.ts

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

package/src/worker-browser.js

@@ -0,0 +1,6 @@
+import { startWorkerRuntime } from "./worker-runtime.js";
+
+await startWorkerRuntime({
+  post: (message) => globalThis.postMessage(message),
+  listen: (listener) => globalThis.addEventListener("message", (event) => listener(event.data))
+});

package/src/worker-node.js

@@ -0,0 +1,9 @@
+import { parentPort } from "node:worker_threads";
+import { startWorkerRuntime } from "./worker-runtime.js";
+
+if (!parentPort) throw new Error("The QuickJS Node worker requires a parent port.");
+
+await startWorkerRuntime({
+  post: (message) => parentPort.postMessage(message),
+  listen: (listener) => parentPort.on("message", listener)
+});

package/src/worker-runtime.js

@@ -0,0 +1,51 @@
+import { diagnostic } from "./analyzer.js";
+import { executeQuickJS, prepareQuickJS } from "./engine.js";
+
+export const startWorkerRuntime = async ({ post, listen }) => {
+  try {
+    await prepareQuickJS();
+    post({ type: "ready" });
+  } catch (error) {
+    post({
+      type: "startup-error",
+      message: error?.message ?? String(error)
+    });
+    return;
+  }
+
+  let configuration = { options: {}, modules: {} };
+  listen(async (message) => {
+    if (message?.type === "configure") {
+      configuration = {
+        options: message.options ?? {},
+        modules: message.modules ?? {}
+      };
+      post({ type: "configured" });
+      return;
+    }
+    if (message?.type !== "execute") return;
+    const { executionId, request } = message;
+    post({ type: "started", executionId });
+    let outcome;
+    try {
+      outcome = await executeQuickJS({
+        request,
+        options: configuration.options,
+        modules: configuration.modules
+      });
+    } catch (error) {
+      outcome = {
+        ok: false,
+        version: 1,
+        status: "failed",
+        hasExport: false,
+        diagnostics: [diagnostic(
+          "RJL130",
+          "QuickJS worker failed: " + (error?.message ?? String(error)),
+          request.sourceLocation
+        )]
+      };
+    }
+    post({ type: "result", executionId, outcome });
+  });
+};