@openthink/ui-leaf 0.6.0 → 0.7.0

package/package.json

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

package/packages/cli/dist/cli.js

@@ -38,13 +38,15 @@ var reactAliasPlugin = {
     });
   }
 };
+var SESSION_ENDED_HTML = '<div style="font-family:sans-serif;padding:2em;color:#555"><p>Session ended \u2014 re-launch the CLI to continue.</p></div>';
+var CLOSED_OVERLAY_HTML = '<div style="font-family:sans-serif;padding:2em;color:#555"><p>This view has closed.</p></div>';
 var SHARED_BRIDGE = `
 async function mutate(name: string, args?: unknown): Promise<unknown> {
   const res = await fetch("/mutate", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      ...(token ? { Authorization: "Bearer " + token } : {}),
+      ...(token ? { "X-UI-Leaf-Token": token } : {}),
     },
     body: JSON.stringify({ name, args }),
   });
@@ -66,12 +68,64 @@ async function heartbeat(): Promise<void> {
   try {
     await fetch("/heartbeat", {
       method: "POST",
-      headers: token ? { Authorization: "Bearer " + token } : {},
+      headers: token ? { "X-UI-Leaf-Token": token } : {},
     });
   } catch { /* server may have shut down; ignore */ }
 }
 setInterval(heartbeat, 5000);
-heartbeat();`;
+heartbeat();
+
+function subscribeEvents(onEvent: (ev: { type: string; [k: string]: unknown }) => void): void {
+  let delay = 250;
+  const budget = 30_000;
+  const started = Date.now();
+  let done = false;
+
+  async function connect(): Promise<void> {
+    try {
+      const res = await fetch("/events", {
+        headers: token ? { "X-UI-Leaf-Token": token } : {},
+      });
+      if (!res.ok || !res.body) throw new Error("bad status " + res.status);
+      delay = 250;
+      const reader = res.body.getReader();
+      const dec = new TextDecoder("utf-8");
+      let buf = "";
+      while (true) {
+        const { done: streamDone, value } = await reader.read();
+        if (streamDone) break;
+        buf += dec.decode(value, { stream: true });
+        let idx: number;
+        while ((idx = buf.indexOf("\\n\\n")) !== -1) {
+          const chunk = buf.slice(0, idx);
+          buf = buf.slice(idx + 2);
+          for (const line of chunk.split("\\n")) {
+            if (line.startsWith("data:")) {
+              try {
+                const ev = JSON.parse(line.slice(5).trimStart()) as { type: string; [k: string]: unknown };
+                if (ev.type === "closing") done = true;
+                onEvent(ev);
+              } catch { /* skip malformed event */ }
+            }
+          }
+        }
+        if (done) return;
+      }
+    } catch {
+      if (done) return;
+    }
+    if (done) return;
+    if (Date.now() - started > budget) {
+      onEvent({ type: "closing", reason: "error" });
+      return;
+    }
+    await new Promise<void>((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, 5_000);
+    void connect();
+  }
+
+  void connect();
+}`;
 async function runBunBuild(entryPath) {
   let buildOutput;
   try {
@@ -104,21 +158,21 @@ async function runBunBuild(entryPath) {
   return { js: await output.text() };
 }
 function assembleHtml(opts) {
-  const { js, title, csp, data, token, dataLoader } = opts;
+  const { js, title, csp, data, dataLoader } = opts;
   const safeJs = js.replace(/<\/script>/gi, "<\\/script>");
   const titleEscaped = title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
   const cspMeta = csp ? `    <meta http-equiv="Content-Security-Policy" content="${csp.replace(/&/g, "&amp;").replace(/"/g, "&quot;")}" />
 ` : "";
-  const safeToken = token ? escapeForScriptTag(JSON.stringify(token)) : null;
-  const tokenField = safeToken ? `, token: ${safeToken}` : "";
-  const bootstrapValue = dataLoader ? `{ token: ${safeToken ?? '""'} }` : `{ data: JSON.parse(${escapeForScriptTag(JSON.stringify(JSON.stringify(data ?? null)))})${tokenField} }`;
+  const dataInit = dataLoader ? "window.__UI_LEAF__ = {};" : `window.__UI_LEAF__ = { data: JSON.parse(${escapeForScriptTag(JSON.stringify(JSON.stringify(data ?? null)))}) };`;
+  const bootstrapScript = `${dataInit}
+(function(){var m=/[#&]token=([^&#]*)/.exec(window.location.hash);if(m){try{window.__UI_LEAF__.token=decodeURIComponent(m[1]);history.replaceState(null,"",window.location.pathname+window.location.search);}catch(e){window.__UI_LEAF__.sessionEnded=true;}}else{window.__UI_LEAF__.sessionEnded=true;}})();`;
   return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <title>${titleEscaped}</title>
 ${cspMeta}    <!-- ui-leaf bootstrap -->
-    <script>window.__UI_LEAF__ = ${bootstrapValue};</script>
+    <script>${bootstrapScript}</script>
   </head>
   <body>
     <div id="root"></div>
@@ -133,9 +187,9 @@ async function compileView(opts) {
     data,
     title = "ui-leaf",
     csp,
-    // allowedHosts has no compile-time effect; accepted for API symmetry.
+    // allowedHosts and token have no compile-time effect; accepted for API symmetry.
     allowedHosts: _allowedHosts,
-    token,
+    token: _token,
     dataLoader = false
   } = opts;
   const viewsRootAbs = resolve(viewsRoot);
@@ -175,41 +229,75 @@ async function compileView(opts) {
     const entryContent = dataLoader ? `import { createRoot } from "react-dom/client";
 import View from ${JSON.stringify(viewAbs)};
 
-const ctx = (globalThis as { __UI_LEAF__?: { token?: string } }).__UI_LEAF__ ?? {};
+const ctx = (globalThis as { __UI_LEAF__?: { token?: string; sessionEnded?: boolean } }).__UI_LEAF__ ?? {};
 const token = ctx.token;
+
+if (ctx.sessionEnded) {
+  const root = document.getElementById("root");
+  if (root) root.innerHTML = ${JSON.stringify(SESSION_ENDED_HTML)};
+} else {
 ${SHARED_BRIDGE}
 
-async function bootstrap(): Promise<void> {
-  const res = await fetch("/api/data", {
-    headers: token ? { Authorization: "Bearer " + token } : {},
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error("ui-leaf: /api/data fetch failed (" + res.status + "): " + text);
+  async function bootstrap(): Promise<void> {
+    const res = await fetch("/api/data", {
+      headers: token ? { "X-UI-Leaf-Token": token } : {},
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error("ui-leaf: /api/data fetch failed (" + res.status + "): " + text);
+    }
+    let currentData: unknown = await res.json();
+    const el = document.getElementById("root");
+    if (!el) throw new Error("ui-leaf: #root element missing");
+    const root = createRoot(el);
+    root.render(<View data={currentData} mutate={mutate} />);
+    subscribeEvents((ev) => {
+      if (ev.type === "data-updated") {
+        currentData = ev.data;
+        root.render(<View data={currentData} mutate={mutate} />);
+      } else if (ev.type === "view-swapped") {
+        window.location.reload();
+      } else if (ev.type === "closing") {
+        el.innerHTML = ${JSON.stringify(CLOSED_OVERLAY_HTML)};
+      }
+    });
   }
-  const data = await res.json();
-  const el = document.getElementById("root");
-  if (!el) throw new Error("ui-leaf: #root element missing");
-  createRoot(el).render(<View data={data} mutate={mutate} />);
+  bootstrap();
 }
-bootstrap();
 ` : `import { createRoot } from "react-dom/client";
 import View from ${JSON.stringify(viewAbs)};
 
-const ctx = (globalThis as { __UI_LEAF__?: { data?: unknown; token?: string } }).__UI_LEAF__ ?? {};
-const data = ctx.data;
+const ctx = (globalThis as { __UI_LEAF__?: { data?: unknown; token?: string; sessionEnded?: boolean } }).__UI_LEAF__ ?? {};
 const token = ctx.token;
+
+if (ctx.sessionEnded) {
+  const root = document.getElementById("root");
+  if (root) root.innerHTML = ${JSON.stringify(SESSION_ENDED_HTML)};
+} else {
+  let currentData: unknown = ctx.data;
 ${SHARED_BRIDGE}
 
-const el = document.getElementById("root");
-if (!el) throw new Error("ui-leaf: #root element missing");
-createRoot(el).render(<View data={data} mutate={mutate} />);
+  const el = document.getElementById("root");
+  if (!el) throw new Error("ui-leaf: #root element missing");
+  const root = createRoot(el);
+  root.render(<View data={currentData} mutate={mutate} />);
+  subscribeEvents((ev) => {
+    if (ev.type === "data-updated") {
+      currentData = ev.data;
+      root.render(<View data={currentData} mutate={mutate} />);
+    } else if (ev.type === "view-swapped") {
+      window.location.reload();
+    } else if (ev.type === "closing") {
+      el.innerHTML = ${JSON.stringify(CLOSED_OVERLAY_HTML)};
+    }
+  });
+}
 `;
     await writeFile(entryPath, entryContent);
     const buildResult = await runBunBuild(entryPath);
     if ("errors" in buildResult) return { html: "", errors: buildResult.errors };
     return {
-      html: assembleHtml({ js: buildResult.js, title, csp, data, token, dataLoader }),
+      html: assembleHtml({ js: buildResult.js, title, csp, data, dataLoader }),
       errors: []
     };
   } finally {
@@ -217,7 +305,7 @@ createRoot(el).render(<View data={data} mutate={mutate} />);
   }
 }
 async function compileSource(opts) {
-  const { source, data, title = "ui-leaf", csp, token } = opts;
+  const { source, data, title = "ui-leaf", csp, token: _token } = opts;
   const tempDir = await mkdtemp(join(tmpdir(), "ui-leaf-src-"));
   try {
     const viewPath = join(tempDir, "view.tsx");
@@ -226,20 +314,37 @@ async function compileSource(opts) {
     const entryContent = `import { createRoot } from "react-dom/client";
 import View from ${JSON.stringify(viewPath)};
 
-const ctx = (globalThis as { __UI_LEAF__?: { data?: unknown; token?: string } }).__UI_LEAF__ ?? {};
-const data = ctx.data;
+const ctx = (globalThis as { __UI_LEAF__?: { data?: unknown; token?: string; sessionEnded?: boolean } }).__UI_LEAF__ ?? {};
 const token = ctx.token;
+
+if (ctx.sessionEnded) {
+  const root = document.getElementById("root");
+  if (root) root.innerHTML = ${JSON.stringify(SESSION_ENDED_HTML)};
+} else {
+  let currentData: unknown = ctx.data;
 ${SHARED_BRIDGE}
 
-const el = document.getElementById("root");
-if (!el) throw new Error("ui-leaf: #root element missing");
-createRoot(el).render(<View data={data} mutate={mutate} />);
+  const el = document.getElementById("root");
+  if (!el) throw new Error("ui-leaf: #root element missing");
+  const root = createRoot(el);
+  root.render(<View data={currentData} mutate={mutate} />);
+  subscribeEvents((ev) => {
+    if (ev.type === "data-updated") {
+      currentData = ev.data;
+      root.render(<View data={currentData} mutate={mutate} />);
+    } else if (ev.type === "view-swapped") {
+      window.location.reload();
+    } else if (ev.type === "closing") {
+      el.innerHTML = ${JSON.stringify(CLOSED_OVERLAY_HTML)};
+    }
+  });
+}
 `;
     await writeFile(entryPath, entryContent);
     const buildResult = await runBunBuild(entryPath);
     if ("errors" in buildResult) return { html: "", errors: buildResult.errors };
     return {
-      html: assembleHtml({ js: buildResult.js, title, csp, data, token, dataLoader: false }),
+      html: assembleHtml({ js: buildResult.js, title, csp, data, dataLoader: false }),
       errors: []
     };
   } finally {
@@ -348,8 +453,19 @@ async function startDevServer(opts) {
   try {
     let fireEvent2 = function(event) {
       for (const fn of listeners.get(event)) fn();
+    }, broadcast2 = function(event) {
+      const frame = sseEncoder.encode(`data: ${JSON.stringify(event)}
+
+`);
+      for (const controller of sseClients) {
+        try {
+          controller.enqueue(frame);
+        } catch {
+          sseClients.delete(controller);
+        }
+      }
     };
-    var fireEvent = fireEvent2;
+    var fireEvent = fireEvent2, broadcast = broadcast2;
     if (view.includes("/") || view.includes("\\")) {
       throw new Error(
         `ui-leaf: view '${view}' must be a bare identifier with no path separators`
@@ -383,6 +499,8 @@ async function startDevServer(opts) {
       ["disconnected", /* @__PURE__ */ new Set()],
       ["reconnected", /* @__PURE__ */ new Set()]
     ]);
+    const sseClients = /* @__PURE__ */ new Set();
+    const sseEncoder = new TextEncoder();
     let lastHeartbeatAt = Date.now();
     let closeRequested = false;
     let connectionState = "connecting";
@@ -421,10 +539,7 @@ async function startDevServer(opts) {
       }
       if (method === "POST" && path === "/heartbeat") {
         if (!checkAuth(req, token)) {
-          return new Response(JSON.stringify({ error: "unauthorized" }), {
-            status: 401,
-            headers: { ...headers, "Content-Type": "application/json" }
-          });
+          return new Response("", { status: 401, headers });
         }
         lastHeartbeatAt = Date.now();
         if (connectionState === "disconnected") {
@@ -437,10 +552,7 @@ async function startDevServer(opts) {
       }
       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 new Response("", { status: 401, headers });
         }
         return handleMutate(req, mutations, headers);
       }
@@ -452,16 +564,44 @@ async function startDevServer(opts) {
           });
         }
         if (!checkAuth(req, token)) {
-          return new Response(JSON.stringify({ error: "unauthorized" }), {
-            status: 401,
-            headers: { ...headers, "Content-Type": "application/json" }
-          });
+          return new Response("", { status: 401, headers });
         }
         return new Response(JSON.stringify(viewState.data !== void 0 ? viewState.data : null), {
           status: 200,
           headers: { ...headers, "Content-Type": "application/json" }
         });
       }
+      if (method === "GET" && path === "/events") {
+        if (!checkAuth(req, token)) {
+          return new Response("", { status: 401, headers });
+        }
+        let sseController;
+        const stream = new ReadableStream({
+          start(controller) {
+            sseController = controller;
+            sseClients.add(controller);
+            controller.enqueue(sseEncoder.encode(": connected\n\n"));
+            req.signal?.addEventListener("abort", () => {
+              sseClients.delete(sseController);
+              try {
+                sseController.close();
+              } catch {
+              }
+            });
+          },
+          cancel() {
+            sseClients.delete(sseController);
+          }
+        });
+        return new Response(stream, {
+          status: 200,
+          headers: {
+            ...headers,
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache"
+          }
+        });
+      }
       return new Response(JSON.stringify({ error: "not found" }), {
         status: 404,
         headers: { ...headers, "Content-Type": "application/json" }
@@ -473,7 +613,15 @@ async function startDevServer(opts) {
       if (closeRequested) return;
       closeRequested = true;
       if (heartbeatWatcher) clearInterval(heartbeatWatcher);
-      await bunServer.stop(true);
+      broadcast2({ type: "closing", reason });
+      for (const controller of sseClients) {
+        try {
+          controller.close();
+        } catch {
+        }
+      }
+      sseClients.clear();
+      await bunServer.stop();
       if (restoreStdout) restoreStdout();
       resolveClosed(reason);
     };
@@ -486,12 +634,12 @@ async function startDevServer(opts) {
     };
     bunServer = (() => {
       if (bunPort === 0) {
-        return Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: handler, error: serverErrorHandler });
+        return Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: handler, error: serverErrorHandler, idleTimeout: 0 });
       }
       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, error: serverErrorHandler });
+          return Bun.serve({ hostname: "127.0.0.1", port: bunPort + i, fetch: handler, error: serverErrorHandler, idleTimeout: 0 });
         } catch (err) {
           const isAddrinuse = err instanceof Error && err.message.includes("EADDRINUSE");
           if (!isAddrinuse || i === MAX_PORT_ATTEMPTS - 1) {
@@ -520,18 +668,19 @@ async function startDevServer(opts) {
         }
       }
     }, _heartbeatCheckIntervalMs);
-    const doOpen = _opener ? () => _opener(url) : async () => {
+    const openUrl = `${url}/#token=${token}`;
+    const doOpen = _opener ? () => _opener(openUrl) : async () => {
       if (shell === "app") {
-        const launched = await openInAppMode(url);
+        const launched = await openInAppMode(openUrl);
         if (!launched) {
           process.stderr.write(
             `ui-leaf: shell:"app" requested but no Chromium browser found; falling back to default browser tab.
 `
           );
-          await open(url);
+          await open(openUrl);
         }
       } else {
-        await open(url);
+        await open(openUrl);
       }
     };
     if (openBrowser) {
@@ -550,6 +699,7 @@ async function startDevServer(opts) {
       },
       update(newData) {
         viewState.data = newData;
+        broadcast2({ type: "data-updated", data: newData });
         fireEvent2("data-updated");
       },
       async swapView(source) {
@@ -562,6 +712,7 @@ async function startDevServer(opts) {
         });
         if (r.errors.length > 0) return r.errors;
         viewState.html = r.html;
+        broadcast2({ type: "view-swapped" });
         fireEvent2("view-swapped");
         return [];
       },
@@ -576,6 +727,8 @@ async function startDevServer(opts) {
         if (r.errors.length > 0) return r.errors;
         viewState.data = newData;
         viewState.html = r.html;
+        broadcast2({ type: "data-updated", data: newData });
+        broadcast2({ type: "view-swapped" });
         fireEvent2("data-updated");
         fireEvent2("view-swapped");
         return [];
@@ -590,10 +743,9 @@ async function startDevServer(opts) {
   }
 }
 function checkAuth(req, token) {
-  const header = req.headers.get("authorization") ?? "";
-  const match = /^Bearer (.+)$/.exec(header);
-  if (!match) return false;
-  return timingSafeEqual(match[1], token);
+  const value = req.headers.get("x-ui-leaf-token") ?? "";
+  if (!value) return false;
+  return timingSafeEqual(value, token);
 }
 async function handleMutate(req, mutations, headers) {
   const contentLength = req.headers.get("content-length");
@@ -728,6 +880,80 @@ function emit(event) {
   return `${JSON.stringify(stamped)}
 `;
 }
+function validateInboundShape(msg, kind) {
+  if (typeof msg !== "object" || msg === null) {
+    return { ok: false, reason: "message is not an object" };
+  }
+  const m = msg;
+  if (kind === "config") {
+    if (typeof m.view !== "string" || m.view === "") {
+      return { ok: false, reason: 'config requires a non-empty string "view"' };
+    }
+    if (typeof m.viewsRoot !== "string" || m.viewsRoot === "") {
+      return { ok: false, reason: 'config requires a non-empty string "viewsRoot"' };
+    }
+    if ("mutations" in m && m.mutations !== void 0) {
+      if (!Array.isArray(m.mutations) || !m.mutations.every((x) => typeof x === "string")) {
+        return { ok: false, reason: "config.mutations must be an array of strings" };
+      }
+    }
+    if ("port" in m && m.port !== void 0 && typeof m.port !== "number") {
+      return { ok: false, reason: "config.port must be a number" };
+    }
+    if ("openBrowser" in m && m.openBrowser !== void 0 && typeof m.openBrowser !== "boolean") {
+      return { ok: false, reason: "config.openBrowser must be a boolean" };
+    }
+    if ("shell" in m && m.shell !== void 0 && m.shell !== "tab" && m.shell !== "app") {
+      return { ok: false, reason: 'config.shell must be "tab" or "app"' };
+    }
+    if ("heartbeatTimeoutMs" in m && m.heartbeatTimeoutMs !== void 0 && typeof m.heartbeatTimeoutMs !== "number") {
+      return { ok: false, reason: "config.heartbeatTimeoutMs must be a number" };
+    }
+    if ("startupGraceMs" in m && m.startupGraceMs !== void 0 && typeof m.startupGraceMs !== "number") {
+      return { ok: false, reason: "config.startupGraceMs must be a number" };
+    }
+    return { ok: true };
+  }
+  const type = m.type;
+  if (typeof type !== "string") {
+    return { ok: false, reason: '"type" field must be a string' };
+  }
+  if (type === "result" || type === "error") {
+    if (typeof m.id !== "number") {
+      return { ok: false, reason: `"${type}" requires a numeric "id" field` };
+    }
+    if (type === "error" && typeof m.message !== "string") {
+      return { ok: false, reason: '"error" requires a string "message" field' };
+    }
+    return { ok: true };
+  }
+  switch (type) {
+    case "update":
+      if (!Object.hasOwn(m, "data")) {
+        return { ok: false, reason: '"update" requires a "data" field' };
+      }
+      return { ok: true };
+    case "view":
+      if (typeof m.source !== "string") {
+        return { ok: false, reason: '"view" requires a string "source" field' };
+      }
+      return { ok: true };
+    case "patch":
+      if (!Object.hasOwn(m, "data")) {
+        return { ok: false, reason: '"patch" requires a "data" field' };
+      }
+      if (typeof m.view !== "object" || m.view === null || typeof m.view.source !== "string") {
+        return { ok: false, reason: '"patch" requires a string "view.source" field' };
+      }
+      return { ok: true };
+    case "reopen":
+    case "close":
+    case "ping":
+      return { ok: true };
+    default:
+      return { ok: false, reason: `unknown message type: "${type}"` };
+  }
+}
 function parseInbound(line) {
   let parsed;
   try {
@@ -856,6 +1082,11 @@ async function runMount() {
         }
         process.exit(1);
       }
+      const configValidation = validateInboundShape(outcome2.msg, "config");
+      if (!configValidation.ok) {
+        emit2({ type: "error", message: configValidation.reason });
+        process.exit(1);
+      }
       configResolve(outcome2.msg);
       return;
     }
@@ -872,6 +1103,11 @@ async function runMount() {
       return;
     }
     const msg = outcome.msg;
+    const msgValidation = validateInboundShape(msg, "post-config");
+    if (!msgValidation.ok) {
+      emit2({ type: "error", message: msgValidation.reason });
+      return;
+    }
     if ("id" in msg && typeof msg.id === "number") {
       const p = pending.get(msg.id);
       if (!p) return;
@@ -921,7 +1157,9 @@ async function runMount() {
       void mountedView.close();
       return;
     }
-    emit2({ type: "error", message: `unknown message type: ${msg.type}` });
+    if (msg.type === "ping") {
+      return;
+    }
   });
   rl.on("close", () => {
     stdinClosed = true;