janela 0.1.2 → 0.3.0

package/README.md

@@ -18,6 +18,19 @@ janela dev                # build + run with logs in the terminal
 janela build              # .janela/out/my-app  (+ my-app.app on macOS)
 ```
 
+Or start from a frontend framework — any Vite-based one:
+
+```bash
+janela init my-app --template vue     # or react | svelte | solid | vanilla
+cd my-app && npm install
+janela dev                            # Vite dev server + HMR, in a native window
+```
+
+`vanilla` is the default and needs no frontend toolchain at all. With a
+framework, `janela dev` runs your Vite dev server and points the window at it,
+and `janela build` flattens the production bundle into the binary — see
+[docs/frontend.md](../../docs/frontend.md).
+
 Requirements: Node 18+, a C++ compiler (Xcode CLT on macOS; g++ +
 `libwebkit2gtk-4.1-dev` on Linux; see [Windows](#windows) below). A worked
 example lives in [`examples/demo`](examples/demo) — commands, events, and a
@@ -41,9 +54,15 @@ 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.
+`janela build` produces a **GUI-subsystem** `.exe`, so no console window
+appears behind the UI — which also means `console.log` from a command has
+nowhere to go. `janela dev` keeps the console subsystem, so logs are there
+while you work. (scriptc exposes no way to pass `-mwindows` to the linker, so
+janela rewrites the PE `Subsystem` field after linking; see
+[docs/native-shell.md](../../docs/native-shell.md).)
+
+One caveat today: there is no installer step — you get a bare `.exe`, not an
+MSI.
 
 [llvm-mingw]: https://github.com/mstorsjo/llvm-mingw/releases
 
@@ -56,6 +75,10 @@ my-app/
 └── janela.conf.json    name, bundle identifier, version, window
 ```
 
+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):
 
 ```js
@@ -69,10 +92,10 @@ 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()
 }
@@ -85,19 +108,19 @@ 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", (argsJson, resolve, reject) => {
-  const a = JSON.parse(argsJson) as { ms: number };
-  app.sleep(a.ms, () => resolve(JSON.stringify("done")));   // resolve later
+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", (argsJson, resolve) => {
-  const a = JSON.parse(argsJson) as { n: number };
+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(JSON.stringify(i));
+    if (i < a.n) app.defer(step); else resolve(i);
   };
   app.defer(step);
 });
@@ -105,8 +128,36 @@ app.commandAsync("countTo", (argsJson, resolve) => {
 
 - `app.defer(fn)` — run `fn` on the next turn of the host loop.
 - `app.sleep(ms, fn)` — run `fn` after at least `ms`.
-- `resolve(json)` / `reject(json)` settle the page's promise; `reject` makes
-  `await janela.invoke(...)` throw. Settling twice is ignored.
+- `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 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.
 
 **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`,
@@ -124,6 +175,64 @@ 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.
 
+## Native dialogs and window control
+
+```ts
+app.commandAsync("openFile", (_args, resolve) => {
+  app.openFileDialog(
+    { title: "Pick a file", filters: [{ name: "Text", extensions: ["txt", "md"] }] },
+    (paths, err) => {
+      if (paths === null) { resolve({ cancelled: true }); return; }   // cancel
+      app.readFileAsync(paths[0], (rerr, text) => resolve({ path: paths[0], text }));
+    },
+  );
+});
+
+app.saveFileDialog({ defaultName: "untitled.txt" }, (path) => { /* … */ });
+
+app.setTitle("new title");
+app.setSize(720, 480, 0);
+app.setFullscreen(true);
+```
+
+A cancel is `null`, not an error. Options: `title`, `defaultPath`, `filters`,
+plus `multiple` and `directory` for open, and `defaultName` for save.
+`directory: true` is not supported on Windows and reports `ENOTSUP`.
+
+Use `commandAsync` for dialogs — the user may take as long as they like, and
+the window keeps serving other calls meanwhile. The modal itself runs on a
+later UI-thread turn rather than inside the call that requests it, because a
+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.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` +
@@ -133,12 +242,12 @@ 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
@@ -151,12 +260,12 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 
 ## Status
 
-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
-that run in parallel (host code is single-threaded; `commandAsync` interleaves
-instead), native dialogs/tray/menus, multi-window,
-icons/installers/notarization.
+Early proof of concept, on macOS (arm64), Linux (WebKitGTK) and Windows
+(WebView2). The design notes and scriptc findings behind it are in
+[docs/findings.md](../../docs/findings.md). Not yet: async commands that run in
+parallel (host code is single-threaded; `commandAsync` interleaves instead),
+tray icons and menus, multi-window, directory picking on Windows,
+`app.center()`, and icons/installers/notarization.
 
 ## Releasing