janela 0.3.0 → 0.4.0

package/README.md

@@ -70,7 +70,7 @@ MSI.
 
 ```
 my-app/
-├── index.html          frontend — any HTML/JS; calls janela.invoke() / janela.listen()
+├── index.html          frontend — any HTML/JS/TS; calls invoke() / listen()
 ├── src-host/main.ts    backend — exports setup(app), registers commands
 └── janela.conf.json    name, bundle identifier, version, window
 ```
@@ -79,17 +79,42 @@ A Vite project adds a `vite.config.js` and a `src/` tree — that config is what
 makes janela build the frontend with Vite instead of inlining `index.html`
 directly.
 
-Frontend API (injected before page load):
+Frontend API — import it, and your editor and `tsc` know the shapes:
+
+```ts
+import { invoke, listen } from "janela/api";
+
+const sum = await invoke<number>("add", { a: 2, b: 40 }); // call a backend command
+listen<number>("added", (payload) => { ... });            // backend-fired events
+```
+
+`janela` is already a devDependency of a scaffolded project, so there is
+nothing extra to install. The generic is what the host command returns —
+values cross the boundary as values, so there is no JSON to parse.
+
+<details>
+<summary>No bundler? Use the injected global instead</summary>
+
+janela injects the same two functions as `window.janela` before every document
+loads, which is what the `vanilla` template uses — it needs no `npm install` at
+all:
 
 ```js
-const sum = await janela.invoke("add", { a: 2, b: 40 }); // call a backend command
-janela.listen("added", (payload) => { ... });            // backend-fired events
+const sum = await janela.invoke("add", { a: 2, b: 40 });
+janela.listen("added", (payload) => { ... });
 ```
 
-Backend API (`src-host/main.ts`):
+TypeScript users on this path can pull in the ambient types with
+`/// <reference types="janela/global" />`, or by adding `"janela/global"` to
+`compilerOptions.types`. With a bundler, prefer the import — it needs no
+ambient declaration.
+
+</details>
+
+Backend API (`src-host/main.ts`) — also typed, from the same package:
 
 ```ts
-import type { JanelaApp } from "./janela";
+import type { JanelaApp } from "janela/host";
 
 export function setup(app: JanelaApp): void {
   app.command("add", (args) => {              // values in, values out
@@ -154,10 +179,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`,
@@ -206,11 +235,48 @@ nested modal loop would otherwise re-enter the host loop underneath a live TS
 frame; [docs/native-shell.md](../../docs/native-shell.md) has the details, the
 per-platform table, and the Windows GUI-subsystem note.
 
+## Migrating from 0.3.x
+
+Nothing breaks: the injected `janela` global still works exactly as before.
+What changed is the recommendation — the frontend now has a real module, so
+editors and `tsc` can see it:
+
+```ts
+// 0.3.x — an untyped global, invisible to tsc and ESLint
+const sum = await janela.invoke("add", { a: 2, b: 40 });
+
+// 0.4.x — typed, resolvable, and generic over what the command returns
+import { invoke } from "janela/api";
+const sum = await invoke<number>("add", { a: 2, b: 40 });
+```
+
+The host side had the same problem and gets the same fix. `src-host/main.ts`
+used to import `JanelaApp` from `"./janela"` — a path that only exists inside
+`.janela/build/`, so an editor could never resolve it and the whole `app.*`
+API was untyped:
+
+```ts
+// 0.3.x — unresolved in the editor; JanelaApp was effectively `any`
+import type { JanelaApp } from "./janela";
+
+// 0.4.x — resolves against the installed package
+import type { JanelaApp } from "janela/host";
+```
+
+`janela build` rewrites that specifier to the local runtime copy while
+assembling the compile unit, so the build stays fully static and a project
+with no `node_modules` at all still compiles.
+
+The framework templates (`vue`, `react`, `svelte`, `solid`) are TypeScript now
+and scaffold with a `typecheck` script that covers `src/` and `src-host/`
+alike. `vanilla` stays plain JavaScript on the global, so it still needs no
+`npm install` before the first build.
+
 ## 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.
+(`invoke` / `listen`) is unchanged.
 
 ```ts
 // 0.1.x

package/api/global.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Types for the injected `janela` global, for pages that use it directly
+ * rather than importing `janela/api` — a plain `<script>` with no bundler,
+ * typically. Pull them in from a TypeScript project with:
+ *
+ * ```ts
+ * /// <reference types="janela/global" />
+ * ```
+ *
+ * or by adding `"janela/global"` to `compilerOptions.types` in tsconfig.json.
+ *
+ * If you have a bundler, prefer `import { invoke, listen } from "janela/api"` —
+ * it needs no ambient declaration and is what the templates use.
+ */
+
+import type { JanelaBridge } from "./index.js";
+
+declare global {
+  /** The host bridge janela injects before the document loads. */
+  const janela: JanelaBridge;
+
+  interface Window {
+    janela: JanelaBridge;
+  }
+}
+
+export {};

package/api/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The janela frontend API.
+ *
+ * Values cross the boundary as values — janela owns the JSON at the edge — so
+ * the generic parameter is what the host command returns, not a string to
+ * parse.
+ */
+
+/** The bridge janela injects as `window.janela` before each document loads. */
+export interface JanelaBridge {
+  invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
+  listen<T = unknown>(event: string, cb: (payload: T) => void): void;
+}
+
+/**
+ * Call a command the host registered with `app.command` / `app.commandAsync`.
+ *
+ * ```ts
+ * const sum = await invoke<number>("add", { a: 2, b: 40 });
+ * ```
+ *
+ * Rejects if the command is unknown, if the handler rejected, or if the page
+ * is not running inside a janela window.
+ */
+export declare function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
+
+/**
+ * Subscribe to an event the host sends with `app.emit`.
+ *
+ * ```ts
+ * listen<number>("added", (sum) => console.log(sum));
+ * ```
+ */
+export declare function listen<T = unknown>(
+  event: string,
+  cb: (payload: T) => void,
+): void;

package/api/index.js

@@ -0,0 +1,35 @@
+// The janela frontend API — `import { invoke, listen } from "janela/api"`.
+//
+// janela injects a bridge as `window.janela` into every document before it
+// loads, so this module is a thin wrapper over that global rather than a
+// transport of its own. Importing it is the recommended style: bundlers
+// resolve it, editors complete it, and `tsc` checks it. The global stays
+// available unchanged for pages with no build step.
+
+function bridge() {
+  const found = typeof globalThis === "undefined" ? undefined : globalThis.janela;
+  if (!found || typeof found.invoke !== "function") {
+    throw new Error(
+      "janela: no host bridge on this page (window.janela is undefined). " +
+        "The page is not running inside a janela window — run the app with " +
+        "`janela dev`, or `janela build` and launch the binary. Opening the " +
+        "page in a browser, or serving it with plain `vite`, leaves no host " +
+        "to talk to.",
+    );
+  }
+  return found;
+}
+
+/**
+ * Call a command the host registered with `app.command` / `app.commandAsync`.
+ * Arguments and the resolved value are ordinary values; janela owns the
+ * serialisation at the boundary.
+ */
+export async function invoke(cmd, args) {
+  return bridge().invoke(cmd, args);
+}
+
+/** Subscribe to an event the host sends with `app.emit`. */
+export function listen(event, cb) {
+  bridge().listen(event, cb);
+}

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
@@ -478,9 +481,22 @@ function build(root, { devUrl = null, gui = true } = {}) {
 
   // Assemble the compile unit: runtime + user's commands + generated modules.
   cpSync(join(KIT, "runtime", "janela.ts"), join(buildDir, "janela.ts"));
+  cpSync(join(KIT, "runtime", "types.ts"), join(buildDir, "types.ts"));
   const mainSrc = join(root, "src-host", "main.ts");
   if (!existsSync(mainSrc)) fail("missing src-host/main.ts");
-  cpSync(mainSrc, join(buildDir, "main.ts"));
+  // A project's main.ts imports from "janela/host" so that it resolves in the
+  // editor against the installed package. Here it is compiled next to the
+  // runtime instead, so the specifier is rewritten to that local copy: the
+  // build never resolves through node_modules, which keeps it static and will
+  // keep working when "janela/host" starts exporting values (not just types)
+  // as well.
+  writeFileSync(
+    join(buildDir, "main.ts"),
+    readFileSync(mainSrc, "utf8").replace(
+      /(\bfrom\s*)(['"])janela\/host\2/g,
+      "$1$2./janela$2",
+    ),
+  );
 
   const html = frontendHtml(root, conf, devUrl);
   writeFileSync(
@@ -613,6 +629,7 @@ function init(name, template) {
     const extra = JSON.parse(readFileSync(join(tdir, "deps.json"), "utf8"));
     pkg.type = "module";
     Object.assign(pkg.devDependencies, extra.devDependencies ?? {});
+    Object.assign(pkg.scripts, extra.scripts ?? {});
     if (extra.dependencies) pkg.dependencies = extra.dependencies;
   }
 

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "janela",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
     "janela": "bin/janela.mjs",
     "jn": "bin/janela.mjs"
   },
+  "exports": {
+    "./api": {
+      "types": "./api/index.d.ts",
+      "default": "./api/index.js"
+    },
+    "./host": {
+      "types": "./runtime/types.ts"
+    },
+    "./global": {
+      "types": "./api/global.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
     "scriptc": "0.0.35"
   },
@@ -33,6 +46,7 @@
     "node": ">=24"
   },
   "files": [
+    "api/",
     "bin/",
     "runtime/",
     "shim/",

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,
@@ -67,124 +74,30 @@ const BOOTSTRAP =
   "  for (var i = 0; i < cbs.length; i++) cbs[i](payload);" +
   "};";
 
-// 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;
-
-/** 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;
-  height: number;
-}
-
-export interface JanelaApp {
-  handle: number;
-  names: string[];
-  handlers: CommandHandler[];
-  /** Register a named command, callable from the page as janela.invoke(name, args). */
-  command: (name: string, h: CommandHandler) => 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;
-  /**
-   * 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;
-}
+// The public host types live in ./types (shipped as `janela/host` too, so a
+// user's editor can see them). Re-exported here because the compiled build
+// resolves them through this module — see the specifier rewrite in the CLI.
+export type {
+  AsyncCommandHandler,
+  CommandHandler,
+  DialogFilter,
+  FsCallback,
+  JanelaApp,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
+
+import type {
+  AsyncCommandHandler,
+  CommandHandler,
+  DialogFilter,
+  FsCallback,
+  JanelaApp,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
 
 // 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.
@@ -214,19 +127,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 +280,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();
   };