@openthink/ui-leaf 0.4.0 → 0.6.0

package/README.md

@@ -78,11 +78,15 @@ Three reasons:
 
 ## How it works
 
-`mount()` spins up a local dev server (rsbuild + React under the hood), bundles your view file, injects the data into `window.__UI_LEAF__.data`, and opens the user's default browser. Mutations from the view POST back to a localhost endpoint with a per-launch random token; the runtime dispatches them to the handlers you registered. Browser tab close → heartbeat stops → server shuts down → `view.closed` resolves and your CLI continues.
+`mount()` compiles your view file once with `Bun.build`, injects data into `window.__UI_LEAF__`, starts a `Bun.serve` HTTP server, and opens the user's default browser. Mutations from the view POST back to a localhost endpoint with a per-launch random token; the runtime dispatches them to the handlers you registered.
 
-The transport is HTTP + JSON over loopback. The token is in `window.__UI_LEAF__.token`, and it's served inline in the HTML at `/index.html` — so the token only protects against drive-by cross-origin requests in the user's browser, not against other processes on the same machine. Any local process that can reach `127.0.0.1:<port>` can fetch the page, grep the token out, and call `/mutate` with it; treat any local process you don't trust as having the same access as the view. View bundling resolves React from `ui-leaf`'s installed location, so your project doesn't need to install React.
+**Heartbeat and lifecycle.** The browser tab sends periodic heartbeats while the page is open. When heartbeats stop (tab closed or navigated away), `mount()` emits a `disconnected` event but the server stays running — the port, token, and in-memory data are all preserved. When a tab reconnects (heartbeat resumes), a `reconnected` event fires. Any data updates or view swaps that arrive during the disconnected window take effect on the next load. The mount terminates only on an explicit caller close (`view.close()` or the inbound `{type:"close"}` message), a signal (SIGINT/SIGTERM), or an internal error — and `view.closed` resolves to the reason (`"caller"`, `"signal"`, or `"error"`).
 
-The same trust boundary applies to the `data` you pass to `mount()`. The payload is JSON-inlined into `window.__UI_LEAF__.data` in the same `/index.html`, and is also written to `<tmpdir()>/ui-leaf-XXXXXX/index.html` on disk for the mount lifetime — readable by the same set of same-UID local processes that can read the token. For PHI, PCI, financial records, or anything else where a same-UID local reader is in your threat model, don't pass the sensitive payload through `data`; keep it in your CLI's memory and inject it into the view via an authenticated `connect-src 'self'` fetch on boot. See "Data-at-rest in the temp directory" below for the disk-residency details.
+Multi-tab note: `disconnected` fires only when **all** open tabs go silent — the heartbeat is a single high-water mark across tabs, so closing one tab while another is open emits no event.
+
+The transport is HTTP + JSON over loopback. The token is in `window.__UI_LEAF__.token`, served inline in the compiled HTML — so the token only protects against drive-by cross-origin requests in the user's browser, not against other processes on the same machine. Any local process that can reach `127.0.0.1:<port>` can fetch `GET /`, grep the token out, and call `/mutate` or `/api/data` with it; treat any local process you don't trust as having the same access as the view. View bundling resolves React from `ui-leaf`'s installed location, so your project doesn't need to install React.
+
+The same trust boundary applies to the `data` you pass to `mount()`. The payload is JSON-inlined into `window.__UI_LEAF__.data` in the served HTML and held in memory for the mount lifetime — readable by the same set of same-UID local processes that can read the token. For PHI, PCI, financial records, or anything else where a same-UID local reader is in your threat model, use `dataLoader` instead — the loader's return value is served at a token-gated `/api/data` endpoint and never appears in the HTML. See "Data-at-rest" below for details.
 
 ## API surface
 
@@ -97,7 +101,7 @@ await mount({
   mutations,                                 // Record<string, MutationHandler> (optional)
   viewsRoot,                                 // optional, default: <cwd>/views
   title,                                     // optional, default: "ui-leaf"
-  port,                                      // optional, default: 5810 (auto-bumps if busy)
+  port,                                      // optional, default: 5810 (auto-bumps if busy; pass 0 for OS-assigned)
   openBrowser,                               // optional, default: true
   shell,                                     // optional, "tab" | "app", default: "tab"
   csp,                                       // optional, default: "off" (see Hardening)
@@ -130,7 +134,7 @@ mount({
 
 - **Locks `connect-src` to same-origin** — the architectural lock. Views cannot fetch external APIs; all data flows through `data` and `mutations`.
 - **Permits HTTPS images and fonts** so views can load CDN assets normally.
-- **Allows inline styles, eval, and inline scripts** for React + rsbuild's HMR.
+- **Allows inline styles and inline scripts** for React.
 
 Because the policy is sent as an HTTP response header, views cannot relax it at runtime. The only way to weaken the policy is to change the `mount()` call (i.e. fork the consumer CLI, not the view).
 
@@ -156,22 +160,22 @@ mount({
 
 Be deliberate — every name you add becomes a viable rebinding target. Don't add public DNS names or LAN hostnames you don't fully control.
 
-### Data-at-rest in the temp directory
+### Data-at-rest
 
-ui-leaf serialises the `data` you pass to `mount()` into `<tmpdir()>/ui-leaf-XXXXXX/index.html` so the dev server can serve it. The directory is created with `mode 0700` (readable only by the same UID), and ui-leaf removes it on `close()`, on `SIGINT`/`SIGTERM`, on uncaught throws via a `process.on('exit')` fallback, and opportunistically sweeps `ui-leaf-*` siblings older than 24h on every startup to catch anything that still slipped through.
+The `data` you pass to `mount()` is JSON-inlined into the compiled HTML that `GET /` serves, and held in memory for the mount lifetime. It is **not written to disk** — the compiled HTML exists only in process memory. A same-UID local process that can reach `127.0.0.1:<port>` can still recover the data by fetching `GET /` (no token required), so `data` is appropriate for routine payloads but not for PHI, PCI, or financial records where in-HTML exposure is in your threat model.
 
-What still leaks: `SIGKILL`, OOM-kill, and abrupt power loss skip every Node hook, so the directory stays on disk until the next `mount()` runs (the startup sweep) or the OS rotates `tmpdir()` (on macOS, only across reboots; on many Linux systems, only via `tmpfiles.d` age policies). If the data is sensitive enough that even that bounded window is too long, use `dataLoader` instead of `data`:
+For sensitive payloads use `dataLoader` instead of `data`:
 
 ```ts
 mount({
   view: "report",
   dataLoader: async () => {
-    return await db.fetchSensitiveRecords(); // stays in memory; never touches disk
+    return await db.fetchSensitiveRecords(); // stays in memory; never appears in HTML
   },
 });
 ```
 
-`dataLoader` invokes the function once at mount time, captures the result in-process, and serves it at a token-gated `GET /api/data` endpoint using the same per-launch token as `/mutate`. The view fetches `/api/data` on first render. Nothing is written to `index.html` or any tempdir file — the payload stays in memory for the entire mount lifetime. `data` remains the ergonomic default for routine payloads where disk residency is not a concern.
+`dataLoader` invokes the function once at mount time, captures the result in-process, and serves it at a token-gated `GET /api/data` endpoint using the same per-launch token as `/mutate`. The view fetches `/api/data` on first render. The payload never appears in the HTML — it can only be read by a caller that already has the token. Note that a local process that can fetch `GET /` (no auth) can still read the token from `window.__UI_LEAF__.token` and then call `/api/data` — so `dataLoader` hardens against HTML-level exposure, not against a determined same-UID reader.
 
 ## Sharing views across users
 
@@ -237,12 +241,22 @@ What the consumer CLI is responsible for (out of ui-leaf's scope):
     {"type":"result","id":1,"value":{"ok":true}}
     {"type":"error","id":2,"message":"…"}
     ```
+  - **Or live-update / control messages:**
+    ```json
+    {"version":"1","type":"update","data":{}}
+    {"version":"1","type":"view","source":"<tsx>"}
+    {"version":"1","type":"patch","data":{},"view":{"source":"<tsx>"}}
+    {"version":"1","type":"reopen"}
+    {"version":"1","type":"close"}
+    ```
 - **stdout (line-delimited JSON):**
   - `{"type":"ready","url":"http://127.0.0.1:54321","port":54321}` — emitted once when the dev server is up
   - `{"type":"mutate","id":1,"name":"refresh","args":{}}` — emitted when a view triggers a mutation; respond on stdin
-  - `{"type":"closed"}` — emitted on natural close (browser tab closed, heartbeat timeout)
+  - `{"type":"disconnected"}` — browser tab stopped heartbeating; mount stays alive
+  - `{"type":"reconnected"}` — browser reconnected after a disconnect
+  - `{"type":"closed","reason":"caller"}` — mount terminated; reason is `caller` | `signal` | `error`
   - `{"type":"error","message":"…"}` — emitted on internal failure
-- **Lifecycle:** binary exits 0 on natural close, 1 on internal error; closing stdin from the parent triggers shutdown.
+- **Lifecycle:** binary exits 0 on `closed`, 1 on internal error. The mount does **not** auto-terminate when the browser disconnects — only an explicit `{type:"close"}` message, stdin close, SIGINT/SIGTERM, or internal error terminates it. Closing stdin from the parent triggers a `caller` close.
 
 ### Minimal Bash example (read-only view, no mutations)
 
@@ -250,8 +264,10 @@ What the consumer CLI is responsible for (out of ui-leaf's scope):
 CONFIG='{"view":"spec","viewsRoot":"/abs/path/to/views","data":{"markdown":"# hi"},"port":0}'
 echo "$CONFIG" | ui-leaf mount
 # → {"type":"ready","url":"http://127.0.0.1:54321","port":54321}
-# (browser opens; user closes tab)
-# → {"type":"closed"}
+# (browser opens; user closes tab → disconnected; mount stays running)
+# → {"type":"disconnected"}
+# (send {"type":"close"} on stdin to terminate)
+# → {"type":"closed","reason":"caller"}
 ```
 
 ### Worked example with mutations
@@ -273,10 +289,18 @@ Child → parent stdout:
 Parent → child stdin (after handling the mutation):
   {"type":"result","id":1,"value":{"count":1}}
 
-(user closes tab)
+(user closes tab → mount stays running)
+
+Child → parent stdout:
+  {"type":"disconnected"}
+
+(parent decides to shut down)
+
+Parent → child stdin:
+  {"type":"close"}
 
 Child → parent stdout:
-  {"type":"closed"}
+  {"type":"closed","reason":"caller"}
 ```
 
 Each pending mutation has a unique `id`. Multiple mutations can be in flight concurrently — match `result`/`error` responses by id.
@@ -285,13 +309,13 @@ Each pending mutation has a unique `id`. Multiple mutations can be in flight con
 
 - **Pass `viewsRoot` as an absolute path.** No `cwd/views` default games when invoked from another process.
 - **Pass `port: 0`.** ui-leaf asks the OS for a free port and reports it back in the `ready` event. Lets you run concurrent views without collision.
-- **Lower `heartbeatTimeoutMs`** (e.g. 5000) so orphaned ui-leaf children exit fast if your parent process dies. The default 75000 is tuned for human-direct use (survives one browser background-tab throttle) and is too long when a parent process is supervising.
-- **Kill the child on parent shutdown** rather than relying on heartbeat — `kill <pid>` from the parent. Closing stdin also triggers a clean shutdown.
+- **Lower `heartbeatTimeoutMs`** (e.g. 5000) to get faster `disconnected` events. Note that heartbeat timeout no longer terminates the mount — the mount only terminates on an explicit `{type:"close"}` message, stdin close, or signal. If you want fast shutdown on tab close, listen for `disconnected` and send `{type:"close"}` on stdin.
+- **Kill the child on parent shutdown** rather than relying on heartbeat — `kill <pid>` from the parent, or close stdin (which triggers a `caller` close).
 - **Declare every mutation name** the view will call in the `mutations: []` array. The binary only routes mutations whose names appear in the list; calls to undeclared names get a 404 from `/mutate` with the standard "no mutation handler registered for X" error, and the view's `mutate()` promise rejects.
 
 ### Driving from Node via `mount()` directly
 
-If your consumer is itself Node (or you want a thin in-process integration), use the SDK directly. Pass `silent: true` to suppress rsbuild output so you can keep stdout clean for your own protocol (capture `process.stdout.write` *before* calling `mount()`, since the option redirects stdout to stderr for the lifetime of the dev server):
+If your consumer is itself Node (or you want a thin in-process integration), use the SDK directly. Pass `silent: true` to redirect stdout to stderr for the lifetime of the server, keeping stdout clean for your own protocol (capture `process.stdout.write` *before* calling `mount()` if you need to write to real stdout from the same process):
 
 ```ts
 const realStdoutWrite = process.stdout.write.bind(process.stdout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openthink/ui-leaf",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Customizable browser views, on demand, for any CLI.",
   "license": "MIT",
   "author": "Matt Pardini",
@@ -25,41 +25,38 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./packages/cli/dist/index.d.ts",
+      "import": "./packages/cli/dist/index.js"
     },
     "./view": {
-      "types": "./dist/view.d.ts",
-      "import": "./dist/view.js"
+      "types": "./packages/cli/dist/view.d.ts",
+      "import": "./packages/cli/dist/view.js"
     }
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./packages/cli/dist/index.js",
+  "types": "./packages/cli/dist/index.d.ts",
   "bin": {
-    "ui-leaf": "./dist/cli.js"
+    "ui-leaf": "./packages/cli/dist/cli.js"
   },
   "files": [
-    "dist",
+    "packages/cli/dist",
+    "packages/cli/package.json",
     "README.md",
     "LICENSE"
   ],
+  "workspaces": ["packages/*"],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
+    "build": "bun run --filter '@openthink/ui-leaf-cli' build",
+    "dev": "bun run --filter '@openthink/ui-leaf-cli' dev",
+    "typecheck": "tsc --noEmit -p packages/cli/tsconfig.src.json",
     "test": "bun test",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "tsup": "^8.4.0",
     "typescript": "^6.0.0"
   },
   "dependencies": {
-    "@rsbuild/core": "^2.0.1",
-    "@rsbuild/plugin-react": "^2.0.0",
     "open": "^11.0.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"