@onda-lang/wasm-compiler 0.5.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Cameli
+
+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,131 @@
+# Onda WebAssembly compiler
+
+`@onda-lang/wasm-compiler` compiles Onda source or an in-memory multi-file project to a complete,
+self-contained WebAssembly processor artifact. It runs in modern browsers and Node.js and does not
+require LLVM, a Wasm linker, Rust, or `wasm-pack` after installation.
+
+```js
+import { createCompiler } from "@onda-lang/wasm-compiler";
+
+const compiler = await createCompiler();
+const artifact = await compiler.compileSource(source, {
+  sampleRate: 48_000,
+  blockSize: 128,
+});
+
+console.log(artifact.wasm, artifact.metadata);
+```
+
+The package composes Onda's embedded Rust frontend with its Binaryen backend. The frontend emits
+validated versioned MIR in memory; the backend lowers that trusted producer output to the generic
+Onda WebAssembly processor ABI. The package verifies the MIR schema handshake during startup.
+
+Release builds post-optimize the Rust frontend Wasm with the package's pinned Binaryen
+`wasm-opt -O4`. The build records input/output sizes and the optimizer version in
+`dist/build.json`, and fails if the pass does not reduce the shipped module. Generated DSP modules
+are already optimized independently by the runtime Binaryen O4 pipeline.
+
+## Projects
+
+Project compilation resolves imports and includes entirely from the supplied source map and the
+embedded standard library:
+
+```js
+const artifact = await compiler.compileProject({
+  entry: "main.onda",
+  sources: {
+    "main.onda": mainSource,
+    "dsp/filter.onda": filterSource,
+  },
+}, {
+  sampleRate: 48_000,
+  blockSize: 128,
+});
+```
+
+Compilation failures throw `OndaCompileError`. Its `diagnostics` property contains structured
+parse, semantic, MIR, configuration, or code-generation diagnostics.
+
+## Browser workers
+
+Compilation is CPU-intensive. Use the built-in worker client in interactive browser applications:
+
+```js
+const compiler = await createCompiler({ worker: true });
+const artifact = await compiler.compileSource(source, options);
+await compiler.dispose();
+```
+
+Static hosts and bundlers may provide explicit `workerUrl` and `frontendWasm` URLs. The worker
+receives the frontend URL during initialization, so versioned or content-hashed compiler assets do
+not depend on the package's development directory layout.
+
+In worker mode the page-side entry point stays lightweight; the Rust frontend Wasm, Binaryen, and
+the MIR backend are loaded only inside the worker.
+
+The package also exports `@onda-lang/wasm-compiler/worker` for hosts that want to own the worker
+protocol directly.
+
+## Browser LSP
+
+The frontend Wasm contains the same transport-neutral language server used by `onda lsp`. Worker
+clients send ordinary JSON-RPC/LSP messages and receive every response or notification emitted for
+that message:
+
+```js
+await compiler.setLspAnalysisOptions({ sampleRate: 48_000, blockSize: 256 });
+
+const [initialized] = await compiler.sendLspMessage({
+  jsonrpc: "2.0",
+  id: 1,
+  method: "initialize",
+  params: { processId: null, capabilities: {} },
+});
+
+await compiler.sendLspMessage({
+  jsonrpc: "2.0",
+  method: "textDocument/didOpen",
+  params: {
+    textDocument: {
+      uri: "file:///onda-project/main.onda",
+      languageId: "onda",
+      version: 1,
+      text: source,
+    },
+  },
+});
+```
+
+Open every virtual project file with `didOpen`; imports and includes resolve from those overlays and
+the embedded standard library. Diagnostics, semantic tokens, completion, hover, definitions, and
+document symbols use the native server implementation. The browser transport does not run MIR or a
+backend until the host explicitly calls `compileSource` or `compileProject`.
+
+## CLI
+
+The npm package installs `onda-wasm`:
+
+```sh
+onda-wasm compile ./main.onda --root . --output ./dist/main.wasm
+```
+
+The command recursively collects `.onda` files below `--root`, compiles the requested entry, and
+writes an integrity-associated `main.wasm` plus `main.onda.json` descriptor. Use `--help` for code
+generation and output options.
+
+## Artifact hosting
+
+The compiler returns the generic processor artifact. Web Audio is optional; use
+`@onda-lang/webaudio` when an `AudioWorklet` host is desired. Build-time users should publish only
+the generated `.wasm` and `.onda.json`, not this compiler package or Binaryen.
+
+The low-level `@onda-lang/binaryen-web` package remains available for advanced consumers that
+already produce compatible Onda MIR.
+
+## Versioning
+
+`[workspace.package].version` in the repository's top-level `Cargo.toml` is the only authored Onda
+version. Run `scripts/sync-versions.sh` or `scripts/sync-versions.ps1` after changing it.
+The underlying `scripts/sync-package-versions.mjs` updates the workspace-owned `Cargo.lock` entries,
+discovers every `@onda-lang/*` package, and synchronizes its manifest and lockfile. Compiler builds
+and release jobs run it automatically; `ONDA_VERSION` is generated into the packaged distribution.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+The packaged compiler includes the following third-party components:
+
+- Binaryen.js 130.0.0, licensed under Apache-2.0. The complete license is shipped as
+  `dist/licenses/BINARYEN-LICENSE`.
+- The Onda WebAssembly math kernel uses `libm` 0.2.16, licensed under MIT. The complete license is
+  shipped as `dist/licenses/LIBM-LICENSE`.
+
+The generated processor artifacts contain only the required closure of the math kernel. They do
+not contain Binaryen itself.

package/bin/onda-wasm.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  OndaCompileError,
+  createCompiler,
+  createProcessorArtifactFiles,
+} from "../src/index.js";
+import { MAX_BLOCK_SIZE } from "../src/config.js";
+
+const HELP = `Usage:
+  onda-wasm compile <input.onda> [options]
+
+Options:
+  --root <directory>       Project root used to collect .onda sources
+  --output, -o <file>      Output Wasm path (default: <input>.wasm)
+  --meta-out <file>        Output descriptor path (default: <output>.onda.json)
+  --sample-rate <number>   Compile-time sample rate (default: 48000)
+  --block-size <integer>   Compile-time block size (default: 128)
+  --optimize-level <0..4>  Binaryen optimization level (default: 4)
+  --shrink-level <0..2>    Binaryen shrink level (default: 0)
+  --fast-math              Enable relaxed floating-point rewrites
+  --no-simd                Disable WebAssembly SIMD code generation
+  --wat-out <file>         Also write WebAssembly text format
+  --help, -h               Show this help
+  --version, -V            Show the Onda compiler version
+`;
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (argv.includes("--version") || argv.includes("-V")) {
+    const manifest = JSON.parse(
+      await readFile(new URL("../package.json", import.meta.url), "utf8"),
+    );
+    process.stdout.write(`${manifest.version}\n`);
+    return 0;
+  }
+  if (argv[0] !== "compile") {
+    throw new Error(`unknown command '${argv[0]}'\n\n${HELP}`);
+  }
+
+  const parsed = parseCompileArguments(argv.slice(1));
+  const input = resolve(parsed.input);
+  const root = resolve(parsed.root ?? dirname(input));
+  const entryRelative = relative(root, input);
+  if (entryRelative === "" || entryRelative === ".") {
+    throw new Error("input must identify an .onda file below the project root");
+  }
+  if (entryRelative === ".." || entryRelative.startsWith(`..${sep}`) || isAbsolute(entryRelative)) {
+    throw new Error(`input '${input}' is outside project root '${root}'`);
+  }
+  if (extname(input) !== ".onda") {
+    throw new Error("input must have an .onda extension");
+  }
+
+  const sources = await collectSources(root);
+  const entry = portablePath(entryRelative);
+  if (!(entry in sources)) {
+    throw new Error(`input '${entry}' was not found while collecting project sources`);
+  }
+
+  const output = normalizeWasmOutput(parsed.output ?? resolve(dirname(input), parse(input).name));
+  const metadataOutput = resolve(
+    parsed.metaOut ?? output.slice(0, -".wasm".length) + ".onda.json",
+  );
+  const watOutput = parsed.watOut === undefined ? undefined : resolve(parsed.watOut);
+  const compiler = await createCompiler();
+  try {
+    const artifact = await compiler.compileProject({ entry, sources }, {
+      sampleRate: parsed.sampleRate,
+      blockSize: parsed.blockSize,
+      codegen: {
+        optimizeLevel: parsed.optimizeLevel,
+        shrinkLevel: parsed.shrinkLevel,
+        fastMath: parsed.fastMath,
+        simd: parsed.simd,
+        emitText: watOutput !== undefined,
+      },
+    });
+    const files = await createProcessorArtifactFiles(artifact, {
+      baseName: parse(output).name,
+    });
+    await mkdir(dirname(output), { recursive: true });
+    await mkdir(dirname(metadataOutput), { recursive: true });
+    if (watOutput !== undefined) await mkdir(dirname(watOutput), { recursive: true });
+    const writes = [
+      writeFile(output, files.wasm.bytes),
+      writeFile(metadataOutput, files.metadata.text),
+    ];
+    if (watOutput !== undefined) {
+      if (typeof artifact.wat !== "string") {
+        throw new Error("Binaryen did not return the requested WebAssembly text");
+      }
+      writes.push(writeFile(watOutput, artifact.wat));
+    }
+    await Promise.all(writes);
+    process.stdout.write(`Wrote WebAssembly: ${output}\n`);
+    process.stdout.write(`Wrote descriptor: ${metadataOutput}\n`);
+    if (watOutput !== undefined) process.stdout.write(`Wrote WebAssembly text: ${watOutput}\n`);
+    return 0;
+  } finally {
+    await compiler.dispose();
+  }
+}
+
+function parseCompileArguments(args) {
+  let input;
+  const result = {
+    root: undefined,
+    output: undefined,
+    metaOut: undefined,
+    sampleRate: 48_000,
+    blockSize: 128,
+    optimizeLevel: 4,
+    shrinkLevel: 0,
+    fastMath: false,
+    simd: true,
+    watOut: undefined,
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("-")) {
+      if (input !== undefined) throw new Error(`unexpected argument '${argument}'`);
+      input = argument;
+      continue;
+    }
+    switch (argument) {
+      case "--root":
+        result.root = requiredValue(args, ++index, argument);
+        break;
+      case "--output":
+      case "-o":
+        result.output = requiredValue(args, ++index, argument);
+        break;
+      case "--meta-out":
+        result.metaOut = requiredValue(args, ++index, argument);
+        break;
+      case "--sample-rate":
+        result.sampleRate = numberValue(args, ++index, argument);
+        break;
+      case "--block-size":
+        result.blockSize = integerValue(args, ++index, argument, 1, MAX_BLOCK_SIZE);
+        break;
+      case "--optimize-level":
+        result.optimizeLevel = integerValue(args, ++index, argument, 0, 4);
+        break;
+      case "--shrink-level":
+        result.shrinkLevel = integerValue(args, ++index, argument, 0, 2);
+        break;
+      case "--fast-math":
+        result.fastMath = true;
+        break;
+      case "--no-simd":
+        result.simd = false;
+        break;
+      case "--wat-out":
+        result.watOut = requiredValue(args, ++index, argument);
+        break;
+      default:
+        throw new Error(`unknown option '${argument}'`);
+    }
+  }
+  if (input === undefined) throw new Error("compile requires an input .onda file");
+  return { input, ...result };
+}
+
+async function collectSources(root) {
+  const sources = Object.create(null);
+  await visit(root);
+  return sources;
+
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if ([".git", "node_modules", "target"].includes(entry.name)) continue;
+        await visit(resolve(directory, entry.name));
+      } else if (entry.isFile() && extname(entry.name) === ".onda") {
+        const path = resolve(directory, entry.name);
+        sources[portablePath(relative(root, path))] = await readFile(path, "utf8");
+      }
+    }
+  }
+}
+
+function normalizeWasmOutput(output) {
+  const resolved = resolve(output);
+  return extname(resolved) === ".wasm" ? resolved : `${resolved}.wasm`;
+}
+
+function portablePath(path) {
+  return path.split(sep).join("/");
+}
+
+function requiredValue(args, index, option) {
+  const value = args[index];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`${option} requires a value`);
+  }
+  return value;
+}
+
+function numberValue(args, index, option) {
+  const value = Number(requiredValue(args, index, option));
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${option} requires a finite number greater than zero`);
+  }
+  return value;
+}
+
+function integerValue(args, index, option, minimum, maximum) {
+  const value = Number(requiredValue(args, index, option));
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`${option} requires an integer from ${minimum} to ${maximum}`);
+  }
+  return value;
+}
+
+function printError(error) {
+  if (error instanceof OndaCompileError) {
+    for (const diagnostic of error.diagnostics) {
+      const location = diagnostic.file
+        ? `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: `
+        : "";
+      process.stderr.write(`${location}[${diagnostic.stage}] ${diagnostic.message}\n`);
+    }
+    return;
+  }
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().then(
+    (status) => {
+      process.exitCode = status;
+    },
+    (error) => {
+      printError(error);
+      process.exitCode = 1;
+    },
+  );
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@onda-lang/wasm-compiler",
+  "version": "0.5.0-rc.0",
+  "type": "module",
+  "description": "Onda source-to-WebAssembly compiler for browsers and Node.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onda-lang/onda.git",
+    "directory": "packages/onda_wasm_compiler"
+  },
+  "homepage": "https://onda-lang.github.io/onda/",
+  "bugs": {
+    "url": "https://github.com/onda-lang/onda/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./artifact": {
+      "types": "./src/artifact.d.ts",
+      "default": "./src/artifact.js"
+    },
+    "./worker": {
+      "types": "./src/worker.d.ts",
+      "default": "./src/worker.js"
+    }
+  },
+  "imports": {
+    "#onda-frontend-loader": {
+      "node": "./src/frontend-node.js",
+      "default": "./src/frontend-browser.js"
+    }
+  },
+  "bin": {
+    "onda-wasm": "./bin/onda-wasm.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "sync:versions": "node ../../scripts/sync-package-versions.mjs",
+    "check:versions": "node ../../scripts/sync-package-versions.mjs --check",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node --test ./test/*.test.js",
+    "test:pack": "node ./scripts/test-package.mjs",
+    "test:pack:built": "node ./scripts/test-package.mjs --skip-build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@onda-lang/processor-abi": "0.5.0-rc.0",
+    "binaryen": "130.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/artifact.d.ts

@@ -0,0 +1 @@
+export * from "@onda-lang/processor-abi";

package/src/artifact.js

@@ -0,0 +1 @@
+export * from "@onda-lang/processor-abi";

package/src/config.js

@@ -0,0 +1,2 @@
+// Onda's MIR and processor ABI use signed i32 frame indices.
+export const MAX_BLOCK_SIZE = 0x7fff_ffff;

package/src/frontend-browser.js

@@ -0,0 +1,6 @@
+export function defaultFrontendInput() {
+  return new URL(
+    "../dist/frontend/onda_compiler_web_bg.wasm",
+    import.meta.url,
+  );
+}

package/src/frontend-node.js

@@ -0,0 +1,8 @@
+import { readFile } from "node:fs/promises";
+
+export function defaultFrontendInput() {
+  return readFile(new URL(
+    "../dist/frontend/onda_compiler_web_bg.wasm",
+    import.meta.url,
+  ));
+}

package/src/index.d.ts

@@ -0,0 +1,119 @@
+export const ONDA_VERSION: string;
+export const MIR_SCHEMA_VERSION: number;
+export {
+  OndaArtifactError,
+  PROCESSOR_ABI_VERSION,
+  PROCESSOR_ARTIFACT_FORMAT,
+  PROCESSOR_ARTIFACT_FORMAT_VERSION,
+  PROCESSOR_SNAPSHOT_FORMAT_VERSION,
+  createProcessorArtifactFiles,
+  loadProcessorArtifactFiles,
+  parseProcessorMetadata,
+  serializeProcessorMetadata,
+  validateProcessorArtifact,
+  validateProcessorMetadata,
+  validateProcessorModule,
+} from "@onda-lang/processor-abi";
+export type {
+  OndaProcessorArtifact,
+  OndaProcessorMetadata,
+} from "@onda-lang/processor-abi";
+import type { OndaProcessorArtifact } from "@onda-lang/processor-abi";
+
+export interface OndaCompilerDiagnostic {
+  stage: string;
+  code: number;
+  message: string;
+  file: string | null;
+  line: number;
+  column: number;
+  end_line: number;
+  end_column: number;
+  trace: string[];
+}
+
+export interface OndaCodegenOptions {
+  optimize?: boolean;
+  optimizeLevel?: 0 | 1 | 2 | 3 | 4;
+  shrinkLevel?: 0 | 1 | 2;
+  fastMath?: boolean;
+  simd?: boolean;
+  allowInliningFunctionsWithLoops?: boolean;
+  emitText?: boolean;
+}
+
+export interface OndaCompileOptions {
+  sampleRate?: number;
+  blockSize?: number;
+  codegen?: OndaCodegenOptions;
+}
+
+export interface OndaProject {
+  entry: string;
+  sources: Record<string, string>;
+}
+
+export interface OndaCompilerInstance {
+  compileSource(
+    source: string,
+    options?: OndaCompileOptions,
+  ): Promise<OndaProcessorArtifact>;
+  compileProject(
+    project: OndaProject,
+    options?: OndaCompileOptions,
+  ): Promise<OndaProcessorArtifact>;
+  sendLspMessage(message: OndaLspMessage): Promise<OndaLspMessage[]>;
+  setLspAnalysisOptions(options?: OndaCompileOptions): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export interface OndaLspMessage {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface DirectCompilerOptions {
+  worker?: false;
+  frontendWasm?: string | URL | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
+}
+
+export interface OndaWorkerLike {
+  addEventListener(type: "message" | "error", listener: (event: any) => void): void;
+  removeEventListener(type: "message" | "error", listener: (event: any) => void): void;
+  postMessage(message: unknown): void;
+  terminate(): void;
+}
+
+export interface OndaWorkerConstructor {
+  new (
+    url: string | URL,
+    options: { type: "module"; name: string },
+  ): OndaWorkerLike;
+}
+
+export interface WorkerCompilerOptions {
+  worker: true;
+  workerUrl?: string | URL;
+  frontendWasm?: string | URL | ArrayBuffer | ArrayBufferView | WebAssembly.Module;
+  Worker?: OndaWorkerConstructor;
+}
+
+export class OndaCompilerError extends Error {
+  cause?: unknown;
+}
+
+export class OndaCompileError extends OndaCompilerError {
+  readonly diagnostics: OndaCompilerDiagnostic[];
+}
+
+export class OndaBinaryenError extends Error {}
+
+export function createCompiler(
+  options?: DirectCompilerOptions | WorkerCompilerOptions,
+): Promise<OndaCompilerInstance>;
+
+export function createDefaultImports(): Record<string, never>;

package/src/index.js

@@ -0,0 +1,384 @@
+import {
+  OndaArtifactError,
+  PROCESSOR_ABI_VERSION,
+  PROCESSOR_ARTIFACT_FORMAT,
+  PROCESSOR_ARTIFACT_FORMAT_VERSION,
+  PROCESSOR_SNAPSHOT_FORMAT_VERSION,
+  createProcessorArtifactFiles,
+  loadProcessorArtifactFiles,
+  parseProcessorMetadata,
+  serializeProcessorMetadata,
+  validateProcessorArtifact,
+  validateProcessorMetadata,
+  validateProcessorModule,
+} from "@onda-lang/processor-abi";
+import { SUPPORTED_MIR_SCHEMA_VERSION } from "../dist/backend/constants.js";
+import { OndaBinaryenError } from "../dist/backend/errors.js";
+import { defaultFrontendInput } from "#onda-frontend-loader";
+import { ONDA_VERSION } from "../dist/version.js";
+import { MAX_BLOCK_SIZE } from "./config.js";
+
+export const MIR_SCHEMA_VERSION = SUPPORTED_MIR_SCHEMA_VERSION;
+export { ONDA_VERSION };
+
+export {
+  OndaArtifactError,
+  OndaBinaryenError,
+  PROCESSOR_ABI_VERSION,
+  PROCESSOR_ARTIFACT_FORMAT,
+  PROCESSOR_ARTIFACT_FORMAT_VERSION,
+  PROCESSOR_SNAPSHOT_FORMAT_VERSION,
+  createProcessorArtifactFiles,
+  loadProcessorArtifactFiles,
+  parseProcessorMetadata,
+  serializeProcessorMetadata,
+  validateProcessorArtifact,
+  validateProcessorMetadata,
+  validateProcessorModule,
+};
+
+export class OndaCompilerError extends Error {
+  constructor(message, { cause } = {}) {
+    super(message);
+    this.name = "OndaCompilerError";
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+export class OndaCompileError extends OndaCompilerError {
+  constructor(diagnostics, { cause } = {}) {
+    const normalized = normalizeDiagnostics(diagnostics);
+    const first = normalized[0];
+    const message = first
+      ? `${first.stage}: ${first.message}`
+      : "Onda compilation failed";
+    super(message, { cause });
+    this.name = "OndaCompileError";
+    this.diagnostics = normalized;
+  }
+}
+
+let toolchainInitialization;
+
+class OndaCompiler {
+  constructor(frontend, compileTrustedMir) {
+    this.frontend = frontend;
+    this.compileTrustedMir = compileTrustedMir;
+    this.lsp = null;
+  }
+
+  async compileSource(source, options = {}) {
+    if (typeof source !== "string") {
+      throw configurationError("source must be a string");
+    }
+    const compile = normalizeCompileOptions(options);
+    let mir;
+    try {
+      mir = this.frontend.compile_to_mir_messagepack(
+        source,
+        compile.sampleRate,
+        compile.blockSize,
+      );
+    } catch (error) {
+      throw diagnosticsFromFrontend(error);
+    }
+    return compileMirTransport(mir, compile.codegen, this.compileTrustedMir);
+  }
+
+  async compileProject(project, options = {}) {
+    if (!project || typeof project !== "object" || Array.isArray(project)) {
+      throw configurationError("project must contain an entry and source map");
+    }
+    if (typeof project.entry !== "string" || project.entry.length === 0) {
+      throw configurationError("project.entry must be a non-empty string");
+    }
+    if (!project.sources || typeof project.sources !== "object" || Array.isArray(project.sources)) {
+      throw configurationError("project.sources must be an object of paths to source strings");
+    }
+    for (const [path, source] of Object.entries(project.sources)) {
+      if (typeof source !== "string") {
+        throw configurationError(`project source '${path}' must be a string`);
+      }
+    }
+
+    const compile = normalizeCompileOptions(options);
+    let mir;
+    try {
+      mir = this.frontend.compile_project_to_mir_messagepack(
+        project.entry,
+        JSON.stringify(project.sources),
+        compile.sampleRate,
+        compile.blockSize,
+      );
+    } catch (error) {
+      throw diagnosticsFromFrontend(error);
+    }
+    return compileMirTransport(mir, compile.codegen, this.compileTrustedMir);
+  }
+
+  async sendLspMessage(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message)) {
+      throw new OndaCompilerError("LSP message must be a JSON-RPC object");
+    }
+    this.lsp ??= new this.frontend.OndaLsp();
+    try {
+      const responses = JSON.parse(this.lsp.handle_message(JSON.stringify(message)));
+      if (!Array.isArray(responses)) {
+        throw new Error("Onda LSP returned a non-array response batch");
+      }
+      return responses;
+    } catch (cause) {
+      throw new OndaCompilerError("Onda LSP failed to handle a message", { cause });
+    }
+  }
+
+  async setLspAnalysisOptions(options = {}) {
+    const compile = normalizeCompileOptions(options);
+    this.lsp ??= new this.frontend.OndaLsp();
+    try {
+      this.lsp.set_analysis_options(compile.sampleRate, compile.blockSize);
+    } catch (cause) {
+      throw new OndaCompilerError("failed to configure Onda LSP analysis", { cause });
+    }
+  }
+
+  async dispose() {
+    this.lsp?.free();
+    this.lsp = null;
+  }
+}
+
+class WorkerOndaCompiler {
+  constructor(worker) {
+    this.worker = worker;
+    this.nextRequestId = 1;
+    this.pending = new Map();
+    this.onMessage = (event) => this.handleMessage(event.data);
+    this.onError = (event) => this.failAll(event.error ?? new Error(event.message));
+    worker.addEventListener("message", this.onMessage);
+    worker.addEventListener("error", this.onError);
+  }
+
+  initialize(frontendWasm) {
+    return this.request("initialize", { frontendWasm });
+  }
+
+  compileSource(source, options = {}) {
+    return this.request("compileSource", { source, options });
+  }
+
+  compileProject(project, options = {}) {
+    return this.request("compileProject", { project, options });
+  }
+
+  sendLspMessage(message) {
+    return this.request("lspMessage", { message });
+  }
+
+  setLspAnalysisOptions(options = {}) {
+    return this.request("lspAnalysisOptions", { options });
+  }
+
+  async dispose() {
+    try {
+      await this.request("dispose");
+    } finally {
+      this.terminate(new OndaCompilerError("compiler worker was disposed"));
+    }
+  }
+
+  terminate(error) {
+    this.worker.removeEventListener("message", this.onMessage);
+    this.worker.removeEventListener("error", this.onError);
+    this.worker.terminate();
+    this.failAll(error);
+  }
+
+  request(type, fields = {}) {
+    const requestId = this.nextRequestId;
+    this.nextRequestId += 1;
+    return new Promise((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject });
+      this.worker.postMessage({ type, requestId, ...fields });
+    });
+  }
+
+  handleMessage(message) {
+    const pending = this.pending.get(message?.requestId);
+    if (!pending) return;
+    this.pending.delete(message.requestId);
+    if (message.type === "result") {
+      pending.resolve(message.value);
+      return;
+    }
+    const error = message.error?.diagnostics
+      ? new OndaCompileError(message.error.diagnostics)
+      : new OndaCompilerError(message.error?.message ?? "compiler worker failed");
+    if (message.error?.name) error.name = message.error.name;
+    if (message.error?.stack) error.stack = message.error.stack;
+    pending.reject(error);
+  }
+
+  failAll(error) {
+    for (const { reject } of this.pending.values()) reject(error);
+    this.pending.clear();
+  }
+}
+
+export async function createCompiler(options = {}) {
+  if (options.worker === true) {
+    const WorkerConstructor = options.Worker ?? globalThis.Worker;
+    if (typeof WorkerConstructor !== "function") {
+      throw new OndaCompilerError(
+        "worker compilation requires a browser Worker constructor",
+      );
+    }
+    const workerUrl = options.workerUrl ?? new URL("./worker.js", import.meta.url);
+    const compiler = new WorkerOndaCompiler(
+      new WorkerConstructor(workerUrl, {
+        type: "module",
+        name: "onda-wasm-compiler",
+      }),
+    );
+    try {
+      await compiler.initialize(options.frontendWasm);
+      return compiler;
+    } catch (error) {
+      compiler.terminate(
+        new OndaCompilerError("compiler worker initialization failed", { cause: error }),
+      );
+      throw error;
+    }
+  }
+
+  if (!toolchainInitialization) {
+    let initialization;
+    initialization = initializeToolchain(options.frontendWasm).catch((error) => {
+      if (toolchainInitialization === initialization) {
+        toolchainInitialization = undefined;
+      }
+      throw error;
+    });
+    toolchainInitialization = initialization;
+  }
+  const toolchain = await toolchainInitialization;
+  return new OndaCompiler(toolchain.frontend, toolchain.compileTrustedMir);
+}
+
+async function initializeToolchain(frontendWasm) {
+  const [frontend, backend] = await Promise.all([
+    import("../dist/frontend/onda_compiler_web.js"),
+    import("../dist/backend/index.js"),
+  ]);
+  const moduleOrPath = frontendWasm ?? await defaultFrontendInput();
+  try {
+    await frontend.default({ module_or_path: moduleOrPath });
+  } catch (cause) {
+    throw new OndaCompilerError("failed to initialize the Onda frontend Wasm", { cause });
+  }
+  const producerSchema = frontend.mir_schema_version();
+  if (producerSchema !== SUPPORTED_MIR_SCHEMA_VERSION) {
+    throw new OndaCompilerError(
+      `MIR schema mismatch: frontend produces ${producerSchema}, Binaryen backend supports ${SUPPORTED_MIR_SCHEMA_VERSION}`,
+    );
+  }
+  return { frontend, compileTrustedMir: backend.compileTrustedMir };
+}
+
+export function createDefaultImports() {
+  return {};
+}
+
+function normalizeCompileOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw configurationError("compiler options must be an object");
+  }
+  const sampleRate = options.sampleRate ?? 48_000;
+  const blockSize = options.blockSize ?? 128;
+  if (typeof sampleRate !== "number" || !Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw configurationError("sampleRate must be finite and greater than zero");
+  }
+  if (!Number.isInteger(blockSize) || blockSize <= 0 || blockSize > MAX_BLOCK_SIZE) {
+    throw configurationError(`blockSize must be between 1 and ${MAX_BLOCK_SIZE} frames`);
+  }
+  if (
+    options.codegen !== undefined
+    && (!options.codegen || typeof options.codegen !== "object" || Array.isArray(options.codegen))
+  ) {
+    throw configurationError("codegen options must be an object");
+  }
+  return { sampleRate, blockSize, codegen: options.codegen ?? {} };
+}
+
+function compileMirTransport(mir, codegen, compileTrustedMir) {
+  try {
+    return compileTrustedMir(mir, codegen);
+  } catch (cause) {
+    if (cause instanceof OndaCompileError) throw cause;
+    throw new OndaCompileError([{
+      stage: "codegen",
+      code: 0,
+      message: cause instanceof Error ? cause.message : String(cause),
+      file: null,
+      line: 0,
+      column: 0,
+      end_line: 0,
+      end_column: 0,
+      trace: [],
+    }], { cause });
+  }
+}
+
+function diagnosticsFromFrontend(error) {
+  const encoded = typeof error === "string" ? error : error?.message;
+  if (typeof encoded === "string") {
+    try {
+      const diagnostics = JSON.parse(encoded);
+      if (Array.isArray(diagnostics)) {
+        return new OndaCompileError(diagnostics, { cause: error });
+      }
+    } catch {}
+  }
+  return new OndaCompileError([{
+    stage: "frontend",
+    code: 0,
+    message: encoded ?? String(error),
+    file: null,
+    line: 0,
+    column: 0,
+    end_line: 0,
+    end_column: 0,
+    trace: [],
+  }], { cause: error });
+}
+
+function configurationError(message) {
+  return new OndaCompileError([{
+    stage: "configuration",
+    code: 0,
+    message,
+    file: null,
+    line: 0,
+    column: 0,
+    end_line: 0,
+    end_column: 0,
+    trace: [],
+  }]);
+}
+
+function normalizeDiagnostics(diagnostics) {
+  if (!Array.isArray(diagnostics)) return [];
+  return diagnostics.map((diagnostic) => ({
+    stage: String(diagnostic?.stage ?? "unknown"),
+    code: Number.isInteger(diagnostic?.code) ? diagnostic.code : 0,
+    message: String(diagnostic?.message ?? "compilation failed"),
+    file: typeof diagnostic?.file === "string" ? diagnostic.file : null,
+    line: Number.isInteger(diagnostic?.line) ? diagnostic.line : 0,
+    column: Number.isInteger(diagnostic?.column) ? diagnostic.column : 0,
+    end_line: Number.isInteger(diagnostic?.end_line) ? diagnostic.end_line : 0,
+    end_column: Number.isInteger(diagnostic?.end_column) ? diagnostic.end_column : 0,
+    trace: Array.isArray(diagnostic?.trace)
+      ? diagnostic.trace.map((entry) => String(entry))
+      : [],
+  }));
+}

package/src/worker.d.ts

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

package/src/worker.js

@@ -0,0 +1,68 @@
+import { createCompiler } from "./index.js";
+
+let compilerPromise;
+
+globalThis.addEventListener("message", async (event) => {
+  const message = event.data ?? {};
+  const requestId = message.requestId;
+  try {
+    if (message.type === "initialize") {
+      await compiler(message.frontendWasm);
+      respond(requestId, null);
+      return;
+    }
+    if (message.type === "compileSource") {
+      const artifact = await (await compiler()).compileSource(
+        message.source,
+        message.options,
+      );
+      respond(requestId, artifact, [artifact.wasm.buffer]);
+      return;
+    }
+    if (message.type === "compileProject") {
+      const artifact = await (await compiler()).compileProject(
+        message.project,
+        message.options,
+      );
+      respond(requestId, artifact, [artifact.wasm.buffer]);
+      return;
+    }
+    if (message.type === "lspMessage") {
+      const responses = await (await compiler()).sendLspMessage(message.message);
+      respond(requestId, responses);
+      return;
+    }
+    if (message.type === "lspAnalysisOptions") {
+      await (await compiler()).setLspAnalysisOptions(message.options);
+      respond(requestId, null);
+      return;
+    }
+    if (message.type === "dispose") {
+      if (compilerPromise) await (await compilerPromise).dispose();
+      respond(requestId, null);
+      globalThis.close();
+      return;
+    }
+    throw new Error(`unknown compiler worker request '${String(message.type)}'`);
+  } catch (error) {
+    globalThis.postMessage({
+      type: "error",
+      requestId,
+      error: {
+        name: error?.name ?? "Error",
+        message: error?.message ?? String(error),
+        stack: error?.stack,
+        diagnostics: error?.diagnostics,
+      },
+    });
+  }
+});
+
+function compiler(frontendWasm) {
+  compilerPromise ??= createCompiler({ frontendWasm });
+  return compilerPromise;
+}
+
+function respond(requestId, value, transfer = []) {
+  globalThis.postMessage({ type: "result", requestId, value }, transfer);
+}