janela 0.1.1 → 0.2.0

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,12 +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;
+
+const FS_PENDING = 0;
+const FS_OK = 1;
 
 // Injected into every page before it loads (webview_init).
 const BOOTSTRAP =
@@ -40,10 +52,34 @@ 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
+ * 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 = (
+  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;
@@ -57,85 +93,39 @@ export interface JanelaApp {
   handlers: CommandHandler[];
   /** Register a named command, callable from the page as janela.invoke(name, args). */
   command: (name: string, h: CommandHandler) => void;
-  /** Fire an event into the page; payloadJson must be valid JSON text. */
-  emit: (event: string, payloadJson: string) => void;
+  /** Register a command that answers later; see AsyncCommandHandler. */
+  commandAsync: (name: string, h: AsyncCommandHandler) => void;
+  /** Run fn on the next turn of the host loop — the way to slice long work. */
+  defer: (fn: () => void) => void;
+  /** 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;
+  /**
+   * 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 {
@@ -144,6 +134,100 @@ export function createApp(cfg: WindowConfig): JanelaApp {
   wvSetSize(h, cfg.width, cfg.height, 0);
   wvInit(h, BOOTSTRAP);
 
+  // ---- 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 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 => {
+    if (ticking) return;
+    ticking = true;
+    wvTickStart(h, 8);
+  };
+
+  const idle = (): void => {
+    if (!ticking) return;
+    if (taskFns.length > 0 || timerFns.length > 0 || fsIds.length > 0) return;
+    ticking = false;
+    wvTickStop(h);
+  };
+
+  // One turn of the loop: every task queued so far, plus every due timer.
+  // Tasks queued *by* this turn wait for the next one, so a defer() chain
+  // yields to the UI between slices instead of starving it.
+  const turn = (): void => {
+    const tasks = taskFns;
+    taskFns = [];
+    for (let i = 0; i < tasks.length; i++) tasks[i]();
+
+    if (timerFns.length > 0) {
+      const now = Date.now() + 0;
+      const keptFns: (() => void)[] = [];
+      const keptDue: number[] = [];
+      const fire: (() => void)[] = [];
+      for (let i = 0; i < timerFns.length; i++) {
+        if (timerDue[i] <= now) {
+          fire.push(timerFns[i]);
+        } else {
+          keptFns.push(timerFns[i]);
+          keptDue.push(timerDue[i]);
+        }
+      }
+      timerFns = keptFns;
+      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();
+  };
+
   const app: JanelaApp = {
     handle: h,
     names: [],
@@ -154,10 +238,50 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       app.handlers.push(handler);
     },
 
-    emit: (event, payloadJson) => {
+    commandAsync: (name, handler) => {
+      asyncNames.push(name);
+      asyncHandlers.push(handler);
+    },
+
+    defer: (fn) => {
+      taskFns.push(fn);
+      wake();
+    },
+
+    sleep: (ms, fn) => {
+      timerFns.push(fn);
+      timerDue.push(Date.now() + (ms > 0 ? ms : 0));
+      wake();
+    },
+
+    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) + ");",
       );
     },
 
@@ -166,26 +290,49 @@ export function createApp(cfg: WindowConfig): JanelaApp {
     },
 
     run: (html) => {
-      const INVOKE = wvBind(h, "__invoke") + 0;
-      wvSetHtml(h, html);
-
-      const rc = wvRun(h, (bindIndex, _seq) => {
-        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;
           }
         }
-        writeReply(h, JSON.stringify("unknown command: " + cmd));
+        for (let i = 0; i < asyncNames.length; i++) {
+          if (asyncNames[i] === cmd) {
+            // Park the page's promise: the shim holds this call's id and
+            // answers it when resolve/reject reaches wvResolve, whenever
+            // that is. Meanwhile the loop is free to serve other calls.
+            const id = wvDefer(h) + 0;
+            if (id < 0) {
+              wvReply(h, encode("cannot defer command: " + cmd));
+              return 1;
+            }
+            const settle = (status: number): ((value: unknown) => void) => {
+              let done = false;
+              return (value: unknown) => {
+                if (done) return; // a promise settles once
+                done = true;
+                wvReply(h, encode(value));
+                wvResolve(h, id, status);
+              };
+            };
+            asyncHandlers[i](args, settle(0), settle(1));
+            return 0;
+          }
+        }
+        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;
     },
   };