@twinkle-lang/twinkle 0.6.2 → 0.7.1

package/README.md

@@ -18,7 +18,7 @@ npx twk build path/to/program.tw -o out.wasm
 npx twk fmt path/to/program.tw
 ```
 
-## Library
+## Node library
 
 ```js
 import { compile, run, runFile } from "@twinkle-lang/twinkle";
@@ -41,4 +41,27 @@ await run(wasm, { imports: { canvas } });
 
 A missing extern import produces a clear error naming the exact `module.fn`.
 
-Requires Node.js ≥ 22.
+## Browser library
+
+```js
+import { command, run, load } from "@twinkle-lang/twinkle/web";
+
+await load(); // optional prefetch
+
+const result = await command(["fmt", "/input/main.tw"], {
+  source: editor.getValue(),
+  env: { NO_COLOR: "1" },
+});
+
+if (result.exitCode === 0) {
+  editor.setValue(result.text("/input/main.tw"));
+}
+```
+
+`command(args, opts)` runs the shipped compiler payload against an in-memory
+filesystem and returns `{ exitCode, stdout, stderr, files, text(path), bytes(path) }`.
+Compiler failures are returned as non-zero exit codes; host/runtime failures throw.
+The existing browser `run(source, opts)` helper is still available and returns an
+exit code.
+
+Requires Node.js ≥ 22 for the Node APIs. Browser APIs require WebAssembly GC.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinkle-lang/twinkle",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Twinkle — a statically typed language targeting WebAssembly GC. CLI (twk) plus an embeddable compile/run library.",
   "type": "module",
   "bin": { "twk": "node.mjs" },

package/web.mjs

@@ -1,6 +1,7 @@
 // Browser entry for embedding Twinkle.
 //
-//   import { run } from "@twinkle-lang/twinkle/web";
+//   import { command, run } from "@twinkle-lang/twinkle/web";
+//   await command(["fmt", "/input/main.tw"], { source });
 //   await run(source, { stdout, stderr });
 //
 // Unlike index.mjs (Node: temp files, node:fs), this is browser-first: it
@@ -11,6 +12,7 @@
 import { runWasmBytesAsync, createMemoryHost } from "./runtime.mjs";
 
 const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
 
 // 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,
@@ -37,11 +39,135 @@ export function load() {
 
 const defaultStream = (sink) => ({
   write(chunk) {
-    sink(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+    sink(typeof chunk === "string" ? chunk : textDecoder.decode(chunk));
     return true;
   },
 });
 
+function assertPath(path, label) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+}
+
+function bytesFor(value, label) {
+  if (typeof value === "string") return textEncoder.encode(value);
+  if (value instanceof Uint8Array) return value;
+  throw new TypeError(`${label} must be a string or Uint8Array`);
+}
+
+function createCaptureStream(forward) {
+  const decoder = new TextDecoder();
+  let text = "";
+
+  return {
+    stream: {
+      write(chunk) {
+        if (typeof chunk === "string") {
+          text += decoder.decode();
+          text += chunk;
+        } else {
+          text += decoder.decode(chunk, { stream: true });
+        }
+        if (forward) forward.write(chunk);
+        return true;
+      },
+    },
+    finish() {
+      text += decoder.decode();
+      return text;
+    },
+  };
+}
+
+function seedFile(host, cwd, path, value, label) {
+  assertPath(path, label);
+  if (typeof host.resolvePath !== "function" || typeof host.writeBytes !== "function") {
+    throw new TypeError("command: host must provide resolvePath(cwd, path) and writeBytes(path, bytes)");
+  }
+  host.writeBytes(host.resolvePath(cwd, path), bytesFor(value, label));
+}
+
+function normalizeArgs(args) {
+  if (!Array.isArray(args) || !args.every((arg) => typeof arg === "string")) {
+    throw new TypeError("command: args must be an array of strings");
+  }
+  return args.slice();
+}
+
+function commandResult(exitCode, stdout, stderr, host, cwd) {
+  const files = host.files instanceof Map ? host.files : new Map();
+  return {
+    exitCode,
+    stdout,
+    stderr,
+    files,
+    text(path) {
+      const data = this.bytes(path);
+      return data === undefined ? undefined : textDecoder.decode(data);
+    },
+    bytes(path) {
+      assertPath(path, "path");
+      const normalized = typeof host.resolvePath === "function" ? host.resolvePath(cwd, path) : path;
+      return files.get(normalized);
+    },
+  };
+}
+
+/**
+ * Run a compiler command in the browser against an in-memory project.
+ *
+ * @param {string[]} args CLI arguments, e.g. `["fmt", "/input/main.tw"]`.
+ * @param {object} [opts]
+ * @param {string | Uint8Array} [opts.source]  Entry source written to opts.path.
+ * @param {string} [opts.path]     Path for opts.source; defaults to /input/main.tw.
+ * @param {Iterable<[string,string | Uint8Array]>} [opts.files]  Files to seed first.
+ * @param {string} [opts.cwd]      Working directory; defaults to /.
+ * @param {object} [opts.stdout]   Optional stream with write(chunk), tee'd with capture.
+ * @param {object} [opts.stderr]   Optional stream with write(chunk), tee'd with capture.
+ * @param {object} [opts.env]      Environment map exposed to the compiler/program.
+ * @param {object} [opts.imports]  Extern imports for commands that execute user Wasm.
+ * @param {object} [opts.host]     Override the host adapter entirely (advanced).
+ * @returns {Promise<{exitCode:number, stdout:string, stderr:string, files:Map<string,Uint8Array>, text:function, bytes:function}>}
+ */
+export async function command(args, opts = {}) {
+  const guestArgs = normalizeArgs(args);
+  const cwd = opts.cwd ?? "/";
+  assertPath(cwd, "cwd");
+
+  const { bootBytes, bridgeBytes } = await loadAssets();
+  const host = opts.host ?? createMemoryHost();
+
+  if (opts.files !== undefined) {
+    for (const entry of opts.files) {
+      if (!Array.isArray(entry) || entry.length !== 2) {
+        throw new TypeError("command: files must be an iterable of [path, contents] pairs");
+      }
+      seedFile(host, cwd, entry[0], entry[1], "file path");
+    }
+  }
+
+  if (opts.source !== undefined) {
+    seedFile(host, cwd, opts.path ?? "/input/main.tw", opts.source, "path");
+  }
+
+  const stdoutCapture = createCaptureStream(opts.stdout);
+  const stderrCapture = createCaptureStream(opts.stderr);
+  const exitCode = await runWasmBytesAsync(bootBytes, {
+    programPath: "twk.wasm",
+    guestArgs,
+    cwd,
+    env: opts.env ?? {},
+    stdout: stdoutCapture.stream,
+    stderr: stderrCapture.stream,
+    bridgeBytes,
+    host,
+    imports: opts.imports ?? {},
+  });
+
+  return commandResult(exitCode, stdoutCapture.finish(), stderrCapture.finish(), host, cwd);
+}
+
 /**
  * Compile and run Twinkle source in the browser.
  *
@@ -53,25 +179,19 @@ const defaultStream = (sink) => ({
  * @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 {Iterable<[string,string | Uint8Array]>} [opts.files]  Extra in-memory files (multi-file projects).
+ * @param {string} [opts.path]     Entry path; defaults to /input/main.tw.
  * @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 ?? {},
+  const path = opts.path ?? "/input/main.tw";
+  const result = await command(["run", path], {
+    ...opts,
+    source,
+    path,
     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 ?? {},
   });
+  return result.exitCode;
 }