@swiftbrowser/web 0.1.0

package/src/wasm.ts

@@ -0,0 +1,400 @@
+/**
+ * Loads a SwiftBrowser app compiled to Wasm (a WASI command) and bridges its
+ * ops buffer / event exports to the renderer. See docs/ops-protocol.md,
+ * "Events (renderer → Swift)", "Phase 2 additions" and "Executor" (Phase 4).
+ *
+ * Phase 4 modules export `sb_run_jobs(now_ms) -> delay_ms`, which runs the
+ * cooperative executor (Task, .task, Task.sleep). The host drives it: once
+ * after `_start`, after every event, and whenever the returned delay elapses
+ * (a single `setTimeout`, clamped to at least 4 ms); the pending ops are
+ * read and applied after every call. See `JobScheduler`.
+ */
+
+import { ConsoleStdout, Directory, type Fd, File, OpenFile, PreopenDirectory, WASI, WASIProcExit, type Inode } from '@bjorn3/browser_wasi_shim';
+import { isOp, type ElementId, type Op, type RendererEvent } from './protocol';
+
+export type OpsSink = (ops: Op[]) => void;
+
+export interface AppHandle {
+  /** Forward a tap on element `id` to Swift (`sb_event`) and apply the resulting ops. */
+  sendEvent(id: ElementId): void;
+  /**
+   * Deliver a JSON event through `sb_alloc` + `sb_event_json` and apply the
+   * resulting ops. Returns `false` (and does nothing) when the module only
+   * speaks the Phase 1 protocol. A `tap` event is routed to `sendEvent`.
+   */
+  sendEventJson(event: RendererEvent): boolean;
+  /** Whether the module exports `sb_alloc` and `sb_event_json`. */
+  readonly supportsJsonEvents: boolean;
+  /** Whether a `batch` event may be sent through `sendEventJson` (the Wasm runtime; not the mocks). */
+  readonly supportsBatchEvents?: boolean;
+  /**
+   * The current `@State` snapshot (`sb_state_ptr`/`sb_state_len`) as a JSON
+   * string, or `null` when the module has no snapshot support or no state.
+   */
+  snapshotState(): string | null;
+  /**
+   * Phase 4: run the module's executor now (`sb_run_jobs(performance.now())`),
+   * apply the resulting ops and (re)schedule the next run from the returned
+   * delay. Returns that delay in ms (`-1`: nothing pending), or `null` when
+   * the module has no executor export.
+   */
+  runJobs(): number | null;
+  /** Whether the module exports `sb_run_jobs`. */
+  readonly supportsJobs: boolean;
+  /** Exit code reported by `_start` (0 when `main` returned normally). */
+  readonly exitCode: number;
+  readonly instance: WebAssembly.Instance;
+}
+
+export interface LoadAppOptions {
+  /** `argv` passed to the WASI command; defaults to `["Counter"]`. */
+  args?: string[];
+  /** `KEY=VALUE` environment entries; defaults to none. */
+  env?: string[];
+  /** Log every WASI syscall to the console (the shim's own tracing). */
+  debug?: boolean;
+  /**
+   * Phase 11: the app's resources, mounted read-only at `/bundle` (path inside
+   * the bundle → bytes); `Bundle.main` reads them. Nothing is mounted without it.
+   */
+  bundle?: ReadonlyMap<string, Uint8Array>;
+  /** Phase 11: receives the app's `UserDefaults` whenever they change (a `defaults` op); the op never reaches `onOps`. */
+  onDefaults?: (values: Record<string, unknown>) => void;
+}
+
+/** An in-memory WASI directory tree from `path → bytes` (paths `/`-separated, no leading slash). */
+export function bundleDirectory(files: ReadonlyMap<string, Uint8Array>): Directory {
+  const root = new Directory(new Map<string, Inode>());
+  for (const [filePath, bytes] of files) {
+    const parts = filePath.split('/').filter((part) => part !== '' && part !== '.' && part !== '..');
+    if (parts.length === 0) continue;
+    let dir = root;
+    for (const part of parts.slice(0, -1)) {
+      const existing = dir.contents.get(part);
+      let next: Directory;
+      if (existing instanceof Directory) {
+        next = existing;
+      } else {
+        next = new Directory(new Map<string, Inode>());
+        dir.contents.set(part, next);
+      }
+      dir = next;
+    }
+    dir.contents.set(parts[parts.length - 1]!, new File(bytes, { readonly: true }));
+  }
+  return root;
+}
+
+interface SwiftBrowserExports {
+  memory: WebAssembly.Memory;
+  _start?: () => unknown;
+  _initialize?: () => unknown;
+  sb_event: (id: number) => void;
+  sb_ops_ptr: () => number;
+  sb_ops_len: () => number;
+  sb_ops_clear: () => void;
+  // Phase 2 (optional so Phase 1 modules still load).
+  sb_alloc?: (len: number) => number;
+  sb_event_json?: (ptr: number, len: number) => void;
+  sb_state_ptr?: () => number;
+  sb_state_len?: () => number;
+  // Phase 4 (optional).
+  sb_run_jobs?: (nowMs: number) => number;
+}
+
+const WASI_MODULE = 'wasi_snapshot_preview1';
+const REQUIRED_EXPORTS = ['memory', 'sb_event', 'sb_ops_ptr', 'sb_ops_len', 'sb_ops_clear'] as const;
+
+export class WasmLoadError extends Error {
+  override name = 'WasmLoadError';
+}
+
+/** `setTimeout` is clamped to this so a busy executor never spins the main thread. */
+export const MIN_JOB_DELAY_MS = 4;
+
+/** The timer surface `JobScheduler` uses (the window's by default; tests stub it). */
+export interface JobTimers {
+  now(): number;
+  setTimeout(callback: () => void, ms: number): number;
+  clearTimeout(handle: number): void;
+}
+
+const defaultTimers: JobTimers = {
+  now: () => performance.now(),
+  setTimeout: (callback, ms) => window.setTimeout(callback, ms),
+  clearTimeout: (handle) => window.clearTimeout(handle),
+};
+
+/**
+ * Drives a cooperative executor: `run(now)` runs the due jobs and returns the
+ * milliseconds until the next timer (`< 0`: none). `kick()` runs it right away
+ * and schedules the next run; there is only ever one pending timer, which
+ * every `kick` cancels and replaces, so a burst of events never piles up
+ * extra wake-ups. `apply()` is called after every run to drain the ops buffer.
+ */
+export class JobScheduler {
+  private timer: number | null = null;
+  /** How many times `run` was called (for tests and debugging). */
+  runs = 0;
+  /** The delay the last run returned (`-1` when nothing is pending). */
+  lastDelay = -1;
+  private disposed = false;
+
+  constructor(
+    private readonly run: (nowMs: number) => number,
+    private readonly apply: () => void,
+    private readonly timers: JobTimers = defaultTimers,
+    private readonly onError: (error: unknown) => void = (error) => console.error('[sb] sb_run_jobs failed', error),
+  ) {}
+
+  /** Run the executor now, apply its ops and reschedule. Returns the delay. */
+  kick(): number {
+    this.cancel();
+    if (this.disposed) return -1;
+    let delay = -1;
+    try {
+      const raw = this.run(this.timers.now());
+      delay = Number.isFinite(raw) ? raw : -1;
+      this.runs += 1;
+      this.apply();
+    } catch (error) {
+      this.onError(error);
+      delay = -1;
+    }
+    this.lastDelay = delay;
+    if (delay >= 0 && !this.disposed) {
+      this.timer = this.timers.setTimeout(() => {
+        this.timer = null;
+        this.kick();
+      }, Math.max(MIN_JOB_DELAY_MS, delay));
+    }
+    return delay;
+  }
+
+  /** Whether a timer is waiting to run the executor again. */
+  get pending(): boolean {
+    return this.timer !== null;
+  }
+
+  /** Cancel the pending timer (the next `kick` schedules again). */
+  cancel(): void {
+    if (this.timer !== null) {
+      this.timers.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Cancel and refuse further runs. */
+  dispose(): void {
+    this.disposed = true;
+    this.cancel();
+  }
+}
+
+export async function loadApp(
+  url: string,
+  onOps: OpsSink,
+  options: LoadAppOptions = {},
+): Promise<AppHandle> {
+  const module = await compile(url);
+  checkImports(module);
+
+  const fds: Fd[] = [
+    new OpenFile(new File([])), // stdin: empty
+    ConsoleStdout.lineBuffered((line) => console.log(`[wasm stdout] ${line}`)),
+    ConsoleStdout.lineBuffered((line) => console.error(`[wasm stderr] ${line}`)),
+  ];
+  if (options.bundle) {
+    // Preopened as fd 3; WASI libc resolves `/bundle/...` paths through it.
+    const root = bundleDirectory(options.bundle);
+    fds.push(new PreopenDirectory('/bundle', root.contents));
+  }
+  const wasi = new WASI(options.args ?? ['Counter'], options.env ?? [], fds, { debug: options.debug ?? false });
+
+  const instance = await WebAssembly.instantiate(module, {
+    [WASI_MODULE]: wasi.wasiImport,
+  });
+  const exports = instance.exports as unknown as SwiftBrowserExports;
+  for (const name of REQUIRED_EXPORTS) {
+    if (!(name in exports)) {
+      throw new WasmLoadError(`${url} does not export \`${name}\`; see docs/ops-protocol.md`);
+    }
+  }
+
+  // Run `main`. For a WASI command this is `_start`; it returns (or raises
+  // `proc_exit`) after `main` has mounted the root view and performed the
+  // first render pass into the pending buffer. The instance and its linear
+  // memory stay alive afterwards, so later `sb_event` calls are fine.
+  // A reactor-style build (`-mexec-model=reactor`) exposes `_initialize`
+  // instead; support it too.
+  let exitCode = 0;
+  if (typeof exports._start === 'function') {
+    try {
+      exitCode = wasi.start(instance as { exports: { memory: WebAssembly.Memory; _start: () => unknown } });
+    } catch (error) {
+      if (error instanceof WASIProcExit) {
+        exitCode = error.code;
+      } else {
+        throw error;
+      }
+    }
+  } else if (typeof exports._initialize === 'function') {
+    wasi.initialize(instance as { exports: { memory: WebAssembly.Memory; _initialize?: () => unknown } });
+  } else {
+    throw new WasmLoadError(`${url} exports neither \`_start\` nor \`_initialize\``);
+  }
+  if (exitCode !== 0) {
+    throw new WasmLoadError(`${url} exited with code ${exitCode}`);
+  }
+
+  const drain = (): void => {
+    let ops = readPendingOps(exports);
+    // Clear before applying so a renderer error never re-applies stale ops.
+    exports.sb_ops_clear();
+    if (ops.some((op) => op.op === 'defaults')) {
+      // The last `defaults` op of a batch holds the whole dictionary.
+      const latest = ops.filter((op) => op.op === 'defaults').pop();
+      if (latest && latest.op === 'defaults') options.onDefaults?.(latest.values);
+      ops = ops.filter((op) => op.op !== 'defaults');
+    }
+    if (ops.length > 0) onOps(ops);
+  };
+
+  const supportsJsonEvents =
+    typeof exports.sb_alloc === 'function' && typeof exports.sb_event_json === 'function';
+  const supportsSnapshot =
+    typeof exports.sb_state_ptr === 'function' && typeof exports.sb_state_len === 'function';
+  const supportsJobs = typeof exports.sb_run_jobs === 'function';
+
+  // Phase 4: the executor runs after the first ops and after every event; the
+  // scheduler's own timer covers sleeps and clocks in between.
+  const scheduler = supportsJobs ? new JobScheduler((now) => exports.sb_run_jobs!(now), drain) : null;
+  const runJobs = (): number | null => (scheduler ? scheduler.kick() : null);
+
+  const sendEvent = (id: ElementId): void => {
+    exports.sb_event(id | 0);
+    drain();
+    runJobs();
+  };
+
+  drain();
+  runJobs();
+
+  return {
+    instance,
+    exitCode,
+    supportsJsonEvents,
+    supportsBatchEvents: supportsJsonEvents,
+    supportsJobs,
+    runJobs,
+    sendEvent,
+    sendEventJson(event: RendererEvent): boolean {
+      if (event.type === 'tap') {
+        sendEvent(event.id);
+        return true;
+      }
+      if (!supportsJsonEvents) return false;
+      const bytes = encoder.encode(JSON.stringify(event));
+      const ptr = exports.sb_alloc!(bytes.byteLength) >>> 0;
+      // `memory.buffer` must be read after `sb_alloc`: allocating may grow
+      // linear memory and detach the previous ArrayBuffer.
+      const memory = exports.memory.buffer;
+      if (ptr + bytes.byteLength > memory.byteLength) {
+        throw new WasmLoadError(
+          `sb_alloc(${bytes.byteLength}) returned ${ptr}, outside linear memory (${memory.byteLength} bytes)`,
+        );
+      }
+      new Uint8Array(memory, ptr, bytes.byteLength).set(bytes);
+      exports.sb_event_json!(ptr, bytes.byteLength);
+      drain();
+      runJobs();
+      return true;
+    },
+    snapshotState(): string | null {
+      if (!supportsSnapshot) return null;
+      // `sb_state_ptr` refreshes the buffer, so call it before `sb_state_len`.
+      const ptr = exports.sb_state_ptr!() >>> 0;
+      const len = exports.sb_state_len!() >>> 0;
+      if (len === 0) return null;
+      const memory = exports.memory.buffer;
+      if (ptr + len > memory.byteLength) {
+        throw new WasmLoadError(
+          `sb_state_ptr/len (${ptr}, ${len}) point outside linear memory (${memory.byteLength} bytes)`,
+        );
+      }
+      return decoder.decode(new Uint8Array(memory, ptr, len));
+    },
+  };
+}
+
+async function compile(url: string): Promise<WebAssembly.Module> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new WasmLoadError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  const type = response.headers.get('content-type') ?? '';
+  if (typeof WebAssembly.compileStreaming === 'function' && type.includes('application/wasm')) {
+    return WebAssembly.compileStreaming(response);
+  }
+  // Fall back for servers that mislabel the MIME type.
+  const bytes = await response.arrayBuffer();
+  if (bytes.byteLength < 8 || new DataView(bytes).getUint32(0, true) !== 0x6d736100) {
+    throw new WasmLoadError(
+      `${url} is not a Wasm binary (${bytes.byteLength} bytes, content-type "${type}"). ` +
+        'Has scripts/build-wasm.sh copied the module into Web/public/?',
+    );
+  }
+  return WebAssembly.compile(bytes);
+}
+
+function checkImports(module: WebAssembly.Module): void {
+  const foreign = WebAssembly.Module.imports(module).filter((i) => i.module !== WASI_MODULE);
+  if (foreign.length > 0) {
+    const list = foreign.map((i) => `${i.module}.${i.name}`).join(', ');
+    throw new WasmLoadError(
+      `Module imports symbols outside ${WASI_MODULE}: ${list}. ` +
+        'The renderer only provides WASI preview1.',
+    );
+  }
+}
+
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const encoder = new TextEncoder();
+
+/**
+ * Read the pending ops buffer. `memory.buffer` is re-read on every call: the
+ * ArrayBuffer is detached whenever linear memory grows.
+ */
+function readPendingOps(exports: SwiftBrowserExports): Op[] {
+  const ptr = exports.sb_ops_ptr() >>> 0;
+  const len = exports.sb_ops_len() >>> 0;
+  if (len === 0) return [];
+  const memory = exports.memory.buffer;
+  if (ptr + len > memory.byteLength) {
+    throw new WasmLoadError(
+      `sb_ops_ptr/len (${ptr}, ${len}) point outside linear memory (${memory.byteLength} bytes)`,
+    );
+  }
+  const bytes = new Uint8Array(memory, ptr, len);
+  let json: string;
+  try {
+    json = decoder.decode(bytes);
+  } catch (error) {
+    throw new WasmLoadError(`Pending ops buffer is not valid UTF-8: ${String(error)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (error) {
+    throw new WasmLoadError(`Pending ops buffer is not valid JSON: ${String(error)}\n${json}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new WasmLoadError(`Pending ops buffer must be a JSON array, got ${typeof parsed}`);
+  }
+  const bad = parsed.find((item) => !isOp(item));
+  if (bad !== undefined) {
+    throw new WasmLoadError(`Unknown op in pending buffer: ${JSON.stringify(bad)}`);
+  }
+  return parsed as Op[];
+}