@twinkle-lang/twinkle 0.3.0 → 0.5.0

package/index.mjs

@@ -125,7 +125,6 @@ export async function run(wasmBytes, opts = {}) {
     bridgeBytes: loadBridgeWasm(),
     host: nodeHost,
     imports: opts.imports ?? {},
-    marshalSpec: opts.marshalSpec ?? {},
   });
 }
 

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@twinkle-lang/twinkle",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Twinkle — a statically typed language targeting WebAssembly GC. CLI (twk) plus an embeddable compile/run library.",
   "type": "module",
   "bin": { "twk": "node.mjs" },
   "exports": {
     ".": "./index.mjs",
+    "./web": "./web.mjs",
     "./runtime.mjs": "./runtime.mjs",
     "./node_host.mjs": "./node_host.mjs",
     "./boot.wasm": "./boot.wasm",
     "./bridge.wasm": "./bridge.wasm"
   },
-  "files": ["node.mjs", "index.mjs", "runtime.mjs", "node_host.mjs", "boot.wasm", "bridge.wasm", "README.md"],
+  "files": ["node.mjs", "index.mjs", "web.mjs", "runtime.mjs", "node_host.mjs", "boot.wasm", "bridge.wasm", "README.md"],
   "engines": { "node": ">=22" },
   "license": "MIT",
   "publishConfig": { "access": "public" },

package/runtime.mjs

@@ -121,11 +121,18 @@ function decodeByteArray(b, arrRef) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve each wasm extern import to a JS function.
+ * Resolve each wasm extern import to a JS function (and its optional arg spec).
+ *
+ * A scoped `imports[module][name]` entry is either:
+ *   - a function — the implementation, with default arg marshaling, or
+ *   - `{ fn?, args? }` — `fn` is the implementation (omit it to fall back to
+ *     `globals[module][name]`), and `args` is the per-arg marshal spec, an array
+ *     of `"raw" | "string"` keyed by position.
+ *
  * Resolution order per import: scoped `imports[module][name]`, then
  * `globals[module][name]`. Imports already satisfied by `hostImports`, or that
- * are not functions, are skipped. Returns the resolved bindings plus a list of
- * unresolved "module.name" strings.
+ * are not functions, are skipped. Returns the resolved bindings (each with
+ * `fn`, `recv`, and `args`) plus a list of unresolved "module.name" strings.
  */
 export function resolveExternImports(importList, hostImports, imports = {}, globals = globalThis) {
   const found = [];
@@ -134,21 +141,33 @@ export function resolveExternImports(importList, hostImports, imports = {}, glob
     if (hostImports[imp.module]?.[imp.name] !== undefined) continue;
     if (imp.kind !== "function") continue;
 
-    const scopedRecv = imports[imp.module];
-    const scoped = scopedRecv?.[imp.name];
+    const scoped = imports[imp.module]?.[imp.name];
+    let fn;
+    let recv;
+    let args;
+
     if (typeof scoped === "function") {
-      found.push({ module: imp.module, name: imp.name, fn: scoped, recv: scopedRecv });
-      continue;
+      fn = scoped;
+      recv = imports[imp.module];
+    } else if (scoped && typeof scoped === "object") {
+      args = scoped.args;
+      if (typeof scoped.fn === "function") {
+        fn = scoped.fn;
+        recv = imports[imp.module];
+      } else {
+        fn = globals[imp.module]?.[imp.name];
+        recv = globals[imp.module];
+      }
+    } else {
+      fn = globals[imp.module]?.[imp.name];
+      recv = globals[imp.module];
     }
 
-    const globalRecv = globals[imp.module];
-    const global = globalRecv?.[imp.name];
-    if (typeof global === "function") {
-      found.push({ module: imp.module, name: imp.name, fn: global, recv: globalRecv });
-      continue;
+    if (typeof fn === "function") {
+      found.push({ module: imp.module, name: imp.name, fn, recv, args });
+    } else {
+      missing.push(`${imp.module}.${imp.name}`);
     }
-
-    missing.push(`${imp.module}.${imp.name}`);
   }
   return { found, missing };
 }
@@ -162,7 +181,34 @@ export function resolveExternImports(importList, hostImports, imports = {}, glob
  *   - Int (bigint), Float (number), Bool (i32) pass through
  * Throws a single aggregated error if any extern import is unsatisfied.
  */
-function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, imports = {}, marshalSpec = {}) {
+/**
+ * Read the compiler-emitted `twinkle.externs` custom section into a
+ * `module → name → { args, ret }` map. Best-effort: `customSections` may throw
+ * on GC modules in some engines (same risk class as `Module.imports`), and the
+ * section is absent for non-Twinkle wasm — either way we return `{}` and the
+ * manual override / string-default path takes over.
+ */
+function readExternMeta(wasmModule) {
+  let sections;
+  try {
+    sections = WebAssembly.Module.customSections(wasmModule, "twinkle.externs");
+  } catch {
+    return {};
+  }
+  if (!sections || sections.length === 0) return {};
+  try {
+    const list = JSON.parse(new TextDecoder().decode(new Uint8Array(sections[0])));
+    const map = {};
+    for (const e of list) {
+      (map[e.module] ??= {})[e.name] = { args: e.args, ret: e.ret };
+    }
+    return map;
+  } catch {
+    return {};
+  }
+}
+
+function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, imports = {}, externMeta = {}) {
   let importList;
   try {
     importList = WebAssembly.Module.imports(wasmModule);
@@ -182,35 +228,51 @@ function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, impor
     );
   }
 
-  // Per-import arg marshaling honors an optional spec: `marshalSpec[module][name]`
-  // is an array of `"raw" | "string"` keyed by arg position. `"raw"` passes the
-  // value through untouched — essential for externref args (e.g. a canvas 2D
-  // context), since calling decodeString on an opaque host object recurses until
-  // a stack overflow in some engines (notably Safari). Without a spec entry, a
-  // non-numeric arg is assumed to be a Wasm GC string and decoded.
+  // Per-import arg marshaling honors a per-position kind spec. Two vocabularies
+  // are accepted and treated identically: the compiler-emitted twinkle.externs
+  // kinds ("str" | "ref" | "i64" | "f64" | "i32") and the manual override's
+  // ("raw" | "string"). Numbers pass through (handled before the spec). "ref" /
+  // "raw" pass the value untouched — essential for externref args (e.g. a canvas
+  // 2D context), since decodeString on an opaque host object recurses until a
+  // stack overflow in some engines (notably Safari). Anything else (incl. no
+  // entry) is assumed to be a Wasm GC string and decoded.
   const makeMarshalArgs = (spec) => (args) => args.map((arg, i) => {
     if (typeof arg === "bigint") return Number(arg);
     if (typeof arg === "number") return arg;
-    if (spec?.[i] === "raw") return arg;
+    const k = spec?.[i];
+    if (k === "ref" || k === "raw") return arg;
     return decodeString(b, arg);
   });
 
-  const marshalReturn = (result) => {
+  // Return marshaling uses the compiler-emitted `ret` kind when available, so
+  // we never guess from the JS value's type. Falls back to a generic guess when
+  // there is no section (manual-only callers).
+  const marshalReturn = (result, ret) => {
     if (result === undefined || result === null) return;
+    switch (ret) {
+      case "ref": return result;
+      case "str": return typeof result === "string" ? encodeString(b, result) : result;
+      case "i64": return typeof result === "number" ? BigInt(result) : result;
+      case "f64": case "i32": return result;
+      case "void": return undefined;
+    }
     if (typeof result === "string") return encodeString(b, result);
     if (typeof result === "number") return result;
     if (typeof result === "bigint") return result;
     return result;
   };
 
-  for (const { module, name, fn, recv } of found) {
-    const marshalArgs = makeMarshalArgs(marshalSpec[module]?.[name]);
+  for (const { module, name, fn, recv, args } of found) {
+    // Precedence: a manual `args` override wins over the section's kinds.
+    const meta = externMeta[module]?.[name];
+    const marshalArgs = makeMarshalArgs(args ?? meta?.args);
+    const ret = meta?.ret;
     let bridgedFn;
     if (jspi) {
       // JSPI mode: async wrapper so Promise-returning JS functions suspend
       // Wasm. Non-Promise returns pass through without suspension.
       const asyncWrapper = async (...args) =>
-        marshalReturn(await fn.apply(recv, marshalArgs(args)));
+        marshalReturn(await fn.apply(recv, marshalArgs(args)), ret);
       bridgedFn = new WebAssembly.Suspending(asyncWrapper);
     } else {
       // Sync mode: detect and reject Promise returns
@@ -222,7 +284,7 @@ function autoBridgeExternImports(wasmModule, hostImports, b, jspi = false, impor
             `Promise-returning externs require a runtime with WebAssembly.Suspending/promising support.`,
           );
         }
-        return marshalReturn(result);
+        return marshalReturn(result, ret);
       };
     }
     if (!hostImports[module]) hostImports[module] = {};
@@ -280,7 +342,6 @@ function makeHostImports(b, runtime, bridgeBytes) {
           stdout: runtime.stdout,
           stderr: runtime.stderr,
           imports: runtime.imports,
-          marshalSpec: runtime.marshalSpec,
           host: runtime.host,
           bridgeBytes,
         });
@@ -343,6 +404,64 @@ function makeHostImports(b, runtime, bridgeBytes) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// In-memory host adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * A host adapter backed by an in-memory file map — the default for browsers and
+ * other environments without a real filesystem. Reads/writes a `Map<string,
+ * Uint8Array>`; stdin is always EOF. Pure JS (no `node:` deps), so it is safe to
+ * load anywhere.
+ *
+ * @param {Map<string,Uint8Array> | Iterable<[string,Uint8Array]>} [initialFiles]
+ */
+export function createMemoryHost(initialFiles) {
+  const files = initialFiles instanceof Map ? initialFiles : new Map(initialFiles ?? []);
+  const norm = (p) => (p.startsWith("/") ? p : "/" + p).replace(/\/+/g, "/");
+  return {
+    files,
+    resolvePath(cwd, p) {
+      if (p.startsWith("/")) return norm(p);
+      return norm((cwd.endsWith("/") ? cwd : cwd + "/") + p);
+    },
+    readFile(path) {
+      const data = files.get(norm(path));
+      if (data === undefined) throw new Error(`file not found: ${path}`);
+      return data;
+    },
+    writeFile(path, text) { files.set(norm(path), textEncoder.encode(text)); },
+    writeBytes(path, bytes) { files.set(norm(path), bytes); },
+    exists(path) {
+      const np = norm(path);
+      if (files.has(np)) return true;
+      const prefix = np.endsWith("/") ? np : np + "/";
+      for (const k of files.keys()) if (k.startsWith(prefix)) return true;
+      return false;
+    },
+    listDir(path) {
+      const prefix = norm(path).replace(/\/?$/, "/");
+      const names = new Set();
+      for (const k of files.keys()) {
+        if (k.startsWith(prefix)) {
+          const name = k.slice(prefix.length).split("/")[0];
+          if (name) names.add(name);
+        }
+      }
+      return [...names].sort();
+    },
+    mkdirp() { /* virtual dirs are implicit */ },
+    readStdin(_maxBytes, _timeoutMs, runtime) {
+      runtime.stdinEof = true;
+      return new Uint8Array(0);
+    },
+    readStdinAsync(_maxBytes, _timeoutMs, runtime) {
+      runtime.stdinEof = true;
+      return Promise.resolve(new Uint8Array(0));
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Bridge instantiation
 // ---------------------------------------------------------------------------
@@ -376,7 +495,6 @@ function prepareWasm(wasmBytes, opts, { jspi = false } = {}) {
     bridgeBytes,
     host,
     imports = {},
-    marshalSpec = {},
   } = opts;
 
   if (!bridgeBytes) {
@@ -396,12 +514,12 @@ function prepareWasm(wasmBytes, opts, { jspi = false } = {}) {
     stdinEof: false,
     host,
     imports,
-    marshalSpec,
   };
 
   const hostImports = makeHostImports(b, runtime, bridgeBytes);
   const mainModule = new WebAssembly.Module(wasmBytes);
-  autoBridgeExternImports(mainModule, hostImports, b, jspi, imports, marshalSpec);
+  const externMeta = readExternMeta(mainModule);
+  autoBridgeExternImports(mainModule, hostImports, b, jspi, imports, externMeta);
 
   return { mainModule, hostImports, b, runtime };
 }
@@ -466,7 +584,6 @@ export async function runWasmBytesAsync(wasmBytes, opts = {}) {
           stdout: runtime.stdout,
           stderr: runtime.stderr,
           imports: runtime.imports,
-          marshalSpec: runtime.marshalSpec,
           host: runtime.host,
           bridgeBytes: childBridgeBytes,
         });

package/web.mjs

@@ -0,0 +1,77 @@
+// Browser entry for embedding Twinkle.
+//
+//   import { run } from "@twinkle-lang/twinkle/web";
+//   await run(source, { stdout, stderr });
+//
+// Unlike index.mjs (Node: temp files, node:fs), this is browser-first: it
+// self-loads the compiler wasm that ships beside it and uses an in-memory
+// filesystem by default, so callers never touch boot.wasm/bridge.wasm or
+// construct a host adapter.
+
+import { runWasmBytesAsync, createMemoryHost } from "./runtime.mjs";
+
+const textEncoder = new TextEncoder();
+
+// boot.wasm / bridge.wasm are published next to this module. `new URL(...,
+// import.meta.url)` lets the consumer's bundler emit them as assets (Vite,
+// webpack, native ESM all understand this), so no `?url` import is needed.
+let assetsPromise;
+
+function loadAssets() {
+  if (!assetsPromise) {
+    assetsPromise = Promise.all([
+      fetch(new URL("./boot.wasm", import.meta.url)).then((r) => r.arrayBuffer()),
+      fetch(new URL("./bridge.wasm", import.meta.url)).then((r) => r.arrayBuffer()),
+    ]).then(([boot, bridge]) => ({
+      bootBytes: new Uint8Array(boot),
+      bridgeBytes: new Uint8Array(bridge),
+    }));
+  }
+  return assetsPromise;
+}
+
+/** Pre-fetch the compiler wasm so the first run() doesn't pay the load latency. */
+export function load() {
+  return loadAssets();
+}
+
+const defaultStream = (sink) => ({
+  write(chunk) {
+    sink(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+    return true;
+  },
+});
+
+/**
+ * Compile and run Twinkle source in the browser.
+ *
+ * @param {string | Uint8Array} source  Twinkle source for the entry module.
+ * @param {object} [opts]
+ * @param {object} [opts.stdout]   Stream with write(chunk); defaults to console.log.
+ * @param {object} [opts.stderr]   Stream with write(chunk); defaults to console.error.
+ * @param {object} [opts.env]      Environment map exposed to the program.
+ * @param {object} [opts.imports]  Extern imports — `module → fn | { fn?, args? }`
+ *   (else resolved via globalThis). `args` is the per-arg spec, e.g.
+ *   `{ canvas: { fill_rect: { fn, args: ['raw','raw','raw','raw','raw'] } } }`.
+ * @param {Iterable<[string,Uint8Array]>} [opts.files]  Extra in-memory files (multi-file projects).
+ * @param {object} [opts.host]     Override the host adapter entirely (advanced).
+ * @returns {Promise<number>} exit code
+ */
+export async function run(source, opts = {}) {
+  const { bootBytes, bridgeBytes } = await loadAssets();
+
+  const files = new Map(opts.files ?? []);
+  files.set("/input/main.tw", typeof source === "string" ? textEncoder.encode(source) : source);
+
+  return runWasmBytesAsync(bootBytes, {
+    programPath: "twk.wasm",
+    guestArgs: ["run", "/input/main.tw"],
+    cwd: "/",
+    env: opts.env ?? {},
+    stdout: opts.stdout ?? defaultStream((s) => console.log(s)),
+    stderr: opts.stderr ?? defaultStream((s) => console.error(s)),
+    bridgeBytes,
+    host: opts.host ?? createMemoryHost(files),
+    imports: opts.imports ?? {},
+  });
+}