janela 0.2.0 → 0.3.1

package/runtime/janela.ts

@@ -28,12 +28,34 @@ 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;
+declare function wvJobStatus(h: number, id: number): number;
+declare function wvJobSize(h: number, id: number): number;
+declare function wvJobTakeAt(
+  h: number,
+  id: number,
+  offset: number,
+  maxBytes: 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;
 
-const FS_PENDING = 0;
-const FS_OK = 1;
+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 =
@@ -81,6 +103,32 @@ export type AsyncCommandHandler = (
  */
 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;
@@ -113,6 +161,30 @@ export interface JanelaApp {
     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. */
@@ -145,23 +217,115 @@ export function createApp(cfg: WindowConfig): JanelaApp {
   let taskFns: (() => void)[] = [];
   let timerFns: (() => void)[] = [];
   let timerDue: number[] = [];
-  let fsIds: number[] = [];
-  let fsCbs: FsCallback[] = [];
+  let jobIds: number[] = [];
+  let jobCbs: FsCallback[] = [];
   let ticking = false;
 
+  // ---- the drain -----------------------------------------------------------
+  // A finished job's bytes still have to be decoded into a TypeScript string,
+  // and that cost is proportional to the payload: taking a 100 MB file in one
+  // call froze the window for ~240 ms. So a finished job moves here and is
+  // decoded a slice at a time, giving the run loop the thread back between
+  // slices — total work is unchanged, but no single turn carries much of it.
+  //
+  // The budget is wall-clock rather than a byte count on purpose: a fixed
+  // chunk size fixes the WORST turn but also caps throughput (128 KB per 8 ms
+  // tick would cap reads at ~16 MB/s), whereas a time budget spends whatever
+  // the machine can do in the time available.
+  const DRAIN_BUDGET_MS = 4; // ≈ a quarter of a 60fps frame
+  const DRAIN_SLICE = 131072; // 128 KB — granularity within the budget
+  let drainIds: number[] = [];
+  let drainCbs: FsCallback[] = [];
+  let drainOk: boolean[] = [];
+  let drainParts: string[][] = [];
+  let drainOff: number[] = [];
+  let drainSize: number[] = [];
+
+  // Tick interval: 8 ms is plenty for timers and task chains, but while a
+  // payload is draining the loop is doing real work every turn, and waiting
+  // 8 ms between 4 ms slices would halve throughput for no benefit. So the
+  // ticker runs tighter for as long as there is a payload in flight.
+  const TICK_IDLE_MS = 8;
+  const TICK_DRAIN_MS = 4;
+  let tickMs = TICK_IDLE_MS;
+
+  const retick = (): void => {
+    const want = drainIds.length > 0 ? TICK_DRAIN_MS : TICK_IDLE_MS;
+    if (!ticking || want === tickMs) return;
+    tickMs = want;
+    wvTickStart(h, want);
+  };
+
   const wake = (): void => {
     if (ticking) return;
     ticking = true;
-    wvTickStart(h, 8);
+    tickMs = drainIds.length > 0 ? TICK_DRAIN_MS : TICK_IDLE_MS;
+    wvTickStart(h, tickMs);
   };
 
   const idle = (): void => {
     if (!ticking) return;
-    if (taskFns.length > 0 || timerFns.length > 0 || fsIds.length > 0) return;
+    if (
+      taskFns.length > 0 ||
+      timerFns.length > 0 ||
+      jobIds.length > 0 ||
+      drainIds.length > 0
+    ) {
+      return;
+    }
     ticking = false;
     wvTickStop(h);
   };
 
+  // Decode as much of the pending payloads as the budget allows, then yield.
+  // Slices are taken from one job at a time so a big read finishes promptly
+  // rather than every concurrent read finishing slowly.
+  const drainSome = (): void => {
+    if (drainIds.length === 0) return;
+    const started = Date.now() + 0;
+
+    while (drainIds.length > 0) {
+      let chunk = "";
+      const taken =
+        wvJobTakeAt(h, drainIds[0], drainOff[0], DRAIN_SLICE, (text) => {
+          chunk = text;
+        }) + 0;
+
+      // A negative count means the job vanished; treat the payload as final
+      // rather than spinning on it forever.
+      if (taken > 0) {
+        drainParts[0].push(chunk);
+        drainOff[0] = drainOff[0] + taken;
+      }
+
+      if (taken <= 0 || drainOff[0] >= drainSize[0]) {
+        // Joining is one unavoidable O(n) copy: the callback is handed a
+        // single string, so the whole payload must be materialised once.
+        const payload = drainParts[0].join("");
+        const cb = drainCbs[0];
+        const ok = drainOk[0];
+        wvJobFree(h, drainIds[0]);
+
+        drainIds = drainIds.slice(1);
+        drainCbs = drainCbs.slice(1);
+        drainOk = drainOk.slice(1);
+        drainParts = drainParts.slice(1);
+        drainOff = drainOff.slice(1);
+        drainSize = drainSize.slice(1);
+
+        if (ok) {
+          cb(null, payload);
+        } else {
+          cb(payload, "");
+        }
+        // User code just ran and may have taken a while; re-check the budget
+        // before starting another payload.
+      }
+
+      if (Date.now() - started >= DRAIN_BUDGET_MS) return;
+    }
+  };
+
   // 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.
@@ -190,44 +354,92 @@ export function createApp(cfg: WindowConfig): JanelaApp {
 
     // 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) {
+    if (jobIds.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]);
+      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(fsIds[i]);
-          doneCbs.push(fsCbs[i]);
-          doneOk.push(st === FS_OK);
+          doneIds.push(jobIds[i]);
+          doneCbs.push(jobCbs[i]);
+          doneOk.push(st === JOB_OK);
         }
       }
-      fsIds = keptIds;
-      fsCbs = keptCbs;
+      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 = "";
-        wvFsTake(h, doneIds[i], (text) => {
-          payload = text;
-        });
-        wvFsFree(h, doneIds[i]);
-        if (doneOk[i]) {
-          doneCbs[i](null, payload);
-        } else {
-          doneCbs[i](payload, "");
-        }
+        // On failure the payload IS the error message, so one path serves both
+        // outcomes. Nothing is decoded here: the job joins the drain queue and
+        // its bytes are taken a slice at a time, under a time budget.
+        drainIds.push(doneIds[i]);
+        drainCbs.push(doneCbs[i]);
+        drainOk.push(doneOk[i]);
+        drainParts.push([]);
+        drainOff.push(0);
+        drainSize.push(wvJobSize(h, doneIds[i]) + 0);
       }
     }
+
+    drainSome();
+    retick();
     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: [],
@@ -260,8 +472,8 @@ export function createApp(cfg: WindowConfig): JanelaApp {
         app.defer(() => cb("EAGAIN: could not start a read of '" + path + "'", ""));
         return;
       }
-      fsIds.push(id);
-      fsCbs.push(cb);
+      jobIds.push(id);
+      jobCbs.push(cb);
       wake();
     },
 
@@ -271,13 +483,44 @@ export function createApp(cfg: WindowConfig): JanelaApp {
         app.defer(() => cb("EAGAIN: could not start a write of '" + path + "'"));
         return;
       }
-      fsIds.push(id);
+      jobIds.push(id);
       // The write payload is empty on success; the shared callback shape just
       // ignores the text argument.
-      fsCbs.push((err, _text) => cb(err));
+      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,