janela 0.1.2 → 0.3.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,19 +17,38 @@ 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 wvJobStatus(h: number, id: number): number;
+declare function wvJobTake(h: number, id: number, sink: (text: string) => void): number;
+declare function wvJobFree(h: number, id: number): number;
+declare function wvDialog(
+  h: number,
+  kind: number,
+  flags: number,
+  title: string,
+  defaultPath: string,
+  defaultName: string,
+  filters: string,
+): number;
+declare function wvSetFullscreen(h: number, on: number): number;
 
-// Bind index the shim uses for a timer tick rather than a page invoke.
-const TICK_BIND = 4294967295;
+const JOB_PENDING = 0;
+const JOB_OK = 1;
+
+const DLG_OPEN = 0;
+const DLG_SAVE = 1;
+const DLG_MULTIPLE = 1;
+const DLG_DIRECTORY = 2;
 
 // Injected into every page before it loads (webview_init).
 const BOOTSTRAP =
@@ -47,23 +67,61 @@ 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;
+
+/** A named group of extensions offered in a dialog's file-type popup. */
+export interface DialogFilter {
+  name: string;
+  /** Bare extensions, no dot and no glob: ["png", "jpg"]. */
+  extensions: string[];
+}
+
+export interface OpenDialogOptions {
+  title?: string;
+  /** Directory the dialog opens in. */
+  defaultPath?: string;
+  /** Allow picking more than one entry. */
+  multiple?: boolean;
+  /** Pick directories instead of files. Not supported on Windows. */
+  directory?: boolean;
+  filters?: DialogFilter[];
+}
+
+export interface SaveDialogOptions {
+  title?: string;
+  defaultPath?: string;
+  /** Filename pre-filled in the name field. */
+  defaultName?: string;
+  filters?: DialogFilter[];
+}
+
 export interface WindowConfig {
   title: string;
   width: number;
@@ -83,85 +141,56 @@ 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;
+  /**
+   * Show the native "open" dialog. `cb` gets the chosen paths, or null if the
+   * user cancelled. The modal runs on a later turn of the UI thread, so
+   * calling this from inside a command does not block that command's reply —
+   * pair it with commandAsync when the page is waiting for the result.
+   */
+  openFileDialog: (
+    options: OpenDialogOptions,
+    cb: (paths: string[] | null, err?: string) => void,
+  ) => void;
+  /** Show the native "save" dialog; cb gets the path, or null on cancel. */
+  saveFileDialog: (
+    options: SaveDialogOptions,
+    cb: (path: string | null, err?: string) => void,
+  ) => void;
+  /** Change the window title at any time, not just at startup. */
+  setTitle: (title: string) => void;
+  /**
+   * Resize the window. `hint` is webview's sizing hint: 0 none, 1 minimum,
+   * 2 maximum, 3 fixed.
+   */
+  setSize: (width: number, height: number, hint?: number) => void;
+  /** Enter or leave fullscreen. */
+  setFullscreen: (on: boolean) => 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 +202,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 jobIds: number[] = [];
+  let jobCbs: FsCallback[] = [];
   let ticking = false;
 
   const wake = (): void => {
@@ -191,7 +222,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 || jobIds.length > 0) return;
     ticking = false;
     wvTickStop(h);
   };
@@ -221,9 +252,96 @@ 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 (jobIds.length > 0) {
+      const keptIds: number[] = [];
+      const keptCbs: FsCallback[] = [];
+      const doneIds: number[] = [];
+      const doneCbs: FsCallback[] = [];
+      const doneOk: boolean[] = [];
+      for (let i = 0; i < jobIds.length; i++) {
+        const st = wvJobStatus(h, jobIds[i]) + 0;
+        if (st === JOB_PENDING) {
+          keptIds.push(jobIds[i]);
+          keptCbs.push(jobCbs[i]);
+        } else {
+          doneIds.push(jobIds[i]);
+          doneCbs.push(jobCbs[i]);
+          doneOk.push(st === JOB_OK);
+        }
+      }
+      jobIds = keptIds;
+      jobCbs = 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 = "";
+        wvJobTake(h, doneIds[i], (text) => {
+          payload = text;
+        });
+        wvJobFree(h, doneIds[i]);
+        if (doneOk[i]) {
+          doneCbs[i](null, payload);
+        } else {
+          doneCbs[i](payload, "");
+        }
+      }
+    }
     idle();
   };
 
+  // Filters cross as "Name|ext,ext|Name|ext" — the shim needs no JSON parser
+  // for what is always a short, flat list.
+  const encodeFilters = (filters: DialogFilter[] | undefined): string => {
+    if (filters === undefined || filters.length === 0) return "";
+    const parts: string[] = [];
+    for (let i = 0; i < filters.length; i++) {
+      parts.push(filters[i].name);
+      parts.push(filters[i].extensions.join(","));
+    }
+    return parts.join("|");
+  };
+
+  // Both dialog kinds share one path: start the job, then let the same drain
+  // that serves file I/O deliver the answer on a later turn.
+  const startDialog = (
+    kind: number,
+    flags: number,
+    title: string | undefined,
+    defaultPath: string | undefined,
+    defaultName: string | undefined,
+    filters: DialogFilter[] | undefined,
+    cb: (paths: string[] | null, err?: string) => void,
+  ): void => {
+    const id = wvDialog(
+      h,
+      kind,
+      flags,
+      title === undefined ? "" : title,
+      defaultPath === undefined ? "" : defaultPath,
+      defaultName === undefined ? "" : defaultName,
+      encodeFilters(filters),
+    ) + 0;
+    if (id < 0) {
+      taskFns.push(() => cb(null, "EAGAIN: could not open a dialog"));
+      wake();
+      return;
+    }
+    jobIds.push(id);
+    jobCbs.push((err, text) => {
+      if (err !== null) {
+        cb(null, err);
+        return;
+      }
+      // "null" is a cancel; anything else is a JSON array of paths.
+      cb(JSON.parse(text) as string[] | null);
+    });
+    wake();
+  };
+
   const app: JanelaApp = {
     handle: h,
     names: [],
@@ -250,10 +368,65 @@ 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;
+      }
+      jobIds.push(id);
+      jobCbs.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;
+      }
+      jobIds.push(id);
+      // The write payload is empty on success; the shared callback shape just
+      // ignores the text argument.
+      jobCbs.push((err, _text) => cb(err));
+      wake();
+    },
+
+    openFileDialog: (options, cb) => {
+      let flags = 0;
+      if (options.multiple === true) flags = flags + DLG_MULTIPLE;
+      if (options.directory === true) flags = flags + DLG_DIRECTORY;
+      startDialog(DLG_OPEN, flags, options.title, options.defaultPath, "",
+        options.filters, (paths, err) => cb(paths, err));
+    },
+
+    saveFileDialog: (options, cb) => {
+      startDialog(DLG_SAVE, 0, options.title, options.defaultPath,
+        options.defaultName, options.filters, (paths, err) => {
+          if (paths === null) {
+            cb(null, err);
+            return;
+          }
+          cb(paths.length > 0 ? paths[0] : null, err);
+        });
+    },
+
+    setTitle: (title) => {
+      wvSetTitle(h, title);
+    },
+
+    setSize: (width, height, hint) => {
+      wvSetSize(h, width, height, hint === undefined ? 0 : hint);
+    },
+
+    setFullscreen: (on) => {
+      wvSetFullscreen(h, on ? 1 : 0);
+    },
+
+    emit: (event, payload) => {
       wvEval(
         h,
-        "window.__wvEmit(" + JSON.stringify(event) + "," + payloadJson + ");",
+        "window.__wvEmit(" + JSON.stringify(event) + "," + encode(payload) + ");",
       );
     },
 
@@ -262,26 +435,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 +455,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;
     },
   };