janela 0.3.0 → 0.3.1

package/README.md

@@ -154,10 +154,14 @@ 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 crosses in a single call (format 3), and the drain that follows it
-costs about **10 ms per MB on the UI thread** — fine for config files and
-documents, still worth chunking for very large media. See
-[docs/async.md](../../docs/async.md) for the measurements.
+The payload crosses in a single call (format 3), and the decode that follows is
+spread across turns under a 4 ms budget, so a large read no longer stalls the
+window: a 100 MB file's worst UI pause is ~25 ms (p99 4 ms) rather than ~176 ms,
+at the same throughput. The remaining pause is the one unavoidable copy that
+materialises the string for your callback. See
+[docs/async.md](../../docs/async.md) for the measurements — and note that
+indexing a large string in your own callback (`text.length`, `slice`) is O(n)
+in scriptc and can cost far more than the read did.
 
 **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`,

package/bin/janela.mjs

@@ -345,14 +345,17 @@ function ffiManifest(shimLib) {
     // Job accessors, shared by file I/O and dialogs: both are work whose
     // answer cannot be produced during the FFI call that starts it.
     { name: "wvJobStatus", symbol: "wv_job_status", params: ["i32", "i32"], returns: "i32" },
+    { name: "wvJobSize", symbol: "wv_job_size", params: ["i32", "i32"], returns: "f64" },
     {
-      name: "wvJobTake", symbol: "wv_job_take",
+      // One slice per call, so a large payload decodes across several UI turns
+      // instead of stalling on all of it at once. Returns the bytes covered.
+      name: "wvJobTakeAt", symbol: "wv_job_take_at",
       params: [
-        "i32", "i32",
+        "i32", "i32", "f64", "f64",
         { callback: { id: "sink", params: ["string", { context: "sink" }], returns: "void", lifetime: "call" } },
         { context: "sink" },
       ],
-      returns: "i32",
+      returns: "f64",
     },
     { name: "wvJobFree", symbol: "wv_job_free", params: ["i32", "i32"], returns: "i32" },
     // Native dialogs: the modal runs on a later UI-thread turn, so asking for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

package/runtime/janela.ts

@@ -29,7 +29,14 @@ 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 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,
@@ -214,19 +221,111 @@ export function createApp(cfg: WindowConfig): JanelaApp {
   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 || jobIds.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.
@@ -275,21 +374,20 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       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, "");
-        }
+        // 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();
   };
 

package/shim/wvshim.cc

@@ -820,18 +820,65 @@ int32_t wv_job_status(int32_t h, int32_t id) {
   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_job_take(int32_t h, int32_t id,
-                   void (*sink)(const uint8_t *, size_t, void *), void *ctx) {
+// Payload size in bytes, so TS knows when it has drained the whole thing.
+// f64 rather than i32: a payload may exceed 2 GB, and every scriptc number is
+// a double anyway (exact for byte counts far beyond any plausible file).
+double wv_job_size(int32_t h, int32_t id) {
+  if (!app_at(h)) return -1;
+  Job *j = job_at(id);
+  if (!j) return -1;
+  if (j->status.load(std::memory_order_acquire) == JOB_PENDING) return -1;
+  return static_cast<double>(j->data.size());
+}
+
+// Hand ONE SLICE of a finished job's payload to TS, and answer how many bytes
+// it covered. 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 for the whole drain.
+//
+// Slicing exists so the UI thread can decode a large payload across several
+// turns instead of stalling on all of it at once; the caller advances `offset`
+// by the returned count until it reaches wv_job_size().
+//
+// The slice end is pulled back to a UTF-8 sequence boundary, because scriptc
+// decodes a `string` param as UTF-8: cutting mid-sequence would turn one
+// character into replacement characters on both sides of the seam. Bytes that
+// are not valid UTF-8 have no boundary to find, so after four steps the cut
+// stands as asked and the payload is passed through unchanged.
+double wv_job_take_at(int32_t h, int32_t id, double offset, double max_bytes,
+                      void (*sink)(const uint8_t *, size_t, void *),
+                      void *ctx) {
   if (!app_at(h)) return -1;
   Job *j = job_at(id);
   if (!j || !sink) return -1;
   if (j->status.load(std::memory_order_acquire) == JOB_PENDING) return -1;
-  sink(reinterpret_cast<const uint8_t *>(j->data.data()), j->data.size(), ctx);
-  return 0;
+  if (offset < 0 || max_bytes < 0) return -1;
+
+  const size_t size = j->data.size();
+  const size_t off = static_cast<size_t>(offset);
+  if (off > size) return -1;
+  if (off == size) return 0;
+
+  size_t want = static_cast<size_t>(max_bytes);
+  if (want == 0) return 0;
+  size_t end = off + want;
+  if (end >= size) {
+    end = size;
+  } else {
+    const unsigned char *d =
+        reinterpret_cast<const unsigned char *>(j->data.data());
+    // d[end] is the first byte of the NEXT slice; while it is a continuation
+    // byte (10xxxxxx) the cut sits inside a character, so step back.
+    size_t e = end;
+    for (int guard = 0; guard < 4 && e > off && (d[e] & 0xc0) == 0x80; guard++) {
+      e--;
+    }
+    if (e > off) end = e;
+  }
+
+  sink(reinterpret_cast<const uint8_t *>(j->data.data()) + off, end - off, ctx);
+  return static_cast<double>(end - off);
 }
 
 // Release the slot for reuse. Refuses while the worker is still running, so a