@swiftbrowser/wasm-compiler 0.0.0-stage → 0.8.0

package/dist/node/plugin-executable.js

@@ -0,0 +1,97 @@
+// A macro plugin built as WebAssembly, run as the executable plugin a native
+// compiler spawns (`-load-plugin-executable`): `node plugin-executable.js
+// <plugin.wasm>`. The compiler's messages arrive on stdin and the replies go
+// to stdout, framed alike (an 8-byte little-endian length, then JSON), and
+// each message is handed to the module's `swift_wasm_macro_v1_pump`, as the
+// WebAssembly compiler's host does (../plugins.ts). The kit's macros reach a
+// native toolchain this way (the CLI's kit.ts), the same file on every host.
+import { readFileSync, readSync, realpathSync, writeSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { brotliDecompressSync } from 'node:zlib';
+import { ConsoleStdout, WASI, wasi } from '@bjorn3/browser_wasi_shim';
+const HEADER = 8;
+/** Stdin the executable fills with one message before each pump. */
+class MessageInput extends ConsoleStdout {
+    queue = new Uint8Array();
+    constructor() {
+        super(() => { });
+    }
+    set(bytes) {
+        this.queue = bytes;
+    }
+    fd_read(size) {
+        const data = this.queue.slice(0, size);
+        this.queue = this.queue.slice(data.length);
+        return { ret: wasi.ERRNO_SUCCESS, data };
+    }
+}
+/** Stdin, stdout and stderr, read and written synchronously: the compiler waits on each reply. */
+export const processStreams = {
+    read: (buffer, offset, length) => readSync(0, buffer, offset, length, null),
+    write: (bytes) => {
+        for (let written = 0; written < bytes.length;)
+            written += writeSync(1, bytes, written);
+    },
+    error: (bytes) => {
+        for (let written = 0; written < bytes.length;)
+            written += writeSync(2, bytes, written);
+    },
+};
+/** The plugin's module: a `.wasm` file, or a brotli-compressed `.wasm.br`. */
+export function pluginModule(file) {
+    const bytes = readFileSync(file);
+    return new WebAssembly.Module(file.endsWith('.br') ? brotliDecompressSync(bytes) : bytes);
+}
+/**
+ * Serves the compiler's messages until it closes the pipe or sends the empty
+ * message that asks a plugin to finish; returns the exit code.
+ */
+export function servePlugin(module, name, streams = processStreams) {
+    const stdin = new MessageInput();
+    const shim = new WASI([name], [], [stdin, new ConsoleStdout(streams.write), new ConsoleStdout(streams.error)], { debug: false });
+    const instance = new WebAssembly.Instance(module, { wasi_snapshot_preview1: shim.wasiImport });
+    // `main` installs the message handler and returns.
+    const code = shim.start(instance);
+    if (code !== 0)
+        return code;
+    const pump = instance.exports['swift_wasm_macro_v1_pump'];
+    if (!pump) {
+        streams.error(new TextEncoder().encode(`${name}: not a macro plugin built as WebAssembly (no swift_wasm_macro_v1_pump)\n`));
+        return 1;
+    }
+    const readExactly = (size) => {
+        const buffer = new Uint8Array(size);
+        for (let offset = 0; offset < size;) {
+            const count = streams.read(buffer, offset, size - offset);
+            if (count === 0)
+                return null;
+            offset += count;
+        }
+        return buffer;
+    };
+    for (;;) {
+        const header = readExactly(HEADER);
+        if (!header)
+            return 0;
+        const size = Number(new DataView(header.buffer).getBigUint64(0, true));
+        if (size === 0)
+            return 0;
+        const body = readExactly(size);
+        if (!body)
+            return 0;
+        const message = new Uint8Array(HEADER + size);
+        message.set(header);
+        message.set(body, HEADER);
+        stdin.set(message);
+        pump();
+    }
+}
+// Run as a script (through a link, too: npm links workspaces).
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const file = process.argv[2];
+    if (!file) {
+        process.stderr.write('usage: plugin-executable <plugin.wasm>\n');
+        process.exit(2);
+    }
+    process.exit(servePlugin(pluginModule(file), file));
+}

package/dist/node/tools.d.ts

@@ -0,0 +1,24 @@
+import type { ToolName } from '../driver.js';
+/** `<tool>.wasm` in `dir`, or else its brotli-compressed `<tool>.wasm.br`. */
+export declare function toolFile(dir: string, tool: ToolName): string;
+/** Where @swiftbrowser/wasm-tools keeps the tools, when it is installed with them. */
+export declare function packagedToolsDir(): string;
+/**
+ * The tools in `dir`, or else in the installed @swiftbrowser/wasm-tools:
+ * the compiler and the linker, and clang for C targets when the tools have it.
+ */
+export declare function findTools(dir?: string): Record<'swift-frontend' | 'wasm-ld', string> & {
+    clang?: string;
+};
+/**
+ * The macro plugins built as WebAssembly in `<dir>/plugins`
+ * (toolchain/build-plugins.sh): module name → file, `.wasm` or `.wasm.br`.
+ */
+export declare function findPlugins(dir?: string): Record<string, string>;
+/**
+ * PackageDescription built for wasm32-wasip1 in `<dir>/manifest-api`
+ * (toolchain/build-manifest-api.sh): the directory with
+ * `PackageDescription.swiftmodule` and `libPackageDescription.a` that a
+ * manifest is compiled against and linked with; null when the tools have none.
+ */
+export declare function findManifestApi(dir?: string): string | null;

package/dist/node/tools.js

@@ -0,0 +1,66 @@
+// Where the WebAssembly tools are on this machine: a directory of
+// `<tool>.wasm` (a build's toolchain/install-tools.sh output), or the
+// brotli-compressed `<tool>.wasm.br` @swiftbrowser/wasm-tools installs.
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/** `<tool>.wasm` in `dir`, or else its brotli-compressed `<tool>.wasm.br`. */
+export function toolFile(dir, tool) {
+    const file = path.resolve(dir, `${tool}.wasm`);
+    if (existsSync(file) || !existsSync(`${file}.br`))
+        return file;
+    return `${file}.br`;
+}
+/** Where @swiftbrowser/wasm-tools keeps the tools, when it is installed with them. */
+export function packagedToolsDir() {
+    let dir;
+    try {
+        dir = path.dirname(createRequire(import.meta.url).resolve('@swiftbrowser/wasm-tools/package.json'));
+    }
+    catch {
+        throw new Error('no WebAssembly tools: pass --tools, set SWIFTBROWSER_WASM_TOOLS or install @swiftbrowser/wasm-tools');
+    }
+    if (!existsSync(path.join(dir, 'swift-frontend.wasm.br'))) {
+        throw new Error(`@swiftbrowser/wasm-tools in ${dir} has no tools; in this repository, run \`node fetch.mjs\` there`);
+    }
+    return dir;
+}
+/**
+ * The tools in `dir`, or else in the installed @swiftbrowser/wasm-tools:
+ * the compiler and the linker, and clang for C targets when the tools have it.
+ */
+export function findTools(dir) {
+    const root = dir ?? packagedToolsDir();
+    const clang = toolFile(root, 'clang');
+    return {
+        'swift-frontend': toolFile(root, 'swift-frontend'),
+        'wasm-ld': toolFile(root, 'wasm-ld'),
+        ...(existsSync(clang) ? { clang } : {}),
+    };
+}
+/**
+ * The macro plugins built as WebAssembly in `<dir>/plugins`
+ * (toolchain/build-plugins.sh): module name → file, `.wasm` or `.wasm.br`.
+ */
+export function findPlugins(dir) {
+    const root = path.join(dir ?? packagedToolsDir(), 'plugins');
+    if (!existsSync(root))
+        return {};
+    const plugins = {};
+    for (const name of readdirSync(root).sort()) {
+        const match = /^(.+)\.wasm(\.br)?$/.exec(name);
+        if (match && !plugins[match[1]])
+            plugins[match[1]] = path.join(root, name);
+    }
+    return plugins;
+}
+/**
+ * PackageDescription built for wasm32-wasip1 in `<dir>/manifest-api`
+ * (toolchain/build-manifest-api.sh): the directory with
+ * `PackageDescription.swiftmodule` and `libPackageDescription.a` that a
+ * manifest is compiled against and linked with; null when the tools have none.
+ */
+export function findManifestApi(dir) {
+    const root = path.join(dir ?? packagedToolsDir(), 'manifest-api');
+    return existsSync(path.join(root, 'libPackageDescription.a')) && existsSync(path.join(root, 'PackageDescription.swiftmodule')) ? root : null;
+}

package/dist/node/wasi-host.d.ts

@@ -0,0 +1,53 @@
+import { type ToolName } from '../driver.js';
+import type { Host, RunResult } from '../host.js';
+export interface WasiHostOptions {
+    /**
+     * The tool modules by name: `swift-frontend.wasm`, `wasm-ld.wasm`, or
+     * their brotli-compressed `.wasm.br` (as @swiftbrowser/wasm-tools has them).
+     */
+    tools: Partial<Record<ToolName, string>>;
+    /** Guest directory → host directory. */
+    mounts: Record<string, string>;
+    /** The Swift SDK's `wasm32-unknown-wasip1` directory, as a guest path. */
+    sdkRoot: string;
+    /** The worker's native stack, in MB. */
+    stackSizeMb?: number;
+    /**
+     * A host directory for Clang's module cache, mounted at /module-cache and
+     * kept between jobs, so SwiftShims and wasi-libc's modules are built once.
+     * Defaults to a temporary directory for the host's lifetime.
+     */
+    moduleCacheDir?: string;
+    /**
+     * Macro plugins built as WebAssembly, by the guest path the compiler names
+     * in `-load-plugin-executable` (under a mounted directory, since the
+     * compiler checks the file) → the module's host path (`.wasm` or `.wasm.br`).
+     */
+    plugins?: Record<string, string>;
+}
+export interface WasiCommand {
+    module: WebAssembly.Module;
+    /** argv, the program name first. */
+    args: readonly string[];
+    /** Guest directory → host directory. */
+    mounts: Record<string, string>;
+    env?: Record<string, string>;
+    /** The worker's native stack, in MB. */
+    stackSizeMb?: number;
+    /** Macro plugins by guest path (`WasiHostOptions.plugins`), compiled. */
+    plugins?: Record<string, WebAssembly.Module>;
+}
+/**
+ * Runs a WASI command in a worker thread and returns its exit status and its
+ * stdout and stderr, interleaved. A host directory is mounted at /tmp (and
+ * TMPDIR points there) for the command's temporary files, and an empty one at
+ * / unless a mount covers it: the Swift frontend makes / its working
+ * directory, which needs a preopened directory there.
+ */
+export declare function runWasiCommand(command: WasiCommand): Promise<RunResult>;
+/** The Node host: the tools in worker threads, and macro plugins that can be added as a build makes them. */
+export interface WasiHost extends Host {
+    /** A macro plugin built after the host was made: its guest path (as `-load-plugin-executable` names it) and its file. */
+    addPlugin(guest: string, file: string): void;
+}
+export declare function wasiHost(options: WasiHostOptions): WasiHost;

package/dist/node/wasi-host.js

@@ -0,0 +1,189 @@
+// The WebAssembly tools as a host, under Node's WASI: step 1.5 of
+// docs/in-browser-compiler.md. Host directories are mounted at guest paths
+// (/sdk, /work, ...), and every path the jobs name is a guest path.
+//
+// Each tool runs in a worker thread. A worker gets its own, larger native
+// stack: compiled WebAssembly frames live on it, and the frontend's type
+// checker and the SIL passes recurse deeply. The tool's own shadow stack is
+// in its linear memory and was sized when it was linked. A compiled module
+// is kept per tool and sent to each worker, so it is compiled once.
+import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import v8 from 'node:v8';
+import { Worker } from 'node:worker_threads';
+import { brotliDecompress } from 'node:zlib';
+import { sdkPaths } from '../driver.js';
+// Node 22's V8 crashes in a garbage collection that walks the stack while a
+// WebAssembly module is calling node:wasi through V8's fast API calls
+// (InnerPointerToCodeCache::GetCacheEntry, from IterateTurbofanOptimizedFrame);
+// the Swift frontend triggers it on every real compile. Without fast API
+// calls it runs correctly. V8 flags are per process, so this applies to the
+// workers too.
+v8.setFlagsFromString('--no-turbo-fast-api-calls');
+// Runs one WASI command and reports its exit status. CommonJS, evaluated as
+// the worker's script, so it runs the same from the TypeScript sources (in
+// tests) and from dist.
+const WORKER = `
+// Each worker would print node:wasi's ExperimentalWarning again.
+const emitWarning = process.emitWarning;
+process.emitWarning = (warning, ...rest) => {
+  if (String(warning).startsWith('WASI is an experimental feature')) return;
+  emitWarning.call(process, warning, ...rest);
+};
+const { workerData, parentPort } = require('node:worker_threads');
+const { WASI } = require('node:wasi');
+const fs = require('node:fs');
+const { module, args, env, preopens, outputFile, plugins, pluginHostUrl } = workerData;
+const fd = fs.openSync(outputFile, 'w');
+(async () => {
+  const wasi = new WASI({ version: 'preview1', args, env, preopens, stdin: 0, stdout: fd, stderr: fd, returnOnExit: true });
+  const imports = wasi.getImportObject();
+  // A program may close its stdio (a Swift manifest fcloses stdout after
+  // writing its description there). The descriptors are the process's, shared
+  // with every thread: closing one frees its number for another thread's next
+  // open, which this worker's own close would then close. So closing 0-2 is
+  // a no-op; what was written is already in the file.
+  const preview1 = imports.wasi_snapshot_preview1;
+  const fdClose = preview1.fd_close;
+  preview1.fd_close = (descriptor) => (descriptor <= 2 ? 0 : fdClose(descriptor));
+  // The Swift frontend runs macro plugins through the host (plugins.ts).
+  let host = null;
+  if (WebAssembly.Module.imports(module).some((entry) => entry.module === 'swiftbrowser')) {
+    const { pluginHost } = await import(pluginHostUrl);
+    host = pluginHost({ module: (path) => (plugins && plugins[path]) || null, onStderr: (text) => fs.writeSync(fd, text) });
+    Object.assign(imports, host.imports);
+  }
+  const instance = new WebAssembly.Instance(module, imports);
+  if (host) host.bind(instance);
+  const exitCode = wasi.start(instance);
+  const memory = instance.exports.memory;
+  parentPort.postMessage({ exitCode, memoryBytes: memory ? memory.buffer.byteLength : undefined });
+})().catch((error) => {
+  parentPort.postMessage({ exitCode: 1, error: String(error && error.stack || error) });
+}).finally(() => {
+  fs.closeSync(fd);
+});
+`;
+// The plugin host the worker imports: plugins.js next to this module's
+// directory, or, when this runs from the TypeScript sources (the tests), the
+// build's copy, since a plain worker cannot import TypeScript.
+const PLUGIN_HOST_URL = import.meta.url.endsWith('.ts')
+    ? new URL('../../dist/plugins.js', import.meta.url).href
+    : new URL('../plugins.js', import.meta.url).href;
+/**
+ * Runs a WASI command in a worker thread and returns its exit status and its
+ * stdout and stderr, interleaved. A host directory is mounted at /tmp (and
+ * TMPDIR points there) for the command's temporary files, and an empty one at
+ * / unless a mount covers it: the Swift frontend makes / its working
+ * directory, which needs a preopened directory there.
+ */
+export async function runWasiCommand(command) {
+    const scratch = await mkdtemp(path.join(tmpdir(), 'wasmc-'));
+    const outputFile = path.join(scratch, 'output');
+    const tmp = path.join(scratch, 'tmp');
+    const root = path.join(scratch, 'root');
+    await mkdir(tmp);
+    await mkdir(root);
+    try {
+        const message = await new Promise((resolve, reject) => {
+            const worker = new Worker(WORKER, {
+                eval: true,
+                workerData: {
+                    module: command.module,
+                    args: command.args,
+                    env: { TMPDIR: '/tmp', ...command.env },
+                    preopens: { '/': root, ...command.mounts, '/tmp': tmp },
+                    outputFile,
+                    plugins: command.plugins ?? {},
+                    pluginHostUrl: PLUGIN_HOST_URL,
+                },
+                resourceLimits: { stackSizeMb: command.stackSizeMb ?? 256 },
+            });
+            let settled = false;
+            worker.once('message', (m) => {
+                settled = true;
+                resolve(m);
+            });
+            worker.once('error', reject);
+            worker.once('exit', (code) => {
+                if (!settled)
+                    resolve({ exitCode: code || 1, error: `${command.args[0]}: the worker exited with ${code}` });
+            });
+        });
+        const output = await readFile(outputFile, 'utf8');
+        return {
+            exitCode: message.exitCode,
+            output: message.error ? `${output}${message.error}\n` : output,
+            ...(message.memoryBytes !== undefined ? { memoryBytes: message.memoryBytes } : {}),
+        };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** Modules compiled in this process, by file, size and modification time. */
+const compiled = new Map();
+/** A module from a `.wasm` file, or a brotli-compressed `.wasm.br`; compiled once per process while the file is unchanged. */
+async function compileFile(file) {
+    const info = await stat(file);
+    const key = `${path.resolve(file)}\0${info.size}\0${info.mtimeMs}`;
+    let module = compiled.get(key);
+    if (!module) {
+        module = readFile(file).then(async (bytes) => WebAssembly.compile(file.endsWith('.br') ? await promisify(brotliDecompress)(bytes) : bytes));
+        // A failed compile is not kept: the next run tries again.
+        module.catch(() => compiled.delete(key));
+        compiled.set(key, module);
+    }
+    return module;
+}
+export function wasiHost(options) {
+    let moduleCache;
+    const moduleCacheDir = () => (moduleCache ??= options.moduleCacheDir
+        ? mkdir(options.moduleCacheDir, { recursive: true }).then(() => options.moduleCacheDir)
+        : mkdtemp(path.join(tmpdir(), 'wasmc-module-cache-')));
+    const modules = new Map();
+    const moduleFor = (tool) => {
+        let module = modules.get(tool);
+        if (!module) {
+            const file = options.tools[tool];
+            if (!file)
+                throw new Error(`no WebAssembly module for ${tool}`);
+            module = compileFile(file);
+            modules.set(tool, module);
+        }
+        return module;
+    };
+    // The plugins, those added since the host was made (`addPlugin`)
+    // included; each module is compiled once (compileFile).
+    const pluginFiles = { ...options.plugins };
+    const compiledPlugins = () => Promise.all(Object.entries(pluginFiles).map(async ([guest, file]) => [guest, await compileFile(file)]))
+        .then((entries) => Object.fromEntries(entries));
+    const toHost = (guest) => {
+        const mount = Object.keys(options.mounts)
+            .filter((dir) => guest === dir || guest.startsWith(`${dir}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (mount === undefined)
+            throw new Error(`${guest} is not under a mounted directory`);
+        return path.join(options.mounts[mount], guest.slice(mount.length));
+    };
+    return {
+        description: `WebAssembly tools (${Object.values(options.tools).join(', ')})`,
+        sdk: sdkPaths(options.sdkRoot),
+        moduleCachePath: '/module-cache',
+        readFile: (file) => readFile(toHost(file)),
+        async run(tool, args) {
+            const module = await moduleFor(tool);
+            const mounts = { ...options.mounts, '/module-cache': await moduleCacheDir() };
+            return runWasiCommand({
+                module, args: [tool, ...args], mounts,
+                ...(options.stackSizeMb ? { stackSizeMb: options.stackSizeMb } : {}),
+                ...(tool === 'swift-frontend' && Object.keys(pluginFiles).length > 0 ? { plugins: await compiledPlugins() } : {}),
+            });
+        },
+        addPlugin(guest, file) {
+            pluginFiles[guest] = file;
+        },
+    };
+}

package/dist/object.d.ts

@@ -0,0 +1,5 @@
+/**
+ * An object defining the global `symbol` as `data`, in a segment named
+ * `.data.<symbol>` aligned to `2 ** alignLog2` bytes.
+ */
+export declare function dataObject(symbol: string, data: Uint8Array, alignLog2?: number): Uint8Array<ArrayBuffer>;

package/dist/object.js

@@ -0,0 +1,67 @@
+// A relocatable WebAssembly object holding one global data symbol: what
+// clang makes of `.incbin` in an assembly file, without clang. The CLI stages
+// Foundation's ICU data this way (packages/cli/src/icu.ts), and wasm-ld links
+// it like any other object.
+//
+// The layout is clang's: the linear memory imported as env.__linear_memory,
+// one active data segment at offset 0, and a `linking` section (version 2)
+// with the symbol table and the segment's name and alignment.
+const WASM_MAGIC = [0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00];
+const SECTION = { custom: 0, import: 2, data: 11, dataCount: 12 };
+const LINKING = { version: 2, segmentInfo: 5, symbolTable: 8 };
+const SYMTAB_DATA = 1;
+const PAGE = 65536;
+function uleb(value) {
+    const out = [];
+    do {
+        let byte = value & 0x7f;
+        value = Math.floor(value / 128);
+        if (value !== 0)
+            byte |= 0x80;
+        out.push(byte);
+    } while (value !== 0);
+    return out;
+}
+function name(text) {
+    const bytes = [...new TextEncoder().encode(text)];
+    return [...uleb(bytes.length), ...bytes];
+}
+function section(id, body) {
+    const head = [id, ...uleb(body.length)];
+    const out = new Uint8Array(head.length + body.length);
+    out.set(head);
+    out.set(body, head.length);
+    return out;
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/**
+ * An object defining the global `symbol` as `data`, in a segment named
+ * `.data.<symbol>` aligned to `2 ** alignLog2` bytes.
+ */
+export function dataObject(symbol, data, alignLog2 = 4) {
+    const memoryImport = [...uleb(1), ...name('env'), ...name('__linear_memory'), 0x02, 0x00, ...uleb(Math.ceil(data.length / PAGE))];
+    const segmentHead = [...uleb(1), 0x00, 0x41, 0x00, 0x0b, ...uleb(data.length)];
+    const symbolTable = [...uleb(1), SYMTAB_DATA, ...uleb(0), ...name(symbol), ...uleb(0), ...uleb(0), ...uleb(data.length)];
+    const segmentInfo = [...uleb(1), ...name(`.data.${symbol}`), ...uleb(alignLog2), ...uleb(0)];
+    const linking = [
+        ...name('linking'),
+        ...uleb(LINKING.version),
+        LINKING.symbolTable, ...uleb(symbolTable.length), ...symbolTable,
+        LINKING.segmentInfo, ...uleb(segmentInfo.length), ...segmentInfo,
+    ];
+    return concat([
+        new Uint8Array(WASM_MAGIC),
+        section(SECTION.import, memoryImport),
+        section(SECTION.dataCount, uleb(1)),
+        section(SECTION.data, concat([new Uint8Array(segmentHead), data])),
+        section(SECTION.custom, linking),
+    ]);
+}

package/dist/plugins.d.ts

@@ -0,0 +1,15 @@
+export interface PluginHostOptions {
+    /** The compiled plugin for a guest path, or null when there is none. */
+    module(path: string): WebAssembly.Module | null;
+    /** What plugins write to stderr (their own diagnostics and crashes). */
+    onStderr?: (text: string) => void;
+}
+/** The `swiftbrowser` imports, and the hook that gives them the compiler's memory. */
+export interface PluginHost {
+    imports: {
+        swiftbrowser: Record<string, (...args: number[]) => number | void>;
+    };
+    /** Call with the compiler's instance before it runs. */
+    bind(instance: WebAssembly.Instance): void;
+}
+export declare function pluginHost(options: PluginHostOptions): PluginHost;

package/dist/plugins.js

@@ -0,0 +1,147 @@
+// Macro plugins for the WebAssembly compiler. A native compiler runs an
+// executable plugin as a process and talks to it over a pipe; under WASI the
+// compiler asks the host instead (toolchain/patches/swift, PluginRegistry.cpp),
+// through four imports of the `swiftbrowser` module:
+//
+//   plugin_spawn(path, length) -> handle   start the plugin at a guest path
+//   plugin_write(handle, buffer, size)      the compiler's messages to it
+//   plugin_read(handle, buffer, size)       its replies
+//   plugin_close(handle)
+//
+// The plugin is a WebAssembly module built with swift-syntax for WASI
+// (toolchain/build-plugins.sh). Its `main` installs a message handler and
+// returns; the host then calls its `swift_wasm_macro_v1_pump` export once per
+// message, with the message on its stdin, and takes the reply from its
+// stdout. Messages are framed as on the pipe: an 8-byte little-endian length,
+// then that many bytes of JSON. Everything is synchronous, so a plugin runs
+// in the compiler's own thread, in Node and in a browser worker alike.
+import { ConsoleStdout, Fd, WASI, wasi } from '@bjorn3/browser_wasi_shim';
+/** Stdin the host fills before each pump. */
+class MessageInput extends ConsoleStdout {
+    queue = new Uint8Array();
+    constructor() {
+        super(() => { });
+    }
+    push(bytes) {
+        const next = new Uint8Array(this.queue.length + bytes.length);
+        next.set(this.queue);
+        next.set(bytes, this.queue.length);
+        this.queue = next;
+    }
+    fd_read(size) {
+        const data = this.queue.slice(0, size);
+        this.queue = this.queue.slice(data.length);
+        return { ret: wasi.ERRNO_SUCCESS, data };
+    }
+}
+/** Bytes appended to and taken from the front of a buffer. */
+class ByteQueue {
+    bytes = new Uint8Array(0);
+    get length() {
+        return this.bytes.length;
+    }
+    push(data) {
+        const next = new Uint8Array(this.bytes.length + data.length);
+        next.set(this.bytes);
+        next.set(data, this.bytes.length);
+        this.bytes = next;
+    }
+    take(count) {
+        const taken = this.bytes.slice(0, count);
+        this.bytes = this.bytes.slice(taken.length);
+        return taken;
+    }
+    peek() {
+        return this.bytes;
+    }
+}
+const HEADER = 8;
+export function pluginHost(options) {
+    let memory = null;
+    const plugins = new Map();
+    let next = 3;
+    const bytes = (pointer, size) => new Uint8Array(memory.buffer, pointer, size);
+    const decoder = new TextDecoder();
+    const spawn = (path) => {
+        const module = options.module(path);
+        if (!module)
+            return -1;
+        const stdin = new MessageInput();
+        const replies = new ByteQueue();
+        const stderr = (data) => options.onStderr?.(decoder.decode(data));
+        const fds = [stdin, new ConsoleStdout((data) => replies.push(data)), new ConsoleStdout(stderr)];
+        const shim = new WASI([path], [], fds, { debug: false });
+        const instance = new WebAssembly.Instance(module, { wasi_snapshot_preview1: shim.wasiImport });
+        // `main` installs the message handler and returns, which exits.
+        const code = shim.start(instance);
+        if (code !== 0)
+            return -1;
+        const handle = next++;
+        plugins.set(handle, { path, instance, stdin, pending: new ByteQueue(), replies });
+        return handle;
+    };
+    // Hands every complete message the compiler wrote to the plugin, one pump each.
+    const deliver = (plugin) => {
+        const pump = plugin.instance.exports['swift_wasm_macro_v1_pump'];
+        for (;;) {
+            const head = plugin.pending.peek();
+            if (head.length < HEADER)
+                return;
+            const view = new DataView(head.buffer, head.byteOffset, head.byteLength);
+            const size = Number(view.getBigUint64(0, true));
+            // An empty message asks the plugin to finish: nothing to pump.
+            if (size === 0) {
+                plugin.pending.take(HEADER);
+                continue;
+            }
+            if (head.length < HEADER + size)
+                return;
+            plugin.stdin.push(plugin.pending.take(HEADER + size));
+            pump();
+        }
+    };
+    return {
+        bind(instance) {
+            memory = instance.exports['memory'];
+        },
+        imports: {
+            swiftbrowser: {
+                plugin_spawn(pointer, size) {
+                    try {
+                        return spawn(decoder.decode(bytes(pointer, size)));
+                    }
+                    catch (error) {
+                        options.onStderr?.(`plugin: ${String(error.stack ?? error)}\n`);
+                        return -1;
+                    }
+                },
+                plugin_write(handle, pointer, size) {
+                    const plugin = plugins.get(handle);
+                    if (!plugin)
+                        return -1;
+                    plugin.pending.push(bytes(pointer, size).slice());
+                    try {
+                        deliver(plugin);
+                    }
+                    catch (error) {
+                        options.onStderr?.(`${plugin.path}: ${String(error.stack ?? error)}\n`);
+                        plugins.delete(handle);
+                        return -1;
+                    }
+                    return size;
+                },
+                plugin_read(handle, pointer, size) {
+                    const plugin = plugins.get(handle);
+                    if (!plugin)
+                        return -1;
+                    const reply = plugin.replies.take(size);
+                    bytes(pointer, reply.length).set(reply);
+                    return reply.length;
+                },
+                plugin_close(handle) {
+                    plugins.delete(handle);
+                },
+            },
+        },
+    };
+}