lilac-wasm-bin 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0643e7b710fc139e195c98efefa72f55b51d11f0b83fc45f0bf1204e9b1f96cb
+  data.tar.gz: 4ff9a88520b3d9042b204514e2cd3d6bf3832b90cc64b35f1031195ab85743a1
+SHA512:
+  metadata.gz: 7e5d5d6fa6e64f64710b865881f67ecbaad828beadc7425c9a976af4339542d52efbe6e9f20b9f1bcaa972b1d686116fdb61f036112858231639aa995a84564a
+  data.tar.gz: c3ac8131575d118658ce66803da657bdc5e48445cb62926255697ddb19a40f2414b79e546e170d2b498627064ff59b43758c80db16af6d0e6fca5a458e6d356a

data/README.md

@@ -0,0 +1,46 @@
+# lilac-wasm-bin
+
+Bundles the Lilac wasm runtimes (`lilac-full.wasm`, `lilac-compiled.wasm`)
+and the `mruby-wasm-js` JS bridge as a single Ruby gem so that
+
+```
+gem install lilac-cli
+lilac new my-app && cd my-app
+bundle install
+```
+
+is enough to make both `lilac dev` and `lilac build` work — no `npm
+install`, no manual `cp` of wasm files into `public/vendor/...`.
+
+The scaffolded `Gemfile` declares `gem "lilac-wasm-bin"`, so the gem is
+pulled transparently during `bundle install`. The `lilac-cli` gem
+itself does **not** depend on this gem — projects that don't need the
+bundled wasm (e.g. CI for an external runtime) can skip it without
+penalty.
+
+## Resolution
+
+`lilac-cli`'s `CompiledRuntimeResolver` soft-requires `lilac/wasm/bin`
+and consults `Lilac::Wasm::Bin.lilac_compiled_wasm` (and friends) when
+discovering wasm. If the gem is absent the resolver falls back to the
+existing env / config / monorepo / node_modules discovery chain.
+
+## Layout
+
+```
+lilac-wasm-bin-X.Y.Z/
+├── lib/lilac/wasm/bin.rb     # path constants + resolution helpers
+└── data/                     # populated by `rake build:assets`
+    ├── lilac-full.wasm
+    ├── lilac-compiled.wasm
+    └── mruby-wasm-js/        # JS bridge source
+```
+
+`data/` is gitignored and populated by `rake build:assets` immediately
+before `gem build`. The gem build pipeline expects monorepo build
+artifacts under `<monorepo>/build/` and `<monorepo>/mrbgem/mruby-wasm-js/`.
+
+For monorepo development (when the gem is referenced as `gem
+"lilac-wasm-bin", path: "../wasm-bin"`), the resolution helpers also
+walk up to the monorepo `build/` directory as a fallback, so contributors
+don't have to re-run `rake build:assets` after every wasm rebuild.

data/data/mruby-wasm-js/_memory.js

@@ -0,0 +1,35 @@
+// Shared memory helpers for index.js and wasi-preview1.js.
+//
+// Both modules need to encode/decode UTF-8 from wasm linear memory and
+// read i32 arrays of handles. Keeping a single TextDecoder/Encoder pair
+// avoids re-allocating per call, and the `createMemoryHelpers` factory
+// binds them to a particular VM's instance via the `getInstance`
+// callback (read on every helper call so callers can wire it before
+// they actually have an instance handle — e.g. when building the
+// imports object that's fed to instantiateStreaming).
+
+export const decoder = new TextDecoder("utf-8");
+export const encoder = new TextEncoder();
+
+export function createMemoryHelpers(getInstance) {
+  function readUtf8(ptr, len) {
+    const memory = getInstance().exports.memory;
+    return decoder.decode(new Uint8Array(memory.buffer, ptr, len));
+  }
+  function writeUtf8(s, ptr, maxLen) {
+    const memory = getInstance().exports.memory;
+    const view = new Uint8Array(memory.buffer, ptr, maxLen);
+    const encoded = encoder.encode(s);
+    const n = Math.min(encoded.length, maxLen);
+    view.set(encoded.subarray(0, n));
+    return n;
+  }
+  function readHandleArray(ptr, count) {
+    if (count <= 0) return [];
+    const view = new DataView(getInstance().exports.memory.buffer);
+    const out = new Array(count);
+    for (let i = 0; i < count; i++) out[i] = view.getInt32(ptr + i * 4, true);
+    return out;
+  }
+  return { readUtf8, writeUtf8, readHandleArray };
+}

data/data/mruby-wasm-js/_smoke.ts

@@ -0,0 +1,117 @@
+// Type smoke test for index.d.ts. Run with:
+//   npx -p typescript@5 tsc --noEmit --module nodenext --moduleResolution nodenext --target es2022 --strict _smoke.ts
+//
+// Not shipped — exercises every exported shape so a future drift in
+// index.d.ts surfaces as a tsc error.
+
+import {
+  createVM,
+  Directory,
+  File,
+  createFsFacade,
+  debug,
+  RubyError,
+  type FsFacade,
+  type VMCore,
+  type VMWithBundledWasi,
+  type CreateVMOptions,
+  type EvalOptions,
+  type LoadBytecodeOptions,
+} from "./index.js";
+
+// --- Directory / File ---------------------------------------------------
+const f: File = new File(new Uint8Array([1, 2, 3]));
+const bytes: Uint8Array = f.data;
+void bytes;
+
+const root: Directory = new Directory({
+  "hello.txt": new File(new TextEncoder().encode("hi")),
+  nested: new Directory({ "a.txt": new File() }),
+});
+const childEntries: Record<string, File | Directory> = root.entries;
+void childEntries;
+
+// --- createFsFacade -----------------------------------------------------
+const fs: FsFacade = createFsFacade(root);
+fs.set("/x.txt", new Uint8Array(0)).set("/y.txt", new Uint8Array(0));
+const got: Uint8Array | undefined = fs.get("/x.txt");
+const present: boolean = fs.has("/x.txt");
+const sz: number = fs.size;
+void got; void present; void sz;
+for (const [path, data] of fs) {
+  const p: string = path;
+  const d: Uint8Array = data;
+  void p; void d;
+}
+const k: IterableIterator<string> = fs.keys();
+void k.next();
+
+// --- debug --------------------------------------------------------------
+debug.trace = true;
+
+// --- createVM with bundled WASI -----------------------------------------
+const vmBundled: VMWithBundledWasi = await createVM({
+  wasm: "/path/to/mruby-js.wasm",
+  env: { LANG: "C.UTF-8" },
+  args: ["mruby-wasm-js", "demo"],
+  stdin: "hello\n",
+  fs: root,
+});
+const rc: number = vmBundled.eval('puts "hi"');
+void rc;
+vmBundled.loadBytecode(new Uint8Array(0));
+vmBundled.loadBytecode(new ArrayBuffer(0));
+vmBundled.fs.set("/runtime-added.txt", new Uint8Array(0));
+vmBundled.env.NEW_VAR = "1";
+vmBundled.args.push("more");
+vmBundled.stdin.pushText("more\n");
+
+// --- createVM with custom WASI ------------------------------------------
+const wasi: WebAssembly.ModuleImports = {
+  fd_write: (() => 0) as unknown as Function,
+};
+const vmCustom: VMCore = await createVM({
+  wasm: "/path/to/mruby-js.wasm",
+  wasi,
+  onStart: (inst) => {
+    const start = inst.exports._start as () => void;
+    start();
+  },
+});
+
+// @ts-expect-error -- VMCore must NOT carry `fs` (that's bundled-only)
+vmCustom.fs;
+
+// --- CreateVMOptions union exposed for callers --------------------------
+const opts: CreateVMOptions = { wasm: "x" };
+void opts;
+
+// --- VMCore handle table -----------------------------------------------
+const h: number = vmCustom.alloc({ any: "value" });
+const back: unknown = vmCustom.get(h);
+vmCustom.release(h);
+const live: number = vmCustom.handleCount();
+void back; void live;
+
+// --- evalScript ---------------------------------------------------------
+vmBundled.evalScript("#ruby");
+vmBundled.evalScript("#ruby", { filename: "embedded.rb", lineOffset: 5 });
+
+// --- RubyError + eval options -------------------------------------------
+const evalOpts: EvalOptions = { filename: "app.rb", lineOffset: 1, throw: false };
+const loadOpts: LoadBytecodeOptions = { throw: false };
+const noThrowRc: number = vmBundled.eval("nope", evalOpts);
+const noThrowLoad: number = vmBundled.loadBytecode(new Uint8Array(0), loadOpts);
+void noThrowRc; void noThrowLoad;
+
+try {
+  vmBundled.eval("def foo", { filename: "x.rb" });
+} catch (e) {
+  if (e instanceof RubyError) {
+    const cls: string = e.rubyClass;
+    const bt: string[] = e.backtrace;
+    void cls; void bt;
+  }
+}
+const re: RubyError = new RubyError({ class: "Boom", message: "x", backtrace: [] });
+void re;

data/data/mruby-wasm-js/debug.js

@@ -0,0 +1,8 @@
+// Shared debug toggle. Lives in its own module so index.js (gem core)
+// and wasi-preview1.js (one of N possible WASI impls) can both import it
+// without forming a cycle.
+//
+// Set `debug.trace = true` at runtime to log handle release / callback
+// dispatch / WASI fd_read / WASI path_open. Off by default — production
+// noise.
+export const debug = { trace: false };

data/data/mruby-wasm-js/index.d.ts

@@ -0,0 +1,177 @@
+// Type definitions for @takahashim/mruby-wasm-js
+// mruby ↔ JavaScript bridge for WebAssembly.
+
+/** A regular-file node in the virtual filesystem. */
+export class File {
+  constructor(data?: Uint8Array);
+  data: Uint8Array;
+}
+
+/** A directory node in the virtual filesystem. */
+export class Directory {
+  constructor(entries?: Record<string, File | Directory>);
+  entries: Record<string, File | Directory>;
+}
+
+/**
+ * Map-style facade over a {@link Directory} tree. Iteration walks the
+ * tree depth-first and yields only File leaves, keyed by absolute path.
+ */
+export interface FsFacade {
+  set(path: string, bytes: Uint8Array): this;
+  get(path: string): Uint8Array | undefined;
+  has(path: string): boolean;
+  delete(path: string): boolean;
+  entries(): IterableIterator<[string, Uint8Array]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<Uint8Array>;
+  [Symbol.iterator](): IterableIterator<[string, Uint8Array]>;
+  readonly size: number;
+  clear(): void;
+  /** Replace root contents with another Directory's entries. */
+  populate(dir: Directory): void;
+  readonly root: Directory;
+}
+
+/** Wrap a {@link Directory} root as a Map-compatible facade. */
+export function createFsFacade(root: Directory): FsFacade;
+
+/** Mutable bundled-stdin handle exposed on the VM. */
+export interface VMStdin {
+  bytes: Uint8Array;
+  pushText(s: string): void;
+}
+
+/**
+ * Thrown by {@link VMCore.eval} / {@link VMCore.loadBytecode} when
+ * mruby raises an unhandled exception. `rubyClass` mirrors
+ * `exception.class.name`; `backtrace` mirrors `exception.backtrace`.
+ */
+export class RubyError extends Error {
+  constructor(info?: { class?: string; message?: string; backtrace?: string[] });
+  rubyClass: string;
+  backtrace: string[];
+}
+
+/** Optional knobs for {@link VMCore.eval}. */
+export interface EvalOptions {
+  /** Filename surfaced in error backtraces (e.g., `"app.rb"`). */
+  filename?: string;
+  /**
+   * 1-based line number that source line 1 reports as. Useful when the
+   * Ruby was extracted from a wrapping context (e.g., `<script>` block
+   * embedded at line 17 of an HTML file).
+   */
+  lineOffset?: number;
+  /**
+   * When `true` (default), mruby exceptions surface as a thrown
+   * {@link RubyError}. Pass `false` to retain the legacy contract where
+   * `eval` returns `1` on failure and the caller inspects rc.
+   */
+  throw?: boolean;
+}
+
+/** Optional knobs for {@link VMCore.loadBytecode}. */
+export interface LoadBytecodeOptions {
+  /** Same semantics as {@link EvalOptions.throw}. */
+  throw?: boolean;
+}
+
+/** Methods common to every VM returned by {@link createVM}. */
+export interface VMCore {
+  instance: WebAssembly.Instance;
+
+  /**
+   * Parse + run Ruby source on the live VM. By default throws
+   * {@link RubyError} on parse/runtime error. Returns 0 on success.
+   * Throws `NotImplementedError` in compiler-less builds (use
+   * {@link loadBytecode} instead). With `options.throw === false`,
+   * returns 1 on error instead of throwing.
+   */
+  eval(source: string, options?: EvalOptions): number;
+
+  /**
+   * Load pre-compiled mruby bytecode (mrbc output). By default throws
+   * {@link RubyError} on runtime error. Returns 0 on success. Accepts
+   * `Uint8Array` or `ArrayBuffer`. Available in every build variant.
+   * With `options.throw === false`, returns 1 on error instead of throwing.
+   */
+  loadBytecode(bytes: Uint8Array | ArrayBuffer, options?: LoadBytecodeOptions): number;
+
+  /**
+   * Eval the textContent of a DOM element matched by `selector`. Pairs
+   * with `<script type="text/ruby">` blocks. Browser-only — throws if
+   * `document` is undefined.
+   */
+  evalScript(selector: string, options?: EvalOptions): number;
+
+  /** Power-user handle table — allocate a slot for a JS value. */
+  alloc(value: unknown): number;
+  /** Look up the JS value behind a handle. */
+  get(handle: number): unknown;
+  /** Release a handle slot. */
+  release(handle: number): void;
+  /** Live handle count (useful for leak detection in tests). */
+  handleCount(): number;
+}
+
+/**
+ * VM returned when `createVM` is invoked without `options.wasi`.
+ * The bundled WASI preview1 impl owns fs / env / args / stdin and
+ * exposes them here.
+ */
+export interface VMWithBundledWasi extends VMCore {
+  fs: FsFacade;
+  env: Record<string, string>;
+  args: string[];
+  stdin: VMStdin;
+}
+
+/** Options shared by every {@link createVM} call. */
+interface CreateVMOptionsBase {
+  /** URL to mruby-js.wasm. Required. */
+  wasm: string;
+  /**
+   * Post-instantiate callback. Defaults to calling
+   * `instance.exports._initialize()` for reactor modules, falling back
+   * to `_start()` for command modules.
+   */
+  onStart?: (instance: WebAssembly.Instance) => void;
+}
+
+/**
+ * Options when using the bundled in-memory WASI preview1 impl
+ * (default — when `wasi` is omitted).
+ */
+export interface CreateVMOptionsBundled extends CreateVMOptionsBase {
+  wasi?: undefined;
+  /** Initial ENV available to Ruby via `ENV[]`. */
+  env?: Record<string, string>;
+  /** Initial ARGV. `args[1..]` lands in Ruby's `ARGV`. */
+  args?: string[];
+  /** Initial stdin payload for `STDIN.read` / `gets`. */
+  stdin?: string | Uint8Array;
+  /** Initial root directory for the virtual filesystem. */
+  fs?: Directory;
+}
+
+/**
+ * Options when supplying a replacement `wasi_snapshot_preview1` import
+ * object (e.g. `@bjorn3/browser_wasi_shim`). The returned VM does NOT
+ * include fs / env / args / stdin — the caller's WASI owns that state.
+ */
+export interface CreateVMOptionsCustomWasi extends CreateVMOptionsBase {
+  wasi: WebAssembly.ModuleImports;
+}
+
+export type CreateVMOptions = CreateVMOptionsBundled | CreateVMOptionsCustomWasi;
+
+/**
+ * Instantiate a fresh mruby VM. Each call gets an independent handle
+ * table + WASI state — multiple VMs can coexist in one process.
+ */
+export function createVM(options: CreateVMOptionsCustomWasi): Promise<VMCore>;
+export function createVM(options: CreateVMOptionsBundled): Promise<VMWithBundledWasi>;
+
+/** Global debug toggle (`{ trace: false }` by default). */
+export const debug: { trace: boolean };