@openthink/ui-leaf 0.5.0 → 0.6.0

package/README.md

@@ -78,7 +78,11 @@ Three reasons:
 
 ## How it works
 
-`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. 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.
+
+**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"`).
+
+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.
 
@@ -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,8 +309,8 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openthink/ui-leaf",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Customizable browser views, on demand, for any CLI.",
   "license": "MIT",
   "author": "Matt Pardini",

package/packages/cli/dist/cli.js

@@ -337,7 +337,8 @@ async function startDevServer(opts) {
     csp,
     allowedHosts,
     silent = false,
-    _opener
+    _opener,
+    _heartbeatCheckIntervalMs = 1e3
   } = opts;
   const cspHeader = resolveCsp(csp);
   const allowedHostSet = new Set(DEFAULT_LOOPBACK_HOSTNAMES);
@@ -378,10 +379,13 @@ async function startDevServer(opts) {
     const viewState = { html: result.html, data: dataLoader ? loadedData : data };
     const listeners = /* @__PURE__ */ new Map([
       ["data-updated", /* @__PURE__ */ new Set()],
-      ["view-swapped", /* @__PURE__ */ new Set()]
+      ["view-swapped", /* @__PURE__ */ new Set()],
+      ["disconnected", /* @__PURE__ */ new Set()],
+      ["reconnected", /* @__PURE__ */ new Set()]
     ]);
     let lastHeartbeatAt = Date.now();
     let closeRequested = false;
+    let connectionState = "connecting";
     let resolveClosed = () => {
     };
     const closed = new Promise((r) => {
@@ -389,82 +393,105 @@ async function startDevServer(opts) {
     });
     const bunPort = port === void 0 ? 5810 : port;
     let actualPort = bunPort;
-    const server = (() => {
-      const handler = (req) => {
-        const host = req.headers.get("host") ?? void 0;
-        const origin = req.headers.get("origin") ?? void 0;
-        const hostOk = isAllowedHost(host, allowedHostSet);
-        const originOk = isAllowedOrigin(origin, allowedHostSet);
-        if (!hostOk || !originOk) {
-          const offender = !hostOk ? `Host "${host ?? "(absent)"}"` : `Origin "${origin}"`;
-          return new Response(
-            `ui-leaf: refusing request with ${offender} \u2014 only the following hostnames are accepted to prevent DNS rebinding: ${allowedHostList}. Open the server at http://localhost:${actualPort}/ or http://127.0.0.1:${actualPort}/, or pass { allowedHosts: ["my-alias"] } to mount() to permit a custom alias.
+    const handler = (req) => {
+      const host = req.headers.get("host") ?? void 0;
+      const origin = req.headers.get("origin") ?? void 0;
+      const hostOk = isAllowedHost(host, allowedHostSet);
+      const originOk = isAllowedOrigin(origin, allowedHostSet);
+      if (!hostOk || !originOk) {
+        const offender = !hostOk ? `Host "${host ?? "(absent)"}"` : `Origin "${origin}"`;
+        return new Response(
+          `ui-leaf: refusing request with ${offender} \u2014 only the following hostnames are accepted to prevent DNS rebinding: ${allowedHostList}. Open the server at http://localhost:${actualPort}/ or http://127.0.0.1:${actualPort}/, or pass { allowedHosts: ["my-alias"] } to mount() to permit a custom alias.
 `,
-            { status: 403, headers: { "Content-Type": "text/plain; charset=utf-8" } }
-          );
+          { status: 403, headers: { "Content-Type": "text/plain; charset=utf-8" } }
+        );
+      }
+      const headers = {};
+      if (cspHeader) {
+        headers["Content-Security-Policy"] = cspHeader;
+      }
+      const url2 = new URL(req.url);
+      const path = url2.pathname;
+      const method = req.method;
+      if (method === "GET" && path === "/") {
+        return new Response(viewState.html, {
+          status: 200,
+          headers: { ...headers, "Content-Type": "text/html; charset=utf-8" }
+        });
+      }
+      if (method === "POST" && path === "/heartbeat") {
+        if (!checkAuth(req, token)) {
+          return new Response(JSON.stringify({ error: "unauthorized" }), {
+            status: 401,
+            headers: { ...headers, "Content-Type": "application/json" }
+          });
         }
-        const headers = {};
-        if (cspHeader) {
-          headers["Content-Security-Policy"] = cspHeader;
+        lastHeartbeatAt = Date.now();
+        if (connectionState === "disconnected") {
+          connectionState = "connected";
+          fireEvent2("reconnected");
+        } else if (connectionState === "connecting") {
+          connectionState = "connected";
         }
-        const url2 = new URL(req.url);
-        const path = url2.pathname;
-        const method = req.method;
-        if (method === "GET" && path === "/") {
-          return new Response(viewState.html, {
-            status: 200,
-            headers: { ...headers, "Content-Type": "text/html; charset=utf-8" }
+        return new Response("", { status: 204, headers });
+      }
+      if (method === "POST" && path === "/mutate") {
+        if (!checkAuth(req, token)) {
+          return new Response(JSON.stringify({ error: "unauthorized" }), {
+            status: 401,
+            headers: { ...headers, "Content-Type": "application/json" }
           });
         }
-        if (method === "POST" && path === "/heartbeat") {
-          if (!checkAuth(req, token)) {
-            return new Response(JSON.stringify({ error: "unauthorized" }), {
-              status: 401,
-              headers: { ...headers, "Content-Type": "application/json" }
-            });
-          }
-          lastHeartbeatAt = Date.now();
-          return new Response("", { status: 204, headers });
-        }
-        if (method === "POST" && path === "/mutate") {
-          if (!checkAuth(req, token)) {
-            return new Response(JSON.stringify({ error: "unauthorized" }), {
-              status: 401,
-              headers: { ...headers, "Content-Type": "application/json" }
-            });
-          }
-          return handleMutate(req, mutations, headers);
+        return handleMutate(req, mutations, headers);
+      }
+      if (method === "GET" && path === "/api/data") {
+        if (!dataLoader) {
+          return new Response(JSON.stringify({ error: "not found" }), {
+            status: 404,
+            headers: { ...headers, "Content-Type": "application/json" }
+          });
         }
-        if (method === "GET" && path === "/api/data") {
-          if (!dataLoader) {
-            return new Response(JSON.stringify({ error: "not found" }), {
-              status: 404,
-              headers: { ...headers, "Content-Type": "application/json" }
-            });
-          }
-          if (!checkAuth(req, token)) {
-            return new Response(JSON.stringify({ error: "unauthorized" }), {
-              status: 401,
-              headers: { ...headers, "Content-Type": "application/json" }
-            });
-          }
-          return new Response(JSON.stringify(viewState.data !== void 0 ? viewState.data : null), {
-            status: 200,
+        if (!checkAuth(req, token)) {
+          return new Response(JSON.stringify({ error: "unauthorized" }), {
+            status: 401,
             headers: { ...headers, "Content-Type": "application/json" }
           });
         }
-        return new Response(JSON.stringify({ error: "not found" }), {
-          status: 404,
+        return new Response(JSON.stringify(viewState.data !== void 0 ? viewState.data : null), {
+          status: 200,
           headers: { ...headers, "Content-Type": "application/json" }
         });
-      };
+      }
+      return new Response(JSON.stringify({ error: "not found" }), {
+        status: 404,
+        headers: { ...headers, "Content-Type": "application/json" }
+      });
+    };
+    let heartbeatWatcher;
+    let bunServer;
+    const cleanup = async (reason) => {
+      if (closeRequested) return;
+      closeRequested = true;
+      if (heartbeatWatcher) clearInterval(heartbeatWatcher);
+      await bunServer.stop(true);
+      if (restoreStdout) restoreStdout();
+      resolveClosed(reason);
+    };
+    const serverErrorHandler = (_err) => {
+      void cleanup("error");
+      return new Response(JSON.stringify({ error: "internal server error" }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" }
+      });
+    };
+    bunServer = (() => {
       if (bunPort === 0) {
-        return Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: handler });
+        return Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: handler, error: serverErrorHandler });
       }
       const MAX_PORT_ATTEMPTS = 10;
       for (let i = 0; i < MAX_PORT_ATTEMPTS; i++) {
         try {
-          return Bun.serve({ hostname: "127.0.0.1", port: bunPort + i, fetch: handler });
+          return Bun.serve({ hostname: "127.0.0.1", port: bunPort + i, fetch: handler, error: serverErrorHandler });
         } catch (err) {
           const isAddrinuse = err instanceof Error && err.message.includes("EADDRINUSE");
           if (!isAddrinuse || i === MAX_PORT_ATTEMPTS - 1) {
@@ -479,25 +506,20 @@ async function startDevServer(opts) {
       }
       throw new Error("unreachable");
     })();
-    actualPort = server.port ?? bunPort;
+    actualPort = bunServer.port ?? bunPort;
     const url = `http://127.0.0.1:${actualPort}`;
     const startedAt = Date.now();
-    let heartbeatWatcher;
-    const cleanup = async () => {
-      if (closeRequested) return;
-      closeRequested = true;
-      if (heartbeatWatcher) clearInterval(heartbeatWatcher);
-      await server.stop(true);
-      if (restoreStdout) restoreStdout();
-      resolveClosed();
-    };
     heartbeatWatcher = setInterval(() => {
+      if (closeRequested) return;
       const now = Date.now();
       if (now - startedAt < startupGraceMs) return;
       if (now - lastHeartbeatAt > heartbeatTimeoutMs) {
-        void cleanup();
+        if (connectionState !== "disconnected") {
+          connectionState = "disconnected";
+          fireEvent2("disconnected");
+        }
       }
-    }, 1e3);
+    }, _heartbeatCheckIntervalMs);
     const doOpen = _opener ? () => _opener(url) : async () => {
       if (shell === "app") {
         const launched = await openInAppMode(url);
@@ -519,7 +541,7 @@ async function startDevServer(opts) {
       url,
       port: actualPort,
       closed,
-      close: cleanup,
+      close: (reason = "caller") => cleanup(reason),
       on(event, listener) {
         listeners.get(event)?.add(listener);
       },
@@ -644,11 +666,12 @@ async function mount(opts) {
     startupGraceMs: opts.startupGraceMs,
     csp: opts.csp,
     allowedHosts: opts.allowedHosts,
-    silent: opts.silent
+    silent: opts.silent,
+    _heartbeatCheckIntervalMs: opts._heartbeatCheckIntervalMs
   });
   const onSignal = (signal) => {
     void (async () => {
-      await server.close();
+      await server.close("signal");
       process.kill(process.pid, signal);
     })();
   };
@@ -664,8 +687,8 @@ async function mount(opts) {
       return {
         url: server.url,
         port: server.port,
-        closed: Promise.resolve(),
-        close: server.close,
+        closed: Promise.resolve("caller"),
+        close: () => server.close(),
         update: server.update.bind(server),
         swapView: (source) => server.swapView(source),
         patch: (data, source) => server.patch(data, source),
@@ -688,7 +711,7 @@ async function mount(opts) {
     url: server.url,
     port: server.port,
     closed,
-    close: server.close,
+    close: () => server.close(),
     update: server.update.bind(server),
     swapView: (source) => server.swapView(source),
     patch: (data, source) => server.patch(data, source),
@@ -894,6 +917,10 @@ async function runMount() {
       });
       return;
     }
+    if (msg.type === "close") {
+      void mountedView.close();
+      return;
+    }
     emit2({ type: "error", message: `unknown message type: ${msg.type}` });
   });
   rl.on("close", () => {
@@ -942,10 +969,12 @@ async function runMount() {
     if (stdinClosed) {
       void view.close();
     }
+    view.on("disconnected", () => emit2({ type: "disconnected" }));
+    view.on("reconnected", () => emit2({ type: "reconnected" }));
     emit2({ type: "ready", url: view.url, port: view.port });
-    await view.closed;
-    emit2({ type: "closed" });
-    process.exit(0);
+    const closeReason = await view.closed;
+    emit2({ type: "closed", reason: closeReason });
+    process.exit(closeReason === "error" ? 1 : 0);
   } catch (err) {
     emit2({
       type: "error",