lavish-axi 0.1.11 → 0.1.13

package/README.md

@@ -96,9 +96,10 @@ pnpm link
 
 - **File-path identity** - Sessions are keyed by the canonical HTML file path, so agents do not need opaque IDs.
 - **Portable artifacts** - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, and feedback controls. Lavish does not inject any design system, so the saved HTML file renders identically whether you open it through `lavish-axi` or directly in a browser. Run `lavish-axi design` for a copy-pasteable CDN snippet to opt in to Tailwind CSS v4 + DaisyUI v5, or use any other design system (or none).
+- **Local assets** - Copy local images, CSS, fonts, and scripts next to the HTML artifact and reference them with relative paths from that directory; root-prefixed paths such as `/assets/logo.png` will not resolve through Lavish's artifact route.
 - **Live reload** - Lavish watches the HTML artifact file by default. To also reload on sibling asset changes, add `data-lavish-live-reload-root` to the root element or `<meta name="lavish-live-reload" content="root">`.
 - **Feedback controls** - Mark buttons, choices, and other interactive elements with `data-lavish-action` so Lavish does not annotate them, then call `window.lavish.queuePrompt()` or `window.lavish.sendQueuedPrompts()` from the control handler.
-- **Agent presence** - The browser shows when no agent is listening, still queues feedback for the next `lavish-axi poll`, and only blocks sending while the agent is working on delivered feedback.
+- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback for the next successful `lavish-axi poll` send even across reloads, and only blocks sending while the agent is working on delivered feedback.
 - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
 - **Local-first state** - Session state stays under `.lavish-axi/` in the workspace.
 
@@ -118,12 +119,12 @@ Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `diff`, `input`, `
 
 ### Flags
 
-| Command                  | Flag                  | Description                                                                              |
-| ------------------------ | --------------------- | ---------------------------------------------------------------------------------------- |
-| `lavish-axi <html-file>` | `--no-open`           | Ensure the server/session exists without opening another browser window.                 |
-| `lavish-axi poll`        | `--agent-reply "..."` | Show the agent's reply in the existing browser chat before polling again.                |
-| `lavish-axi poll`        | `--timeout-ms <ms>`   | Test/debug escape hatch only; agents should normally omit it.                            |
-| `lavish-axi server`      | `--verbose`           | Log session and watcher events to stderr; can also be enabled with `LAVISH_AXI_DEBUG=1`. |
+| Command                  | Flag                  | Description                                                                                                                                                                                                                         |
+| ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lavish-axi <html-file>` | `--no-open`           | Ensure the server/session exists without opening another browser window.                                                                                                                                                            |
+| `lavish-axi poll`        | `--agent-reply "..."` | Show the agent's reply in the existing browser chat before polling again.                                                                                                                                                           |
+| `lavish-axi poll`        | `--timeout-ms <ms>`   | Test/debug escape hatch only; agents should normally omit it.                                                                                                                                                                       |
+| `lavish-axi server`      | `--verbose`           | Log session and watcher events to stderr; can also be enabled with `LAVISH_AXI_DEBUG=1`. Detached server output is appended to `~/.lavish-axi/server.log` (or `LAVISH_AXI_STATE_DIR/server.log`) for startup and crash diagnostics. |
 
 ## Development
 

package/dist/chrome-client.js

@@ -3,6 +3,7 @@
 const sessionDataElement = document.getElementById("lavish-session");
 const sessionData = JSON.parse(sessionDataElement?.textContent || "{}");
 const key = String(sessionData.key || "");
+const queueStorageKey = "lavish-axi:queued:" + key;
 const initialChat = Array.isArray(sessionData.initialChat) ? sessionData.initialChat : [];
 
 const frame = /** @type {HTMLIFrameElement} */ (document.getElementById("artifact"));
@@ -16,11 +17,13 @@ const filePathInput = /** @type {HTMLInputElement} */ (document.getElementById("
 const copyPathButton = /** @type {HTMLButtonElement} */ (document.getElementById("copyPath"));
 const presenceBanner = /** @type {HTMLDivElement} */ (document.getElementById("presenceBanner"));
 
-const queued = [];
+const queued = loadQueuedPrompts();
 let annotation = true;
 let agentPresence = "waiting";
 let pendingSnapshot = "";
 let workingBubble = null;
+let submitQueuedPromise = null;
+let submitQueuedAgain = false;
 
 function escapeHtml(value) {
   return String(value).replace(
@@ -36,6 +39,27 @@ function escapeHtml(value) {
   );
 }
 
+function loadQueuedPrompts() {
+  try {
+    const parsed = JSON.parse(sessionStorage.getItem(queueStorageKey) || "[]");
+    return Array.isArray(parsed) ? parsed.filter((prompt) => prompt && typeof prompt === "object") : [];
+  } catch {
+    return [];
+  }
+}
+
+function persistQueuedPrompts() {
+  try {
+    if (queued.length) {
+      sessionStorage.setItem(queueStorageKey, JSON.stringify(queued));
+    } else {
+      sessionStorage.removeItem(queueStorageKey);
+    }
+  } catch {
+    // The in-memory queue still works if browser storage is unavailable.
+  }
+}
+
 function render() {
   annotationPills.innerHTML = queued
     .map(
@@ -105,6 +129,7 @@ function setAgentPresence(state) {
 function removeQueuedPrompt(index, event) {
   if (event) event.stopPropagation();
   queued.splice(index, 1);
+  persistQueuedPrompts();
   render();
 }
 
@@ -118,6 +143,7 @@ function sendQueued() {
   const text = chatInput.value.trim();
   if (text) {
     queued.push({ uid: "", prompt: text, selector: "", tag: "message", text: "Freeform message" });
+    persistQueuedPrompts();
     addChat("user", text);
     chatInput.value = "";
     render();
@@ -128,14 +154,40 @@ function sendQueued() {
 }
 
 async function submitQueued() {
-  const prompts = queued.splice(0, queued.length);
-  render();
-  if (agentPresence === "listening") setAgentPresence("working");
-  await fetch("/api/" + key + "/prompts", {
+  if (submitQueuedPromise) {
+    submitQueuedAgain = true;
+    return submitQueuedPromise;
+  }
+
+  let succeeded = false;
+  submitQueuedPromise = submitQueuedOnce();
+  try {
+    const result = await submitQueuedPromise;
+    succeeded = true;
+    return result;
+  } finally {
+    submitQueuedPromise = null;
+    const shouldSubmitAgain = submitQueuedAgain;
+    submitQueuedAgain = false;
+    if (succeeded && shouldSubmitAgain && queued.length) submitQueued();
+  }
+}
+
+async function submitQueuedOnce() {
+  const prompts = queued.slice();
+  const response = await fetch("/api/" + key + "/prompts", {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ prompts, domSnapshot: pendingSnapshot }),
   });
+  if (!response.ok) throw new Error("failed to submit queued prompts");
+  for (const prompt of prompts) {
+    const index = queued.indexOf(prompt);
+    if (index !== -1) queued.splice(index, 1);
+  }
+  persistQueuedPrompts();
+  render();
+  if (agentPresence === "listening") setAgentPresence("working");
 }
 
 async function endSession() {
@@ -185,6 +237,7 @@ window.addEventListener("message", (event) => {
   const msg = event.data || {};
   if (msg.type === "lavish:queuePrompt") {
     queued.push(msg.prompt);
+    persistQueuedPrompts();
     render();
   }
   if (msg.type === "lavish:snapshot") {

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 
 // src/cli.js
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
 import { access } from "node:fs/promises";
 import os2 from "node:os";
 import path4 from "node:path";
@@ -472,12 +472,16 @@ function createDesignOutput() {
 import { mkdir } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+var LOOPBACK_HOST = "127.0.0.1";
 function stateDir() {
   return process.env.LAVISH_AXI_STATE_DIR || path.join(os.homedir(), ".lavish-axi");
 }
 function stateFile() {
   return path.join(stateDir(), "state.json");
 }
+function serverLogFile() {
+  return path.join(stateDir(), "server.log");
+}
 async function ensureStateDir() {
   await mkdir(stateDir(), { recursive: true });
 }
@@ -1179,7 +1183,7 @@ var designAssetUrls = {
     type: "application/javascript"
   }
 };
-async function serve({ port, stateFile: stateFile2, version = "", debug = false, log = null }) {
+async function serve({ port, stateFile: stateFile2, version = "", debug = false, log = null, pollHeartbeatMs = 15e3 }) {
   const app = express();
   const store = new SessionStore(stateFile2);
   const events = new EventEmitter();
@@ -1191,6 +1195,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
   const writeLog = typeof log === "function" ? log : (line) => process.stderr.write(`${line}
 `);
   const logEvent = verbose ? (line) => writeLog(`[lavish] ${line}`) : null;
+  let publicPort = port;
   app.use(express.json({ limit: "2mb" }));
   app.get("/health", (req, res) => {
     res.json({ ok: true, app: "lavish-axi", version });
@@ -1207,7 +1212,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
     try {
       const file = await canonicalFile(req.body.file);
       const key = sessionKey(file);
-      const url = `http://localhost:${port}/session/${key}`;
+      const url = `http://${LOOPBACK_HOST}:${publicPort}/session/${key}`;
       const existing = await store.findByKey(key);
       const session = await store.upsertSession(file, url);
       if (existing?.status === "ended") {
@@ -1222,6 +1227,14 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
   });
   app.get("/api/poll", async (req, res, next) => {
     try {
+      let handleRespondError = function(error) {
+        if (streamHeartbeat) {
+          cleanup();
+          if (!res.writableEnded) res.destroy(error);
+          return;
+        }
+        next(error);
+      };
       const file = await canonicalFile(String(req.query.file || ""));
       const key = sessionKey(file);
       const timeoutMs = req.query.timeoutMs === void 0 ? null : Math.max(0, Math.min(Number(req.query.timeoutMs || 0), 2147483647));
@@ -1231,34 +1244,49 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
         res.json(immediate);
         return;
       }
+      const streamHeartbeat = timeoutMs === null;
+      let heartbeat = null;
+      if (streamHeartbeat) {
+        res.status(200).type("application/json");
+        res.write(" ");
+        heartbeat = setInterval(() => {
+          if (!res.writableEnded) res.write(" ");
+        }, pollHeartbeatMs);
+        heartbeat.unref?.();
+      }
       setPollActive(key, activePolls, deliveredFeedback, events, true);
-      const timer = timeoutMs === null ? null : setTimeout(() => respond().catch(next), timeoutMs);
+      const timer = timeoutMs === null ? null : setTimeout(() => respond().catch(handleRespondError), timeoutMs);
       let cleaned = false;
       let responding = false;
       const cleanup = () => {
         if (cleaned) return;
         cleaned = true;
         if (timer) clearTimeout(timer);
+        if (heartbeat) clearInterval(heartbeat);
         events.off("feedback", onFeedback);
         events.off("ended", onFeedback);
         setPollActive(key, activePolls, deliveredFeedback, events, false);
       };
       const respond = async () => {
-        if (responding || res.headersSent) return;
+        if (responding || res.writableEnded) return;
         responding = true;
         try {
           const result = await store.takeFeedback(key);
           if (result.status === "feedback") markFeedbackDelivered(key, activePolls, deliveredFeedback, events);
-          res.json(result);
+          if (streamHeartbeat) {
+            res.end(JSON.stringify(result));
+          } else {
+            res.json(result);
+          }
         } finally {
           cleanup();
         }
       };
       const onFeedback = (changedKey) => {
-        if (changedKey !== key || res.headersSent) {
+        if (changedKey !== key || res.writableEnded) {
           return;
         }
-        respond().catch(next);
+        respond().catch(handleRespondError);
       };
       events.on("feedback", onFeedback);
       events.on("ended", onFeedback);
@@ -1361,7 +1389,7 @@ async function serve({ port, stateFile: stateFile2, version = "", debug = false,
         res.status(403).send("Forbidden");
         return;
       }
-      res.sendFile(file);
+      res.sendFile(file, { dotfiles: "allow" });
     } catch (error) {
       next(error);
     }
@@ -1452,8 +1480,9 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
     res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
   });
   const httpServer = await new Promise((resolve) => {
-    const s = app.listen(port, "127.0.0.1", () => resolve(s));
+    const s = app.listen(port, LOOPBACK_HOST, () => resolve(s));
   });
+  publicPort = httpServer.address().port;
   let shuttingDown = false;
   function shutdown() {
     if (shuttingDown) return;
@@ -1793,7 +1822,7 @@ function normalizePagePath(path5) {
 // src/cli.js
 var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "server", "playbook", "design"]);
 var DESCRIPTION = "Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run `lavish-axi <html-file>` so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through `lavish-axi poll`.";
-var VERSION = "0.1.11";
+var VERSION = "0.1.13";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -1883,6 +1912,7 @@ function createHomeOutput({ bin, sessions, includeSessions = true }) {
     help: [
       "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session",
       "Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`",
+      "Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work",
       "Run `lavish-axi poll <html-file>` to wait for user feedback",
       "Run `lavish-axi end <html-file>` to end a session",
       "Run `lavish-axi playbook <playbook_id>` for focused artifact guidance",
@@ -1948,7 +1978,10 @@ async function pollCommand(args) {
   }
   const timeoutMs = flagValue(args, "--timeout-ms");
   const timeoutQuery = timeoutMs ? `&timeoutMs=${encodeURIComponent(timeoutMs)}` : "";
-  const response = await fetchJson(`${baseUrl}/api/poll?file=${encodeURIComponent(absolute)}${timeoutQuery}`);
+  const response = await fetchJson(`${baseUrl}/api/poll?file=${encodeURIComponent(absolute)}${timeoutQuery}`, {
+    retries: 3,
+    retryDelayMs: 500
+  });
   return createPollOutput({ file: absolute, response });
 }
 function createPollOutput({ file, response }) {
@@ -2017,7 +2050,7 @@ function isHtmlPath(file) {
 }
 async function ensureServer({ forceRestart = false } = {}) {
   const port = defaultPort();
-  const baseUrl = `http://localhost:${port}`;
+  const baseUrl = `http://${LOOPBACK_HOST}:${port}`;
   const existing = await fetchHealth(baseUrl);
   if (existing && !shouldRestartServer(VERSION, existing, forceRestart)) {
     return baseUrl;
@@ -2106,36 +2139,84 @@ function killProcessOnPort(port) {
 async function startServer(port) {
   await ensureStateDir();
   const entry = resolveServerEntry();
-  const child = spawn(process.execPath, [entry, "server", "--port", String(port)], {
-    detached: true,
-    stdio: "ignore",
-    env: { ...process.env, LAVISH_AXI_NO_OPEN: "1" }
-  });
-  child.unref();
+  let logFd = null;
+  try {
+    logFd = openSync(serverLogFile(), "a");
+  } catch {
+  }
+  try {
+    const child = spawn(process.execPath, [entry, "server", "--port", String(port)], createServerSpawnOptions(logFd));
+    child.unref();
+  } finally {
+    if (logFd !== null) closeSync(logFd);
+  }
 }
 function resolveServerEntry() {
   const binEntry = fileURLToPath(new URL("../bin/lavish-axi.js", import.meta.url));
   if (existsSync(binEntry)) return binEntry;
   return fileURLToPath(import.meta.url);
 }
-async function fetchJson(url) {
-  const response = await fetch(url);
+function createServerSpawnOptions(logFd = null) {
+  const stdio = (
+    /** @type {import("node:child_process").StdioOptions} */
+    logFd === null ? "ignore" : ["ignore", logFd, logFd]
+  );
+  return {
+    detached: true,
+    stdio,
+    env: { ...process.env, LAVISH_AXI_NO_OPEN: "1" }
+  };
+}
+async function fetchJson(url, { retries = 0, retryDelayMs = 250 } = {}) {
+  let response;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      response = await fetch(url);
+      break;
+    } catch (error) {
+      if (error instanceof AxiError) throw error;
+      if (attempt >= retries) throw serverConnectionError();
+      await delay(retryDelayMs);
+    }
+  }
+  if (!response) throw serverConnectionError();
   if (!response.ok) {
     throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
   }
-  return response.json();
+  try {
+    return await response.json();
+  } catch {
+    throw pollResponseInterruptedError();
+  }
 }
 async function postJson(url, body) {
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body)
-  });
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  } catch {
+    throw serverConnectionError();
+  }
   if (!response.ok) {
     throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
   }
   return response.json();
 }
+function serverConnectionError() {
+  return new AxiError("Lavish Editor server connection failed", "SERVER_ERROR", [
+    "Run `lavish-axi server --verbose` or inspect `~/.lavish-axi/server.log` (`LAVISH_AXI_STATE_DIR/server.log` when set) for server startup or crash diagnostics",
+    "Re-run the last `lavish-axi poll <html-file>` command after the server is healthy"
+  ]);
+}
+function pollResponseInterruptedError() {
+  return new AxiError("Lavish Editor poll response was interrupted", "SERVER_ERROR", [
+    "Run `lavish-axi server --verbose` or inspect `~/.lavish-axi/server.log` (`LAVISH_AXI_STATE_DIR/server.log` when set) for server startup or crash diagnostics",
+    "Re-run the last `lavish-axi poll <html-file>` command after the server is healthy"
+  ]);
+}
 function flagValue(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) {
@@ -2192,7 +2273,7 @@ Show a copy-pasteable CDN snippet for Tailwind CSS browser runtime v4 + DaisyUI
 `,
   server: `Usage: lavish-axi server [--port 4387] [--verbose]
 
-Run the local Lavish Editor server. Pass --verbose (or set LAVISH_AXI_DEBUG=1) to log session and watcher events to stderr.
+Run the local Lavish Editor server. Pass --verbose (or set LAVISH_AXI_DEBUG=1) to log session and watcher events to stderr. Detached server output is appended to ~/.lavish-axi/server.log, or LAVISH_AXI_STATE_DIR/server.log when set, for startup and crash diagnostics.
 `
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",