janela 0.1.1 → 0.2.0

package/README.md

@@ -19,8 +19,33 @@ janela build              # .janela/out/my-app  (+ my-app.app on macOS)
 ```
 
 Requirements: Node 18+, a C++ compiler (Xcode CLT on macOS; g++ +
-`libwebkit2gtk-4.1-dev` on Linux). A worked example lives in
-[`examples/demo`](examples/demo) — commands, events, and a file reader.
+`libwebkit2gtk-4.1-dev` on Linux; see [Windows](#windows) below). A worked
+example lives in [`examples/demo`](examples/demo) — commands, events, and a
+file reader.
+
+## Windows
+
+`janela build` produces `.janela/out/<name>.exe` using the WebView2 backend.
+
+**You need a MinGW-targeting clang on `PATH`** — [llvm-mingw][llvm-mingw],
+MSYS2's `clang64` toolchain, or WinLibs. MSVC does **not** work: scriptc's
+runtime uses POSIX types and calls (`ssize_t`, `nanosleep`, `clock_gettime`)
+that the MSVC CRT does not provide. janela checks `clang -dumpmachine` and
+tells you if the wrong one is first on `PATH`.
+
+webview.h's Win32 backend includes `WebView2.h`, which Microsoft ships in a
+nuget package rather than in the Windows SDK, so the first build downloads
+`Microsoft.Web.WebView2` into `.janela/cache/` automatically. To build offline
+or pin your own copy, point `JANELA_WEBVIEW2_INCLUDE` at a directory
+containing `WebView2.h`. No `WebView2Loader.dll` is needed — webview.h has its
+own loader — and end users need only the **WebView2 runtime**, which is
+preinstalled on current Windows 10/11 (it ships with Edge).
+
+Two caveats today: the binary is a console-subsystem app, so a console window
+appears behind the UI (handy for `janela dev`, wrong for shipping), and there
+is no installer step — you get a bare `.exe`, not an MSI.
+
+[llvm-mingw]: https://github.com/mstorsjo/llvm-mingw/releases
 
 ## A project
 
@@ -44,19 +69,116 @@ Backend API (`src-host/main.ts`):
 import type { JanelaApp } from "./janela";
 
 export function setup(app: JanelaApp): void {
-  app.command("add", (argsJson) => {          // args in / result out as JSON text
-    const a = JSON.parse(argsJson) as { a: number; b: number };
-    app.emit("added", JSON.stringify(a.a + a.b));  // push an event to the page
-    return JSON.stringify(a.a + a.b);
+  app.command("add", (args) => {              // values in, values out
+    const a = args as { a: number; b: number };
+    app.emit("added", a.a + a.b);             // push an event to the page
+    return a.a + a.b;
   });
   // app.quit() closes the window and returns from run()
 }
 ```
 
+## Async commands
+
+A command that has to wait — or to chew through real work — should not freeze
+the window. Register it with `commandAsync` and answer whenever you are ready;
+the page keeps using the same `await janela.invoke(...)`.
+
+```ts
+app.commandAsync("wait", (args, resolve, reject) => {
+  const a = args as { ms: number };
+  app.sleep(a.ms, () => resolve("done"));   // resolve later
+});
+
+// Work that cannot just wait: slice it, yielding to the UI between slices.
+app.commandAsync("countTo", (args, resolve) => {
+  const a = args as { n: number };
+  let i = 0;
+  const step = (): void => {
+    const end = Math.min(i + 2_000_000, a.n);
+    for (; i < end; i++) { /* ... */ }
+    if (i < a.n) app.defer(step); else resolve(i);
+  };
+  app.defer(step);
+});
+```
+
+- `app.defer(fn)` — run `fn` on the next turn of the host loop.
+- `app.sleep(ms, fn)` — run `fn` after at least `ms`.
+- `resolve(value)` / `reject(reason)` settle the page's promise; `reject`
+  makes `await janela.invoke(...)` throw. Settling twice is ignored.
+
+## File I/O
+
+`node:fs` works in a handler, but `readFileSync` **blocks the window** for as
+long as the syscall runs — parking a promise does not change that. Use the
+async pair instead: the syscall runs on a worker thread inside the shim, and
+only the result crosses back to your (single-threaded) TypeScript.
+
+```ts
+app.commandAsync("readFile", (args, resolve) => {
+  const a = args as { path: string };
+  app.readFileAsync(a.path, (err, text) => {
+    if (err !== null) { resolve({ ok: false, error: err }); return; }
+    resolve({ ok: true, text });
+  });
+});
+
+app.writeFileAsync("out.txt", "contents", (err) => { /* err is null on success */ });
+```
+
+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 still crosses the FFI boundary one byte per call (format 2), which
+costs about **115 ms per MB on the UI thread** — fine for config files and
+documents, wrong for streaming large media. See
+[docs/async.md](../../docs/async.md) for the measurements.
+
+**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`,
+`queueMicrotask` and `await` in host code never fire while the window is open
+(they all run after it closes). janela supplies its own loop instead: a native
+ticker posts work to the UI thread via `webview_dispatch`, and it only runs
+while something is queued, so an idle app costs nothing.
+
+**Still single-threaded.** scriptc's runtime is not thread-safe (concurrent
+calls from several threads abort the process), so host code always runs on the
+UI thread. Async here means *interleaved*, not parallel: a handler that blocks
+without yielding still freezes the window. Slice long work with `defer`.
+
 The backend is ordinary TypeScript with scriptc's stdlib — including a
 `node:fs` subset — so "read a file" or "call an API" is just code in a
 command handler, no plugin layer needed.
 
+## 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.
+
+```ts
+// 0.1.x
+app.command("add", (argsJson) => {
+  const a = JSON.parse(argsJson) as { a: number; b: number };
+  app.emit("added", JSON.stringify(a.a + a.b));
+  return JSON.stringify(a.a + a.b);
+});
+
+// 0.2.x
+app.command("add", (args) => {
+  const a = args as { a: number; b: number };
+  app.emit("added", a.a + a.b);
+  return a.a + a.b;
+});
+```
+
+Mechanically: drop the `JSON.parse(argsJson)` (cast `args` instead), drop
+every `JSON.stringify` around a result, `resolve`/`reject`/`emit` payload, and
+return nothing at all where you used to return `"null"`. Requires Node 24 to
+build (scriptc 0.0.35's floor).
+
 ## What the CLI hides
 
 `janela build` assembles `.janela/build/` (runtime + your `main.ts` +
@@ -66,18 +188,19 @@ scriptc. On macOS the frameworks are linked as SDK `.tbd` stubs (scriptc has
 no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 `.app` bundle.
 
-## Constraints inherited from scriptc 0.0.32
+## Constraints inherited from scriptc
 
-- Command args/results cross the boundary as **JSON text** — handlers
-  `JSON.parse` in and `JSON.stringify` out. The runtime keeps the byte channel
-  ASCII by `\uXXXX`-escaping non-ASCII (scriptc strings can't hold lone
-  surrogates, and `JSON.parse` is the reliable reassembly point).
+- Command args and results are ordinary values; the runtime serialises them at
+  the boundary, so anything that survives `JSON.stringify`/`JSON.parse` round
+  trips (including full Unicode). `args` is typed `unknown` — cast it to the
+  shape you expect.
 - Never use a bare FFI call as a complete variable initializer or assignment
   RHS — it is silently miscompiled. Wrap it in any expression (`+ 0`). Plain
   TypeScript is unaffected; only the runtime does FFI, so app code rarely
   meets this.
-- One window per app for now; the run loop is single-threaded, so a slow
-  command blocks the UI (same as a blocking Tauri command handler).
+- One window per app for now. Host code is single-threaded: a synchronous
+  command blocks the UI while it runs — use `commandAsync` + `defer`/`sleep`
+  (see "Async commands") for anything slow.
 - `console.log` from commands goes to stdout — visible under `janela dev`,
   not when launched from Finder.
 
@@ -86,9 +209,28 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 Early proof of concept, macOS (arm64) and Linux (WebKitGTK). The design
 notes and scriptc findings behind it are in
 [docs/findings.md](docs/findings.md). Not yet: Windows, async commands
-(the run loop is single-threaded), native dialogs/tray/menus, multi-window,
+that run in parallel (host code is single-threaded; `commandAsync` interleaves
+instead), native dialogs/tray/menus, multi-window,
 icons/installers/notarization.
 
+## Releasing
+
+Bump `version` in `package.json` and merge to `main`. The publish workflow
+then does the rest: it compares the version against the registry, and if it
+is new, scaffolds/builds/runs a smoke app on Linux, publishes to npm with
+trusted publishing (OIDC — no token secret), tags the published commit
+`v<version>`, and opens a GitHub release with generated notes.
+
+A merge that does not change the version is a clean no-op: nothing is
+published and no tag is created. If a publish ever succeeds but the tagging
+step does not, npm and git are briefly out of step — reconcile with:
+
+```bash
+git tag -a v<version> -m "janela <version>" <commit>
+git push origin v<version>
+gh release create v<version> --generate-notes --verify-tag
+```
+
 ## License
 
 MIT. Bundles [webview/webview](https://github.com/webview/webview) headers

package/bin/janela.mjs

@@ -54,16 +54,95 @@ function loadConf(root) {
   return c;
 }
 
+// ---- Windows toolchain ------------------------------------------------------
+
+// scriptc's win32 lane is MinGW-shaped twice over: its runtime uses POSIX
+// types the MSVC CRT lacks (ssize_t), and its event loop calls POSIX time
+// APIs that only a full mingw-w64 provides ("the idle sleep is nanosleep
+// (mingw-w64 ships it, over Sleep)" — scr_async.c). So Windows builds need a
+// clang whose DEFAULT target is mingw: llvm-mingw, MSYS2's clang64, or
+// WinLibs. A stock MSVC-targeting clang cannot compile scriptc's runtime, and
+// zig's bundled mingw omits winpthreads, so it cannot either.
+function winCcOrFail() {
+  const probe = spawnSync("clang", ["-dumpmachine"], { encoding: "utf8" });
+  if (probe.status !== 0) {
+    fail(
+      "Windows builds need a MinGW-targeting clang on PATH. Install llvm-mingw " +
+        "(https://github.com/mstorsjo/llvm-mingw/releases) or MSYS2's clang64 toolchain.",
+    );
+  }
+  const triple = probe.stdout.trim();
+  if (!/mingw|windows-gnu/i.test(triple)) {
+    fail(
+      `clang on PATH targets '${triple}', but scriptc's Windows runtime only builds with ` +
+        "MinGW (it uses ssize_t/nanosleep/clock_gettime, which the MSVC CRT lacks). " +
+        "Put a MinGW-targeting clang first on PATH — llvm-mingw " +
+        "(https://github.com/mstorsjo/llvm-mingw/releases) or MSYS2's clang64.",
+    );
+  }
+  return triple;
+}
+
+// ---- WebView2 SDK (Windows only) -------------------------------------------
+
+// webview.h's Win32 backend includes <WebView2.h>, which ships in Microsoft's
+// nuget package rather than the Windows SDK. Fetch it once into the build
+// cache (a .nupkg is a zip) unless the caller points at their own copy.
+const WEBVIEW2_VERSION = "1.0.2903.40";
+
+function webview2Include(cacheDir) {
+  const override = process.env.JANELA_WEBVIEW2_INCLUDE;
+  if (override) {
+    if (!existsSync(join(override, "WebView2.h"))) {
+      fail(`JANELA_WEBVIEW2_INCLUDE=${override} does not contain WebView2.h`);
+    }
+    return override;
+  }
+
+  const sdkDir = join(cacheDir, `webview2-${WEBVIEW2_VERSION}`);
+  const incDir = join(sdkDir, "build", "native", "include");
+  if (existsSync(join(incDir, "WebView2.h"))) return incDir;
+
+  console.log(`janela: fetching WebView2 SDK ${WEBVIEW2_VERSION}`);
+  const zip = join(cacheDir, `webview2-${WEBVIEW2_VERSION}.zip`);
+  const url = `https://www.nuget.org/api/v2/package/Microsoft.Web.WebView2/${WEBVIEW2_VERSION}`;
+  run([
+    "powershell", "-NoProfile", "-NonInteractive", "-Command",
+    `$ErrorActionPreference='Stop';` +
+      `[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12;` +
+      `Invoke-WebRequest -Uri '${url}' -OutFile '${zip}';` +
+      `Expand-Archive -Path '${zip}' -DestinationPath '${sdkDir}' -Force`,
+  ]);
+  if (!existsSync(join(incDir, "WebView2.h"))) {
+    fail(`WebView2 SDK unpacked to ${sdkDir} but no build/native/include/WebView2.h`);
+  }
+  return incDir;
+}
+
 // ---- shim ----------------------------------------------------------------
 
 function buildShim(cacheDir) {
   const src = join(KIT, "shim", "wvshim.cc");
-  const obj = join(cacheDir, "wvshim.o");
-  const lib = join(cacheDir, "libwvshim.a");
+  const win = process.platform === "win32";
+  // On Windows the object file is handed to the link directly: `ar` is not
+  // part of an MSVC toolchain, and a lone object needs no archive index.
+  const obj = join(cacheDir, win ? "wvshim.obj" : "wvshim.o");
+  const lib = win ? obj : join(cacheDir, "libwvshim.a");
   if (existsSync(lib) && statSync(lib).mtimeMs > statSync(src).mtimeMs) return lib;
 
   console.log("janela: compiling webview shim");
   const inc = `-I${join(KIT, "vendor-webview", "core", "include")}`;
+  if (win) {
+    console.log(`janela: building for ${winCcOrFail()}`);
+    run([
+      "clang++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc,
+      // WebView2.h from the nuget SDK, plus mingw's missing EventToken.h.
+      `-I${webview2Include(cacheDir)}`,
+      `-I${join(KIT, "vendor-webview", "compatibility", "mingw", "include")}`,
+      "-DWIN32_LEAN_AND_MEAN", "-D_WIN32_WINNT=0x0601",
+    ]);
+    return lib;
+  }
   if (process.platform === "darwin") {
     run(["clang++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc]);
   } else {
@@ -87,28 +166,80 @@ function ffiManifest(shimLib) {
     STR("wvInit", "wv_init"),
     STR("wvEval", "wv_eval"),
     STR("wvBind", "wv_bind"),
-    { name: "wvReqLen", symbol: "wv_req_len", params: ["i32"], returns: "i32" },
-    { name: "wvReqByte", symbol: "wv_req_byte", params: ["i32", "i32"], returns: "i32" },
-    { name: "wvReplyReset", symbol: "wv_reply_reset", params: ["i32"], returns: "i32" },
-    { name: "wvReplyPush", symbol: "wv_reply_push", params: ["i32", "i32"], returns: "i32" },
+    STR("wvReply", "wv_reply"),
+    // Retained handlers (format 4): registered once, valid for the app's
+    // lifetime, so wv_run is a plain blocking call. The request rides in as a
+    // `string` param (format 3) rather than a byte-at-a-time drain.
     {
-      name: "wvRun", symbol: "wv_run",
+      name: "wvOnInvoke", symbol: "wv_on_invoke",
       params: [
         "i32",
-        { callback: { id: "run", params: ["u32", "u32", { context: "run" }], returns: "i32", lifetime: "call" } },
-        { context: "run" },
+        { callback: { id: "inv", params: ["string", { context: "inv" }], returns: "i32", lifetime: "retained" } },
+        { context: "inv" },
       ],
       returns: "i32",
     },
+    {
+      name: "wvOnTick", symbol: "wv_on_tick",
+      params: [
+        "i32",
+        { callback: { id: "tick", params: [{ context: "tick" }], returns: "void", lifetime: "retained" } },
+        { context: "tick" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvRun", symbol: "wv_run", params: ["i32"], returns: "i32" },
     { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
+    // async: deferred returns + the UI-thread pump behind app.defer/sleep
+    { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
+    { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
+    { name: "wvTickStart", symbol: "wv_tick_start", params: ["i32", "i32"], returns: "i32" },
+    { name: "wvTickStop", symbol: "wv_tick_stop", params: ["i32"], returns: "i32" },
+    // async file I/O: the blocking syscall runs on a shim worker thread
+    { name: "wvFsRead", symbol: "wv_fs_read", params: ["i32", "string"], returns: "i32" },
+    { name: "wvFsWrite", symbol: "wv_fs_write", params: ["i32", "string", "string"], returns: "i32" },
+    { name: "wvFsStatus", symbol: "wv_fs_status", params: ["i32", "i32"], returns: "i32" },
+    {
+      name: "wvFsTake", symbol: "wv_fs_take",
+      params: [
+        "i32", "i32",
+        { callback: { id: "sink", params: ["string", { context: "sink" }], returns: "void", lifetime: "call" } },
+        { context: "sink" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvFsFree", symbol: "wv_fs_free", params: ["i32", "i32"], returns: "i32" },
   ];
 
+  if (process.platform === "win32") {
+    // MinGW ignores MSVC's #pragma comment(lib, ...), so the Win32 imports the
+    // WebView2 backend needs are named explicitly. scriptc's own win32 lane
+    // already adds advapi32/iphlpapi/ws2_32, so those are omitted here.
+    // `c++` pulls libc++ for the shim's std::string/exceptions.
+    //
+    // `pthread` (mingw's libwinpthread) is here to work around an upstream
+    // scriptc bug: its runtime calls clock_gettime/nanosleep, which mingw
+    // declares in <time.h> but implements in winpthreads, and scriptc's win32
+    // link never adds it. Without this the link dies with
+    // "undefined symbol: clock_gettime" — reproducible with a plain
+    // `scriptc build hello.ts` on Windows, no FFI involved.
+    return {
+      ffi_format: 4,
+      functions,
+      libraries: [shimLib],
+      system_libraries: [
+        "c++", "pthread",
+        "ole32", "oleaut32", "shlwapi", "shell32", "user32", "version", "gdi32",
+      ],
+    };
+  }
+
   if (process.platform === "darwin") {
     // scriptc has no -framework support, but `libraries` entries are passed to
     // the link as plain input files and ld64 accepts .tbd stubs.
     const sdk = capture(["xcrun", "--sdk", "macosx", "--show-sdk-path"]);
     return {
-      ffi_format: 2,
+      ffi_format: 4,
       functions,
       libraries: [
         shimLib,
@@ -119,7 +250,7 @@ function ffiManifest(shimLib) {
     };
   }
   return {
-    ffi_format: 2,
+    ffi_format: 4,
     functions,
     libraries: [shimLib],
     system_libraries: [
@@ -180,11 +311,15 @@ function build(root) {
   writeFileSync(join(buildDir, "janela.ffi.json"), JSON.stringify(ffiManifest(shimLib), null, 2) + "\n");
 
   console.log("janela: compiling TypeScript to a native binary");
-  const bin = join(outDir, conf.name);
+  // An explicit --out is used verbatim, so the PE suffix is ours to add.
+  const bin = join(outDir, process.platform === "win32" ? `${conf.name}.exe` : conf.name);
+  // No SCRIPTC_CC/SCRIPTC_TARGET on Windows: scriptc's default driver is
+  // plain `clang`, which is exactly the MinGW-targeting clang checked above.
   run(["node", scriptcBin(), "build", "entry.ts", "--ffi", "janela.ffi.json", "-o", bin], { cwd: buildDir });
 
   // Symbol/debug metadata is ~16% of the binary and apps don't need it.
-  // (On arm64 macOS, strip re-signs ad-hoc automatically.)
+  // (On arm64 macOS, strip re-signs ad-hoc automatically. MinGW keeps DWARF
+  // inside the .exe rather than a side-by-side .pdb, so Windows benefits too.)
   run(["strip", bin]);
 
   if (process.platform === "darwin") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "jn": "bin/janela.mjs"
   },
   "dependencies": {
-    "scriptc": "0.0.32"
+    "scriptc": "0.0.35"
   },
   "license": "MIT",
   "author": "Mateus Lage",
@@ -30,7 +30,7 @@
     "scriptc"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "files": [
     "bin/",