janela 0.1.2 → 0.2.0

package/README.md

@@ -69,10 +69,10 @@ Backend API (`src-host/main.ts`):
 import type { JanelaApp } from "./janela";
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (argsJson) => {          // args in / result out as JSON text
-    const a = JSON.parse(argsJson) as { a: number; b: number };
-    app.emit("added", JSON.stringify(a.a + a.b));  // push an event to the page
-    return JSON.stringify(a.a + a.b);
+  app.command("add", (args) => {              // values in, values out
+    const a = args as { a: number; b: number };
+    app.emit("added", a.a + a.b);             // push an event to the page
+    return a.a + a.b;
   });
   // app.quit() closes the window and returns from run()
 }
@@ -85,19 +85,19 @@ the window. Register it with `commandAsync` and answer whenever you are ready;
 the page keeps using the same `await janela.invoke(...)`.
 
 ```ts
-app.commandAsync("wait", (argsJson, resolve, reject) => {
-  const a = JSON.parse(argsJson) as { ms: number };
-  app.sleep(a.ms, () => resolve(JSON.stringify("done")));   // resolve later
+app.commandAsync("wait", (args, resolve, reject) => {
+  const a = args as { ms: number };
+  app.sleep(a.ms, () => resolve("done"));   // resolve later
 });
 
 // Work that cannot just wait: slice it, yielding to the UI between slices.
-app.commandAsync("countTo", (argsJson, resolve) => {
-  const a = JSON.parse(argsJson) as { n: number };
+app.commandAsync("countTo", (args, resolve) => {
+  const a = args as { n: number };
   let i = 0;
   const step = (): void => {
     const end = Math.min(i + 2_000_000, a.n);
     for (; i < end; i++) { /* ... */ }
-    if (i < a.n) app.defer(step); else resolve(JSON.stringify(i));
+    if (i < a.n) app.defer(step); else resolve(i);
   };
   app.defer(step);
 });
@@ -105,8 +105,36 @@ app.commandAsync("countTo", (argsJson, resolve) => {
 
 - `app.defer(fn)` — run `fn` on the next turn of the host loop.
 - `app.sleep(ms, fn)` — run `fn` after at least `ms`.
-- `resolve(json)` / `reject(json)` settle the page's promise; `reject` makes
-  `await janela.invoke(...)` throw. Settling twice is ignored.
+- `resolve(value)` / `reject(reason)` settle the page's promise; `reject`
+  makes `await janela.invoke(...)` throw. Settling twice is ignored.
+
+## File I/O
+
+`node:fs` works in a handler, but `readFileSync` **blocks the window** for as
+long as the syscall runs — parking a promise does not change that. Use the
+async pair instead: the syscall runs on a worker thread inside the shim, and
+only the result crosses back to your (single-threaded) TypeScript.
+
+```ts
+app.commandAsync("readFile", (args, resolve) => {
+  const a = args as { path: string };
+  app.readFileAsync(a.path, (err, text) => {
+    if (err !== null) { resolve({ ok: false, error: err }); return; }
+    resolve({ ok: true, text });
+  });
+});
+
+app.writeFileAsync("out.txt", "contents", (err) => { /* err is null on success */ });
+```
+
+Errors arrive as values, never throws — `err` carries a Node-shaped message
+(`ENOENT: no such file or directory, open '/x'`). UTF-8 round-trips exactly,
+astral characters included.
+
+The payload still crosses the FFI boundary one byte per call (format 2), which
+costs about **115 ms per MB on the UI thread** — fine for config files and
+documents, wrong for streaming large media. See
+[docs/async.md](../../docs/async.md) for the measurements.
 
 **Use `app.sleep`, not `setTimeout`.** scriptc's own event loop is parked for
 as long as the program sits inside the `run()` FFI call, so `setTimeout`,
@@ -124,6 +152,33 @@ The backend is ordinary TypeScript with scriptc's stdlib — including a
 `node:fs` subset — so "read a file" or "call an API" is just code in a
 command handler, no plugin layer needed.
 
+## Migrating from 0.1.x
+
+Commands used to take and return **JSON text**; they now take and return
+**values**, with the runtime handling serialisation. The page-side API
+(`janela.invoke` / `janela.listen`) is unchanged.
+
+```ts
+// 0.1.x
+app.command("add", (argsJson) => {
+  const a = JSON.parse(argsJson) as { a: number; b: number };
+  app.emit("added", JSON.stringify(a.a + a.b));
+  return JSON.stringify(a.a + a.b);
+});
+
+// 0.2.x
+app.command("add", (args) => {
+  const a = args as { a: number; b: number };
+  app.emit("added", a.a + a.b);
+  return a.a + a.b;
+});
+```
+
+Mechanically: drop the `JSON.parse(argsJson)` (cast `args` instead), drop
+every `JSON.stringify` around a result, `resolve`/`reject`/`emit` payload, and
+return nothing at all where you used to return `"null"`. Requires Node 24 to
+build (scriptc 0.0.35's floor).
+
 ## What the CLI hides
 
 `janela build` assembles `.janela/build/` (runtime + your `main.ts` +
@@ -133,12 +188,12 @@ scriptc. On macOS the frameworks are linked as SDK `.tbd` stubs (scriptc has
 no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 `.app` bundle.
 
-## Constraints inherited from scriptc 0.0.32
+## Constraints inherited from scriptc
 
-- Command args/results cross the boundary as **JSON text** — handlers
-  `JSON.parse` in and `JSON.stringify` out. The runtime keeps the byte channel
-  ASCII by `\uXXXX`-escaping non-ASCII (scriptc strings can't hold lone
-  surrogates, and `JSON.parse` is the reliable reassembly point).
+- Command args and results are ordinary values; the runtime serialises them at
+  the boundary, so anything that survives `JSON.stringify`/`JSON.parse` round
+  trips (including full Unicode). `args` is typed `unknown` — cast it to the
+  shape you expect.
 - Never use a bare FFI call as a complete variable initializer or assignment
   RHS — it is silently miscompiled. Wrap it in any expression (`+ 0`). Plain
   TypeScript is unaffected; only the runtime does FFI, so app code rarely

package/bin/janela.mjs

@@ -166,25 +166,49 @@ function ffiManifest(shimLib) {
     STR("wvInit", "wv_init"),
     STR("wvEval", "wv_eval"),
     STR("wvBind", "wv_bind"),
-    { name: "wvReqLen", symbol: "wv_req_len", params: ["i32"], returns: "i32" },
-    { name: "wvReqByte", symbol: "wv_req_byte", params: ["i32", "i32"], returns: "i32" },
-    { name: "wvReplyReset", symbol: "wv_reply_reset", params: ["i32"], returns: "i32" },
-    { name: "wvReplyPush", symbol: "wv_reply_push", params: ["i32", "i32"], returns: "i32" },
+    STR("wvReply", "wv_reply"),
+    // Retained handlers (format 4): registered once, valid for the app's
+    // lifetime, so wv_run is a plain blocking call. The request rides in as a
+    // `string` param (format 3) rather than a byte-at-a-time drain.
     {
-      name: "wvRun", symbol: "wv_run",
+      name: "wvOnInvoke", symbol: "wv_on_invoke",
       params: [
         "i32",
-        { callback: { id: "run", params: ["u32", "u32", { context: "run" }], returns: "i32", lifetime: "call" } },
-        { context: "run" },
+        { callback: { id: "inv", params: ["string", { context: "inv" }], returns: "i32", lifetime: "retained" } },
+        { context: "inv" },
       ],
       returns: "i32",
     },
+    {
+      name: "wvOnTick", symbol: "wv_on_tick",
+      params: [
+        "i32",
+        { callback: { id: "tick", params: [{ context: "tick" }], returns: "void", lifetime: "retained" } },
+        { context: "tick" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvRun", symbol: "wv_run", params: ["i32"], returns: "i32" },
     { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
     // async: deferred returns + the UI-thread pump behind app.defer/sleep
     { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
     { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
     { name: "wvTickStart", symbol: "wv_tick_start", params: ["i32", "i32"], returns: "i32" },
     { name: "wvTickStop", symbol: "wv_tick_stop", params: ["i32"], returns: "i32" },
+    // async file I/O: the blocking syscall runs on a shim worker thread
+    { name: "wvFsRead", symbol: "wv_fs_read", params: ["i32", "string"], returns: "i32" },
+    { name: "wvFsWrite", symbol: "wv_fs_write", params: ["i32", "string", "string"], returns: "i32" },
+    { name: "wvFsStatus", symbol: "wv_fs_status", params: ["i32", "i32"], returns: "i32" },
+    {
+      name: "wvFsTake", symbol: "wv_fs_take",
+      params: [
+        "i32", "i32",
+        { callback: { id: "sink", params: ["string", { context: "sink" }], returns: "void", lifetime: "call" } },
+        { context: "sink" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvFsFree", symbol: "wv_fs_free", params: ["i32", "i32"], returns: "i32" },
   ];
 
   if (process.platform === "win32") {
@@ -200,7 +224,7 @@ function ffiManifest(shimLib) {
     // "undefined symbol: clock_gettime" — reproducible with a plain
     // `scriptc build hello.ts` on Windows, no FFI involved.
     return {
-      ffi_format: 2,
+      ffi_format: 4,
       functions,
       libraries: [shimLib],
       system_libraries: [
@@ -215,7 +239,7 @@ function ffiManifest(shimLib) {
     // the link as plain input files and ld64 accepts .tbd stubs.
     const sdk = capture(["xcrun", "--sdk", "macosx", "--show-sdk-path"]);
     return {
-      ffi_format: 2,
+      ffi_format: 4,
       functions,
       libraries: [
         shimLib,
@@ -226,7 +250,7 @@ function ffiManifest(shimLib) {
     };
   }
   return {
-    ffi_format: 2,
+    ffi_format: 4,
     functions,
     libraries: [shimLib],
     system_libraries: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "jn": "bin/janela.mjs"
   },
   "dependencies": {
-    "scriptc": "0.0.32"
+    "scriptc": "0.0.35"
   },
   "license": "MIT",
   "author": "Mateus Lage",
@@ -30,7 +30,7 @@
     "scriptc"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "files": [
     "bin/",

package/runtime/janela.ts

@@ -2,12 +2,13 @@
 //
 // The Tauri-shaped surface: one `__invoke` binding carries every command as a
 // (name, argsJson) envelope, dispatched to handlers registered on the app
-// object. Backend→frontend events ride wv_eval into the injected bootstrap.
+// object. Handlers see decoded values — the runtime owns JSON at the boundary.
+// Backend→frontend events ride wv_eval into the injected bootstrap.
 //
 // NOTE ON STYLE: every FFI call whose result initializes a variable is written
-// `f(...) + 0`. scriptc 0.0.32 miscompiles a bare FFI call used as a complete
-// initializer/assignment RHS (see FINDINGS.md); any enclosing expression is
-// the workaround.
+// `f(...) + 0`. scriptc miscompiles a bare FFI call used as a complete
+// initializer/assignment RHS — still true in 0.0.35, and reported upstream as
+// vercel-labs/scriptc#21. Any enclosing expression is the workaround.
 
 declare function wvCreate(debug: number): number;
 declare function wvSetTitle(h: number, title: string): number;
@@ -16,19 +17,23 @@ declare function wvSetHtml(h: number, html: string): number;
 declare function wvInit(h: number, js: string): number;
 declare function wvEval(h: number, js: string): number;
 declare function wvBind(h: number, name: string): number;
-declare function wvReqLen(h: number): number;
-declare function wvReqByte(h: number, i: number): number;
-declare function wvReplyReset(h: number): number;
-declare function wvReplyPush(h: number, b: number): number;
-declare function wvRun(h: number, cb: (bindIndex: number, seq: number) => number): number;
+declare function wvReply(h: number, body: string): number;
+declare function wvOnInvoke(h: number, cb: (req: string) => number): number;
+declare function wvOnTick(h: number, cb: () => void): number;
+declare function wvRun(h: number): number;
 declare function wvTerminate(h: number): number;
 declare function wvDefer(h: number): number;
 declare function wvResolve(h: number, id: number, status: number): number;
 declare function wvTickStart(h: number, intervalMs: number): number;
 declare function wvTickStop(h: number): number;
+declare function wvFsRead(h: number, path: string): number;
+declare function wvFsWrite(h: number, path: string, data: string): number;
+declare function wvFsStatus(h: number, id: number): number;
+declare function wvFsTake(h: number, id: number, sink: (text: string) => void): number;
+declare function wvFsFree(h: number, id: number): number;
 
-// Bind index the shim uses for a timer tick rather than a page invoke.
-const TICK_BIND = 4294967295;
+const FS_PENDING = 0;
+const FS_OK = 1;
 
 // Injected into every page before it loads (webview_init).
 const BOOTSTRAP =
@@ -47,23 +52,35 @@ const BOOTSTRAP =
   "  for (var i = 0; i < cbs.length; i++) cbs[i](payload);" +
   "};";
 
-// Handlers receive the invoke args as JSON text and must return JSON text
-// (what the frontend promise resolves with). Throwing is not supported by
-// scriptc across the FFI boundary — return an error envelope instead.
-export type CommandHandler = (argsJson: string) => string;
+// Handlers take the invoked arguments as a value and return a value; the
+// runtime owns JSON at the boundary. `args` is whatever the page passed to
+// janela.invoke(name, args) — cast it to the shape you expect. The return
+// value is what the page's promise resolves with.
+//
+// Throwing is not supported by scriptc across the FFI boundary. Use
+// commandAsync's `reject` to fail a call, or return an error value.
+export type CommandHandler = (args: unknown) => unknown;
 
 /**
  * An async command: return immediately, answer later. `resolve`/`reject` take
- * JSON text and settle the page's `await janela.invoke(...)` promise whenever
+ * a value and settle the page's `await janela.invoke(...)` promise whenever
  * they are called — from a later defer()/sleep() turn, or from another
  * command. The window stays responsive for as long as the call is pending.
  */
 export type AsyncCommandHandler = (
-  argsJson: string,
-  resolve: (json: string) => void,
-  reject: (json: string) => void,
+  args: unknown,
+  resolve: (value: unknown) => void,
+  reject: (reason: unknown) => void,
 ) => void;
 
+/**
+ * Completion of an async file operation. `err` is null on success; on failure
+ * it carries a Node-shaped message ("ENOENT: no such file or directory, open
+ * '/x'") and `text` is empty. Errors arrive as values, never as throws —
+ * scriptc cannot propagate an exception across the FFI boundary.
+ */
+export type FsCallback = (err: string | null, text: string) => void;
+
 export interface WindowConfig {
   title: string;
   width: number;
@@ -83,85 +100,32 @@ export interface JanelaApp {
   /** Run fn after at least ms. The host loop's timer; scriptc's setTimeout
    *  cannot fire while the window is open (its loop is parked inside run()). */
   sleep: (ms: number, fn: () => void) => void;
-  /** Fire an event into the page; payloadJson must be valid JSON text. */
-  emit: (event: string, payloadJson: string) => void;
+  /**
+   * Read a file without blocking the window. The syscall runs on a shim
+   * worker thread; the callback lands on the UI thread on a later turn.
+   * Prefer this over node:fs readFileSync inside a command — that one blocks
+   * the loop, and with it the whole window.
+   */
+  readFileAsync: (path: string, cb: FsCallback) => void;
+  /** Write a file without blocking the window; cb(null) on success. */
+  writeFileAsync: (
+    path: string,
+    data: string,
+    cb: (err: string | null) => void,
+  ) => void;
+  /** Fire an event into the page; the payload is delivered as a value. */
+  emit: (event: string, payload: unknown) => void;
   /** Close the window and make run() return. */
   quit: () => void;
   /** Show the page and block until the window closes. Returns the run status. */
   run: (html: string) => number;
 }
 
-const HEX = "0123456789abcdef";
-
-function uEscape(unit: number): string {
-  return (
-    "\\u" +
-    HEX.charAt((unit >> 12) & 0xf) +
-    HEX.charAt((unit >> 8) & 0xf) +
-    HEX.charAt((unit >> 4) & 0xf) +
-    HEX.charAt(unit & 0xf)
-  );
-}
-
-// The request arrives as UTF-8 JSON bytes. scriptc strings cannot hold lone
-// surrogates (String.fromCharCode(0xd83d) yields a replacement char), so we
-// never build non-ASCII chars directly: every code point >= 0x80 is re-emitted
-// as a JSON \uXXXX escape (a surrogate PAIR of escapes for astral planes),
-// which JSON.parse reconstructs correctly. Legal only because the payload is
-// always JSON, where non-ASCII can only occur inside strings.
-function readRequest(h: number): string {
-  let out = "";
-  const n = wvReqLen(h) + 0;
-  let i = 0;
-  while (i < n) {
-    const b0 = wvReqByte(h, i) + 0;
-    i = i + 1;
-    let cp = b0;
-    if ((b0 & 0xe0) === 0xc0 && i < n) {
-      cp = ((b0 & 0x1f) << 6) | (wvReqByte(h, i) & 0x3f);
-      i = i + 1;
-    } else if ((b0 & 0xf0) === 0xe0 && i + 1 < n) {
-      cp = ((b0 & 0x0f) << 12) | ((wvReqByte(h, i) & 0x3f) << 6) | (wvReqByte(h, i + 1) & 0x3f);
-      i = i + 2;
-    } else if ((b0 & 0xf8) === 0xf0 && i + 2 < n) {
-      cp =
-        ((b0 & 0x07) << 18) |
-        ((wvReqByte(h, i) & 0x3f) << 12) |
-        ((wvReqByte(h, i + 1) & 0x3f) << 6) |
-        (wvReqByte(h, i + 2) & 0x3f);
-      i = i + 3;
-    }
-    if (cp < 0x80) {
-      out = out + String.fromCharCode(cp);
-    } else if (cp < 0x10000) {
-      out = out + uEscape(cp);
-    } else {
-      const v = cp - 0x10000;
-      out = out + uEscape(0xd800 + (v >> 10)) + uEscape(0xdc00 + (v & 0x3ff));
-    }
-  }
-  return out;
-}
-
-// The reply must be valid JSON when it reaches the page. Non-ASCII chars can
-// only legally occur inside JSON strings, where a \uXXXX escape is always
-// equivalent — so escaping every char >127 keeps the byte channel ASCII-clean
-// (surrogate halves escape individually, which JSON also permits).
-function writeReply(h: number, body: string): void {
-  wvReplyReset(h);
-  for (let i = 0; i < body.length; i++) {
-    const c = body.charCodeAt(i);
-    if (c < 0x80) {
-      wvReplyPush(h, c);
-    } else {
-      wvReplyPush(h, 92); // backslash
-      wvReplyPush(h, 117); // 'u'
-      wvReplyPush(h, HEX.charCodeAt((c >> 12) & 0xf));
-      wvReplyPush(h, HEX.charCodeAt((c >> 8) & 0xf));
-      wvReplyPush(h, HEX.charCodeAt((c >> 4) & 0xf));
-      wvReplyPush(h, HEX.charCodeAt(c & 0xf));
-    }
-  }
+// JSON.stringify yields undefined for undefined; the wire always needs a
+// value, and a command that returns nothing should read as null in the page.
+function encode(value: unknown): string {
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
 }
 
 export function createApp(cfg: WindowConfig): JanelaApp {
@@ -173,14 +137,16 @@ export function createApp(cfg: WindowConfig): JanelaApp {
   // ---- the host loop -------------------------------------------------------
   // scriptc's event loop is parked for as long as the program sits inside the
   // wvRun() FFI call, so setTimeout/await never fire while the window is open.
-  // These queues are drained instead by TICK_BIND callbacks that the shim's
-  // ticker posts to the UI thread, and the ticker only runs while there is
-  // work — an idle app costs nothing.
+  // These queues are drained instead by the retained tick handler that the
+  // shim's ticker posts to the UI thread, and the ticker only runs while there
+  // is work — an idle app costs nothing.
   const asyncNames: string[] = [];
   const asyncHandlers: AsyncCommandHandler[] = [];
   let taskFns: (() => void)[] = [];
   let timerFns: (() => void)[] = [];
   let timerDue: number[] = [];
+  let fsIds: number[] = [];
+  let fsCbs: FsCallback[] = [];
   let ticking = false;
 
   const wake = (): void => {
@@ -191,7 +157,7 @@ export function createApp(cfg: WindowConfig): JanelaApp {
 
   const idle = (): void => {
     if (!ticking) return;
-    if (taskFns.length > 0 || timerFns.length > 0) return;
+    if (taskFns.length > 0 || timerFns.length > 0 || fsIds.length > 0) return;
     ticking = false;
     wvTickStop(h);
   };
@@ -221,6 +187,44 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       timerDue = keptDue;
       for (let i = 0; i < fire.length; i++) fire[i]();
     }
+
+    // Finished file jobs: the worker thread has already done the blocking
+    // syscall, so all that happens on this (UI) thread is the drain.
+    if (fsIds.length > 0) {
+      const keptIds: number[] = [];
+      const keptCbs: FsCallback[] = [];
+      const doneIds: number[] = [];
+      const doneCbs: FsCallback[] = [];
+      const doneOk: boolean[] = [];
+      for (let i = 0; i < fsIds.length; i++) {
+        const st = wvFsStatus(h, fsIds[i]) + 0;
+        if (st === FS_PENDING) {
+          keptIds.push(fsIds[i]);
+          keptCbs.push(fsCbs[i]);
+        } else {
+          doneIds.push(fsIds[i]);
+          doneCbs.push(fsCbs[i]);
+          doneOk.push(st === FS_OK);
+        }
+      }
+      fsIds = keptIds;
+      fsCbs = keptCbs;
+      for (let i = 0; i < doneIds.length; i++) {
+        // On failure the payload IS the error message, so one take serves both
+        // outcomes. The sink runs synchronously inside wvFsTake (the callback
+        // is lifetime:"call"), so `payload` is set by the time it returns.
+        let payload = "";
+        wvFsTake(h, doneIds[i], (text) => {
+          payload = text;
+        });
+        wvFsFree(h, doneIds[i]);
+        if (doneOk[i]) {
+          doneCbs[i](null, payload);
+        } else {
+          doneCbs[i](payload, "");
+        }
+      }
+    }
     idle();
   };
 
@@ -250,10 +254,34 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       wake();
     },
 
-    emit: (event, payloadJson) => {
+    readFileAsync: (path, cb) => {
+      const id = wvFsRead(h, path) + 0;
+      if (id < 0) {
+        app.defer(() => cb("EAGAIN: could not start a read of '" + path + "'", ""));
+        return;
+      }
+      fsIds.push(id);
+      fsCbs.push(cb);
+      wake();
+    },
+
+    writeFileAsync: (path, data, cb) => {
+      const id = wvFsWrite(h, path, data) + 0;
+      if (id < 0) {
+        app.defer(() => cb("EAGAIN: could not start a write of '" + path + "'"));
+        return;
+      }
+      fsIds.push(id);
+      // The write payload is empty on success; the shared callback shape just
+      // ignores the text argument.
+      fsCbs.push((err, _text) => cb(err));
+      wake();
+    },
+
+    emit: (event, payload) => {
       wvEval(
         h,
-        "window.__wvEmit(" + JSON.stringify(event) + "," + payloadJson + ");",
+        "window.__wvEmit(" + JSON.stringify(event) + "," + encode(payload) + ");",
       );
     },
 
@@ -262,26 +290,16 @@ export function createApp(cfg: WindowConfig): JanelaApp {
     },
 
     run: (html) => {
-      const INVOKE = wvBind(h, "__invoke") + 0;
-      wvSetHtml(h, html);
-
-      const rc = wvRun(h, (bindIndex, _seq) => {
-        // A tick is not an invoke: nothing is waiting on a reply, so the
-        // shim never calls webview_return for it.
-        if (bindIndex === TICK_BIND) {
-          turn();
-          return 0;
-        }
-        if (bindIndex !== INVOKE) {
-          writeReply(h, '"unknown binding"');
-          return 1;
-        }
-        const env = JSON.parse(readRequest(h)) as string[];
+      // Both handlers are retained: registered once here, called by the shim
+      // for as long as the window is open.
+      wvOnTick(h, turn);
+      wvOnInvoke(h, (req) => {
+        const env = JSON.parse(req) as string[];
         const cmd = env[0];
-        const argsJson = env[1];
+        const args = JSON.parse(env[1]) as unknown;
         for (let i = 0; i < app.names.length; i++) {
           if (app.names[i] === cmd) {
-            writeReply(h, app.handlers[i](argsJson));
+            wvReply(h, encode(app.handlers[i](args)));
             return 0;
           }
         }
@@ -292,25 +310,29 @@ export function createApp(cfg: WindowConfig): JanelaApp {
             // that is. Meanwhile the loop is free to serve other calls.
             const id = wvDefer(h) + 0;
             if (id < 0) {
-              writeReply(h, JSON.stringify("cannot defer command: " + cmd));
+              wvReply(h, encode("cannot defer command: " + cmd));
               return 1;
             }
-            const settle = (status: number): ((json: string) => void) => {
+            const settle = (status: number): ((value: unknown) => void) => {
               let done = false;
-              return (json: string) => {
+              return (value: unknown) => {
                 if (done) return; // a promise settles once
                 done = true;
-                writeReply(h, json);
+                wvReply(h, encode(value));
                 wvResolve(h, id, status);
               };
             };
-            asyncHandlers[i](argsJson, settle(0), settle(1));
+            asyncHandlers[i](args, settle(0), settle(1));
             return 0;
           }
         }
-        writeReply(h, JSON.stringify("unknown command: " + cmd));
+        wvReply(h, encode("unknown command: " + cmd));
         return 1; // rejects the frontend promise
-      }) + 0;
+      });
+
+      wvBind(h, "__invoke");
+      wvSetHtml(h, html);
+      const rc = wvRun(h) + 0;
       return rc;
     },
   };

package/shim/wvshim.cc

@@ -1,15 +1,17 @@
-// wvshim.cc — a C-ABI shim over webview.h shaped to scriptc's FFI format 2.
+// wvshim.cc — a C-ABI shim over webview.h shaped to scriptc's FFI format 4.
 //
-// Three constraints drive every design decision here:
-//   1. scriptc has no pointer/u64 type, so webview_t can never cross the
-//      boundary. We keep a handle table and hand out int32 indices.
-//   2. Callback params/returns are numeric scalars only, so the request JSON
-//      cannot be passed as a callback argument. We stage it in a shim-side
-//      buffer and let TS drain it byte-at-a-time via re-entrant FFI calls.
-//   3. Callbacks are lifetime:"call" only. webview_bind wants a retained
-//      callback, which is not expressible. Instead the TS callback is handed
-//      to wv_run(), which blocks for the whole app lifetime — so "call scope"
-//      and "app lifetime" coincide, and bind dispatch happens inside it.
+// One constraint still drives the design: scriptc has no pointer/u64 type, so
+// webview_t can never cross the boundary. We keep a handle table and hand out
+// int32 indices.
+//
+// What the newer formats removed:
+//   * format 3 — callback params may be `string`/`bytes`, so a payload crosses
+//     into TS as one argument instead of one FFI call per byte. Payloads going
+//     the other way ride `string` params on ordinary functions.
+//   * format 4 — callbacks may be `retained`, so the invoke and tick handlers
+//     are registered once and live for the app's lifetime. wv_run() is a plain
+//     blocking call again; it no longer has to carry a callback whose "call
+//     scope" was standing in for "app lifetime".
 
 #include "webview.h"
 
@@ -17,6 +19,10 @@
 #include <chrono>
 #include <cstdint>
 #include <cstring>
+#include <filesystem>
+#include <fstream>
+#include <memory>
+#include <mutex>
 #include <string>
 #include <thread>
 #include <vector>
@@ -39,14 +45,17 @@ struct App {
   bool used = false;
   std::vector<Bind> binds;
 
-  // Callback supplied by TS for the duration of wv_run().
-  int32_t (*cb)(uint32_t, uint32_t, void *) = nullptr;
-  void *cb_ctx = nullptr;
+  // Retained TS handlers, registered once and valid until the app exits. The
+  // request rides in as a (ptr, len) string param.
+  int32_t (*on_invoke)(const uint8_t *, size_t, void *) = nullptr;
+  void *on_invoke_ctx = nullptr;
+  void (*on_tick)(void *) = nullptr;
+  void *on_tick_ctx = nullptr;
 
   // Staging for the in-flight request.
   std::string req;      // JSON args array from JS
   std::string cur_id;   // webview's call id, needed by webview_return
-  std::string reply;    // response body assembled by TS
+  std::string reply;    // response body handed over by TS in one call
   uint32_t seq = 0;
 
   // ---- async support ----
@@ -57,10 +66,6 @@ struct App {
   std::atomic<int32_t> tick_ms{16};
 };
 
-// Bind index handed to the TS callback for a timer tick rather than an
-// invoke. Real bind indices are small sequential integers.
-const uint32_t TICK_BIND = 0xffffffffu;
-
 // Fixed-size table: handles are indices, never pointers.
 App g_apps[8];
 
@@ -74,14 +79,127 @@ std::string to_str(const uint8_t *p, size_t n) {
   return std::string(reinterpret_cast<const char *>(p), n);
 }
 
-// The single C trampoline registered with webview_bind for every binding.
-// `arg` encodes the app index and bind index.
+// ---- file I/O jobs ---------------------------------------------------------
+//
+// The whole point of this subsystem is that the blocking syscall happens HERE,
+// on a worker thread, and never on the UI thread. A worker touches only its
+// own job and never calls into TS — scriptc's runtime is not thread-safe, so
+// results cross back on the UI thread, drained by the tick loop.
+
+const int32_t FS_PENDING = 0;
+const int32_t FS_OK = 1;
+const int32_t FS_ERROR = 2;
+
+struct FsJob {
+  // Written by the worker before `status` flips; read by the UI thread only
+  // after it observes a terminal status. The release/acquire pair on `status`
+  // is what publishes `data`, so no lock is needed for the payload itself.
+  std::atomic<int32_t> status{FS_PENDING};
+  std::string data;  // file contents on success, the error message on failure
+  std::thread worker;
+  bool used = false;
+};
+
+// Jobs are addressed by index and held behind unique_ptr so the vector may
+// grow without invalidating a worker's pointer to its own job.
+std::mutex g_fs_mu;
+std::vector<std::unique_ptr<FsJob>> g_fs_jobs;
+
+FsJob *fs_job_at(int32_t id) {
+  std::lock_guard<std::mutex> lock(g_fs_mu);
+  if (id < 0 || static_cast<size_t>(id) >= g_fs_jobs.size()) return nullptr;
+  FsJob *j = g_fs_jobs[id].get();
+  return j->used ? j : nullptr;
+}
+
+// Reuses a finished slot when one is free, so a long-running app that reads
+// many files does not grow the table without bound.
+int32_t fs_new_job() {
+  std::lock_guard<std::mutex> lock(g_fs_mu);
+  for (size_t i = 0; i < g_fs_jobs.size(); i++) {
+    if (g_fs_jobs[i]->used) continue;
+    if (g_fs_jobs[i]->worker.joinable()) g_fs_jobs[i]->worker.join();
+    g_fs_jobs[i]->status.store(FS_PENDING);
+    g_fs_jobs[i]->data.clear();
+    g_fs_jobs[i]->used = true;
+    return static_cast<int32_t>(i);
+  }
+  g_fs_jobs.push_back(std::unique_ptr<FsJob>(new FsJob()));
+  g_fs_jobs.back()->used = true;
+  return static_cast<int32_t>(g_fs_jobs.size() - 1);
+}
+
+// Node-shaped messages: janela apps already surface node:fs errors from
+// synchronous handlers, so the async path should read the same.
+std::string fs_error_message(const std::string &path, const char *op) {
+  std::error_code ec;
+  auto st = std::filesystem::status(path, ec);
+  if (st.type() == std::filesystem::file_type::not_found) {
+    return "ENOENT: no such file or directory, " + std::string(op) + " '" +
+           path + "'";
+  }
+  if (st.type() == std::filesystem::file_type::directory) {
+    return "EISDIR: illegal operation on a directory, " + std::string(op) +
+           " '" + path + "'";
+  }
+  return "EIO: failed to " + std::string(op) + " '" + path + "'";
+}
+
+void fs_finish(FsJob *j, int32_t status, std::string payload) {
+  j->data = std::move(payload);
+  j->status.store(status, std::memory_order_release);
+}
+
+void fs_read_worker(FsJob *j, std::string path) {
+  std::error_code ec;
+  if (std::filesystem::is_directory(path, ec)) {
+    fs_finish(j, FS_ERROR, fs_error_message(path, "read"));
+    return;
+  }
+  std::ifstream in(path, std::ios::binary);
+  if (!in) {
+    fs_finish(j, FS_ERROR, fs_error_message(path, "open"));
+    return;
+  }
+  std::string buf((std::istreambuf_iterator<char>(in)),
+                  std::istreambuf_iterator<char>());
+  if (in.bad()) {
+    fs_finish(j, FS_ERROR, fs_error_message(path, "read"));
+    return;
+  }
+  fs_finish(j, FS_OK, std::move(buf));
+}
+
+void fs_write_worker(FsJob *j, std::string path, std::string data) {
+  std::ofstream out(path, std::ios::binary | std::ios::trunc);
+  if (!out) {
+    fs_finish(j, FS_ERROR, fs_error_message(path, "open"));
+    return;
+  }
+  out.write(data.data(), static_cast<std::streamsize>(data.size()));
+  out.flush();
+  if (!out) {
+    fs_finish(j, FS_ERROR, fs_error_message(path, "write"));
+    return;
+  }
+  fs_finish(j, FS_OK, std::string());
+}
+
+// Join every worker. Called at shutdown so no thread outlives the process's
+// orderly exit (and so nothing writes into a job after main returns).
+void fs_join_all() {
+  std::lock_guard<std::mutex> lock(g_fs_mu);
+  for (size_t i = 0; i < g_fs_jobs.size(); i++) {
+    if (g_fs_jobs[i]->worker.joinable()) g_fs_jobs[i]->worker.join();
+  }
+}
+
+// The single C trampoline registered with webview_bind. `arg` is the app
+// index; every binding routes to the one retained invoke handler.
 void trampoline(const char *id, const char *req, void *arg) {
-  uintptr_t packed = reinterpret_cast<uintptr_t>(arg);
-  App *a = &g_apps[packed >> 32];
-  uint32_t bind_index = static_cast<uint32_t>(packed & 0xffffffffu);
+  App *a = &g_apps[reinterpret_cast<uintptr_t>(arg)];
 
-  if (!a->cb) return;  // no TS handler installed
+  if (!a->on_invoke) return;  // no TS handler installed
 
   a->req = req ? req : "";
   a->cur_id = id ? id : "";
@@ -89,9 +207,11 @@ void trampoline(const char *id, const char *req, void *arg) {
   a->deferred = false;
   a->seq++;
 
-  // Re-entrancy: this call lands back in TS, which will call wv_req_byte()
-  // etc. back into this shim before returning.
-  int32_t status = a->cb(bind_index, a->seq, a->cb_ctx);
+  // Re-entrancy: this call lands back in TS, which calls wv_reply() back into
+  // this shim before returning.
+  int32_t status = a->on_invoke(
+      reinterpret_cast<const uint8_t *>(a->req.data()), a->req.size(),
+      a->on_invoke_ctx);
 
   // An async handler called wv_defer(): the call id now lives in the pending
   // table and wv_resolve() will answer the page later. Returning now would
@@ -114,9 +234,9 @@ void trampoline(const char *id, const char *req, void *arg) {
 // TS it calls stays single-threaded — scriptc's runtime is NOT thread-safe.
 void tick_on_ui_thread(webview_t, void *arg) {
   App *a = &g_apps[reinterpret_cast<uintptr_t>(arg)];
-  if (!a->used || !a->cb) return;  // app quit between dispatch and delivery
+  if (!a->used || !a->on_tick) return;  // app quit between dispatch and delivery
   a->seq++;
-  a->cb(TICK_BIND, a->seq, a->cb_ctx);
+  a->on_tick(a->on_tick_ctx);
 }
 
 }  // namespace
@@ -131,8 +251,10 @@ int32_t wv_create(int32_t debug) {
     // Field-wise reset: App holds a thread and atomics, so it is not
     // copy-assignable from a temporary.
     g_apps[i].binds.clear();
-    g_apps[i].cb = nullptr;
-    g_apps[i].cb_ctx = nullptr;
+    g_apps[i].on_invoke = nullptr;
+    g_apps[i].on_invoke_ctx = nullptr;
+    g_apps[i].on_tick = nullptr;
+    g_apps[i].on_tick_ctx = nullptr;
     g_apps[i].req.clear();
     g_apps[i].cur_id.clear();
     g_apps[i].reply.clear();
@@ -189,40 +311,20 @@ int32_t wv_eval(int32_t h, const uint8_t *p, size_t n) {
 int32_t wv_bind(int32_t h, const uint8_t *p, size_t n) {
   App *a = app_at(h);
   if (!a) return -1;
-  uint32_t idx = static_cast<uint32_t>(a->binds.size());
+  size_t idx = a->binds.size();
   a->binds.push_back(Bind{to_str(p, n)});
-  uintptr_t packed = (static_cast<uintptr_t>(h) << 32) | idx;
   int rc = webview_bind(a->w, a->binds[idx].name.c_str(), trampoline,
-                        reinterpret_cast<void *>(packed));
+                        reinterpret_cast<void *>(static_cast<uintptr_t>(h)));
   if (rc != WEBVIEW_ERROR_OK) return -1;
   return static_cast<int32_t>(idx);
 }
 
-// ---- request payload, drained byte-at-a-time from inside the TS callback ----
-int32_t wv_req_len(int32_t h) {
+// Stage the response body for the call being handled (or, after wv_defer, for
+// the pending call that wv_resolve will answer). One call, whole payload.
+int32_t wv_reply(int32_t h, const uint8_t *p, size_t n) {
   App *a = app_at(h);
   if (!a) return -1;
-  return static_cast<int32_t>(a->req.size());
-}
-
-int32_t wv_req_byte(int32_t h, int32_t i) {
-  App *a = app_at(h);
-  if (!a || i < 0 || static_cast<size_t>(i) >= a->req.size()) return -1;
-  return static_cast<uint8_t>(a->req[i]);
-}
-
-// ---- reply payload, pushed byte-at-a-time from inside the TS callback ----
-int32_t wv_reply_reset(int32_t h) {
-  App *a = app_at(h);
-  if (!a) return -1;
-  a->reply.clear();
-  return 0;
-}
-
-int32_t wv_reply_push(int32_t h, int32_t byte) {
-  App *a = app_at(h);
-  if (!a) return -1;
-  a->reply.push_back(static_cast<char>(byte & 0xff));
+  a->reply.assign(reinterpret_cast<const char *>(p), n);
   return 0;
 }
 
@@ -268,7 +370,7 @@ int32_t wv_resolve(int32_t h, int32_t id, int32_t status) {
   return 0;
 }
 
-// Start pumping TS with TICK_BIND callbacks every interval_ms. The thread
+// Start pumping the retained tick handler every interval_ms. The thread
 // itself only sleeps and posts; all TS execution happens on the UI thread.
 int32_t wv_tick_start(int32_t h, int32_t interval_ms) {
   App *a = app_at(h);
@@ -295,19 +397,100 @@ int32_t wv_tick_stop(int32_t h) {
   return 0;
 }
 
-// Blocks for the app's lifetime; dispatches bind calls into `cb`.
-int32_t wv_run(int32_t h, int32_t (*cb)(uint32_t, uint32_t, void *),
-               void *cb_ctx) {
+// ---- async file I/O ---------------------------------------------------------
+//
+// wv_fs_read/wv_fs_write start a worker thread and return immediately with a
+// job id. TS polls wv_fs_status() from its tick loop and drains the payload
+// with wv_fs_byte() once the job is terminal. On failure the payload is the
+// error message, so success and failure share one drain path.
+
+int32_t wv_fs_read(int32_t h, const uint8_t *p, size_t n) {
+  if (!app_at(h)) return -1;
+  int32_t id = fs_new_job();
+  FsJob *j = fs_job_at(id);
+  if (!j) return -1;
+  j->worker = std::thread(fs_read_worker, j, to_str(p, n));
+  return id;
+}
+
+int32_t wv_fs_write(int32_t h, const uint8_t *p, size_t n, const uint8_t *dp,
+                    size_t dn) {
+  if (!app_at(h)) return -1;
+  int32_t id = fs_new_job();
+  FsJob *j = fs_job_at(id);
+  if (!j) return -1;
+  j->worker = std::thread(fs_write_worker, j, to_str(p, n), to_str(dp, dn));
+  return id;
+}
+
+// 0 = still running, 1 = done, 2 = failed, -1 = no such job.
+int32_t wv_fs_status(int32_t h, int32_t id) {
+  if (!app_at(h)) return -1;
+  FsJob *j = fs_job_at(id);
+  if (!j) return -1;
+  return j->status.load(std::memory_order_acquire);
+}
+
+// Hand a finished job's payload to TS in one call. The callback is
+// lifetime:"call", so it runs synchronously here — on the UI thread, the only
+// thread allowed to touch the scriptc runtime. The worker is already done by
+// then (the caller has observed a terminal status), so `data` is stable.
+int32_t wv_fs_take(int32_t h, int32_t id,
+                   void (*sink)(const uint8_t *, size_t, void *), void *ctx) {
+  if (!app_at(h)) return -1;
+  FsJob *j = fs_job_at(id);
+  if (!j || !sink) return -1;
+  if (j->status.load(std::memory_order_acquire) == FS_PENDING) return -1;
+  sink(reinterpret_cast<const uint8_t *>(j->data.data()), j->data.size(), ctx);
+  return 0;
+}
+
+// Release the slot for reuse. Refuses while the worker is still running, so a
+// job's buffer can never be recycled out from under its own thread.
+int32_t wv_fs_free(int32_t h, int32_t id) {
+  if (!app_at(h)) return -1;
+  FsJob *j = fs_job_at(id);
+  if (!j) return -1;
+  if (j->status.load(std::memory_order_acquire) == FS_PENDING) return -1;
+  std::lock_guard<std::mutex> lock(g_fs_mu);
+  if (j->worker.joinable()) j->worker.join();
+  j->data.clear();
+  j->data.shrink_to_fit();
+  j->used = false;
+  return 0;
+}
+
+// Register the retained handler for page invokes. Valid until the app exits.
+int32_t wv_on_invoke(int32_t h,
+                     int32_t (*cb)(const uint8_t *, size_t, void *),
+                     void *ctx) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  a->on_invoke = cb;
+  a->on_invoke_ctx = ctx;
+  return 0;
+}
+
+// Register the retained handler the ticker pumps on the UI thread.
+int32_t wv_on_tick(int32_t h, void (*cb)(void *), void *ctx) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  a->on_tick = cb;
+  a->on_tick_ctx = ctx;
+  return 0;
+}
+
+// Blocks for the app's lifetime, dispatching into the retained handlers.
+int32_t wv_run(int32_t h) {
   App *a = app_at(h);
   if (!a) return -1;
-  a->cb = cb;
-  a->cb_ctx = cb_ctx;
   int rc = webview_run(a->w);
-  // The ticker must not outlive the callback it drives.
+  // Nothing may call into TS once run() has returned.
   a->ticking.store(false);
   if (a->ticker.joinable()) a->ticker.join();
-  a->cb = nullptr;  // callback must not outlive the call, per lifetime:"call"
-  a->cb_ctx = nullptr;
+  fs_join_all();  // nor may an in-flight read outlive the app
+  a->on_invoke = nullptr;
+  a->on_tick = nullptr;
   return rc;
 }
 

package/templates/index.html

@@ -17,6 +17,10 @@
       <button id="wait">wait 2s (async)</button>
       <button id="quit">Quit</button>
     </p>
+    <p>
+      <input id="path" type="text" value="janela.conf.json" size="32" />
+      <button id="read">read file (async)</button>
+    </p>
     <pre id="out">booting…</pre>
     <ul id="events"></ul>
 
@@ -51,6 +55,16 @@
           e.target.disabled = false;
         };
 
+        // Reads run on a worker thread in the shim, so even a large file
+        // does not freeze the window while it loads.
+        document.getElementById("read").onclick = async () => {
+          const path = document.getElementById("path").value;
+          const r = await janela.invoke("readFile", { path });
+          out.textContent = r.ok
+            ? `${path}: ${r.length} chars\n\n` + r.text.slice(0, 400)
+            : "error: " + r.error;
+        };
+
         document.getElementById("quit").onclick = () => janela.invoke("quit");
       };
     </script>

package/templates/main.ts

@@ -1,46 +1,57 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
 // Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers receive the args as JSON text and return JSON text (what the
-// frontend promise resolves with).
+// Handlers take the arguments as a value and return a value — the runtime owns
+// JSON at the boundary, so there is no parsing or stringifying to do here.
 //
-// Gotcha inherited from scriptc 0.0.32: never use a bare FFI-backed call as a
+// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
 // complete variable initializer — wrap it in any expression (`+ 0`). Plain
 // TypeScript like everything in this file is unaffected.
 
 import type { JanelaApp } from "./janela";
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (argsJson) => {
-    const a = JSON.parse(argsJson) as { a: number; b: number };
+  app.command("add", (args) => {
+    const a = args as { a: number; b: number };
     const sum = a.a + a.b;
     // Backend→frontend event, just to show the channel exists.
-    app.emit("added", JSON.stringify(sum));
-    return JSON.stringify(sum);
+    app.emit("added", sum);
+    return sum;
   });
 
-  app.command("greet", (argsJson) => {
-    const a = JSON.parse(argsJson) as { name: string };
-    return JSON.stringify("Hello, " + a.name + " — from the native TS binary");
+  app.command("greet", (args) => {
+    const a = args as { name: string };
+    return "Hello, " + a.name + " — from the native TS binary";
   });
 
-  app.command("log", (argsJson) => {
-    const a = JSON.parse(argsJson) as string;
-    console.log("[host] page says:", a);
-    return "null";
+  app.command("log", (args) => {
+    console.log("[host] page says:", args as string);
   });
 
   // An async command: answers later, without freezing the window. The page
   // still just does `await janela.invoke("wait", { ms: 1000 })`.
-  app.commandAsync("wait", (argsJson, resolve) => {
-    const a = JSON.parse(argsJson) as { ms: number };
+  app.commandAsync("wait", (args, resolve) => {
+    const a = args as { ms: number };
     app.sleep(a.ms, () => {
-      resolve(JSON.stringify("waited " + a.ms + "ms without blocking the UI"));
+      resolve("waited " + a.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", (_argsJson) => {
+  // File I/O without freezing the window: the read happens on a worker thread
+  // in the shim. Use this instead of node:fs readFileSync, which blocks the
+  // host loop — and with it the whole UI — until the syscall returns.
+  app.commandAsync("readFile", (args, resolve) => {
+    const a = args as { path: string };
+    app.readFileAsync(a.path, (err, text) => {
+      if (err !== null) {
+        resolve({ ok: false, error: err });
+        return;
+      }
+      resolve({ ok: true, length: text.length, text: text });
+    });
+  });
+
+  app.command("quit", (_args) => {
     app.quit();
-    return "null";
   });
 }