lavish-axi 0.1.10 → 0.1.12

package/README.md

@@ -95,9 +95,10 @@ pnpm link
 ```
 
 - **File-path identity** - Sessions are keyed by the canonical HTML file path, so agents do not need opaque IDs.
-- **Sandboxed artifact** - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, and feedback controls, plus Tailwind CSS v4 and DaisyUI v5 design assets unless the HTML includes `<meta name="lavish-design" content="off">`.
+- **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).
+- **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.
 
@@ -110,17 +111,19 @@ pnpm link
 | `lavish-axi poll <html-file>` | Long-poll until the user sends feedback or ends the session. |
 | `lavish-axi end <html-file>`  | End a session.                                               |
 | `lavish-axi playbook [id]`    | List focused artifact guidance or show one playbook.         |
-| `lavish-axi design`           | Show the injected Tailwind CSS and DaisyUI design reference. |
+| `lavish-axi design`           | Show CDN snippet + DaisyUI component reference (opt-in).     |
+| `lavish-axi server`           | Run the local Lavish Editor server.                          |
 
 Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `diff`, `input`, `slides`.
 
 ### 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.             |
+| 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";
@@ -10,7 +10,17 @@ import { fileURLToPath } from "node:url";
 import { AxiError, runAxiCli } from "axi-sdk-js";
 
 // src/design-reference.js
-var DESIGN_SYSTEM_HINT = 'Lavish auto-injects Tailwind CSS browser runtime v4, DaisyUI v5, and DaisyUI themes into artifacts. Do not add these libraries separately. Set <html data-theme="luxury"> or another DaisyUI theme as appropriate, then use DaisyUI/Tailwind classes directly. Prefer using DaisyUI/Tailwind for styling to avoid having to spend tokens on writing a custom stylesheet, but in cases where you need precise control on the artifact, you can opt out of the auto-injected styles by adding <meta name="lavish-design" content="off">. Run `lavish-axi design` for technical reference.';
+var TAILWIND_BROWSER_VERSION = "4.2.4";
+var DAISYUI_VERSION = "5.5.19";
+var DESIGN_CDN_URLS = {
+  tailwind: `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@${TAILWIND_BROWSER_VERSION}/dist/index.global.js`,
+  daisyui: `https://cdn.jsdelivr.net/npm/daisyui@${DAISYUI_VERSION}/daisyui.css`,
+  daisyuiThemes: `https://cdn.jsdelivr.net/npm/daisyui@${DAISYUI_VERSION}/themes.css`
+};
+var DESIGN_CDN_SNIPPET = `<link rel="stylesheet" href="${DESIGN_CDN_URLS.daisyui}">
+<link rel="stylesheet" href="${DESIGN_CDN_URLS.daisyuiThemes}">
+<script src="${DESIGN_CDN_URLS.tailwind}"></script>`;
+var DESIGN_SYSTEM_HINT = "Lavish does not auto-inject any design system - artifacts stay portable so they render identically when opened directly without lavish-axi running. Tailwind CSS browser runtime v4 and DaisyUI v5 are available via CDN; run `lavish-axi design` for a copy-pasteable CDN snippet plus component reference. Prefer that CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. If the user asks for any other design system or plain HTML, follow that request.";
 var DAISYUI_THEMES = [
   "light",
   "dark",
@@ -51,11 +61,13 @@ var DAISYUI_THEMES = [
 function createDesignOutput() {
   return {
     design: {
-      summary: "Lavish artifacts already have Tailwind CSS browser runtime v4, DaisyUI v5, and DaisyUI themes available.",
-      rule: "Do not add Tailwind or DaisyUI script/link tags yourself.",
-      opt_out: 'Add `<meta name="lavish-design" content="off">` to disable injection for exact-fidelity artifacts.',
+      summary: "Lavish does not auto-inject any design system. Artifacts stay portable HTML. Paste the CDN snippet below into your `<head>` to use Tailwind CSS browser runtime v4 + DaisyUI v5 + themes. Prefer this CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user.",
+      cdn_snippet: DESIGN_CDN_SNIPPET,
+      cdn_urls: DESIGN_CDN_URLS,
+      versions: { tailwind: TAILWIND_BROWSER_VERSION, daisyui: DAISYUI_VERSION },
       latest_docs: "https://daisyui.com/components/",
-      docs_note: "Use this command for common syntax. Read the latest DaisyUI docs for full details when using advanced or unfamiliar components."
+      docs_note: "Use this command for common syntax. Read the latest DaisyUI docs for full details when using advanced or unfamiliar components.",
+      other_design_systems: "If the user asks for a different design system (Bootstrap, custom CSS, plain HTML, etc.), use that instead - Lavish does not require DaisyUI."
     },
     theme_usage: [
       'Set the page theme with `<html data-theme="luxury">`.',
@@ -460,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 });
 }
@@ -992,25 +1008,11 @@ function createArtifactSdk() {
 // src/html-transform.js
 function injectLavishSdk(html, key) {
   const script = `<script src="/sdk.js?key=${encodeURIComponent(key)}"></script>`;
-  const design = shouldInjectDesign(html) ? '<link rel="stylesheet" href="/design/daisyui.css" data-lavish-design><script src="/design/tailwindcss-browser.js" data-lavish-design></script><link rel="stylesheet" href="/design/daisyui-themes.css" data-lavish-design>' : "";
-  const withDesign = injectDesignAssets(html, design);
-  if (/<\/body\s*>/i.test(withDesign)) {
-    return withDesign.replace(/<\/body\s*>/i, `${script}</body>`);
-  }
-  return `${withDesign}
-${script}`;
-}
-function shouldInjectDesign(html) {
-  if (/data-lavish-design/i.test(html)) return false;
-  return !/<meta\b(?=[^>]*name=["']lavish-design["'])(?=[^>]*content=["']off["'])[^>]*>/i.test(html);
-}
-function injectDesignAssets(html, design) {
-  if (!design) return html;
-  if (/<head\b[^>]*>/i.test(html)) {
-    return html.replace(/<head\b[^>]*>/i, (match) => `${match}${design}`);
+  if (/<\/body\s*>/i.test(html)) {
+    return html.replace(/<\/body\s*>/i, `${script}</body>`);
   }
   return `${html}
-${design}`;
+${script}`;
 }
 
 // src/session-store.js
@@ -1181,7 +1183,7 @@ var designAssetUrls = {
     type: "application/javascript"
   }
 };
-async function serve({ port, stateFile: stateFile2, version = "" }) {
+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();
@@ -1189,6 +1191,11 @@ async function serve({ port, stateFile: stateFile2, version = "" }) {
   const activePolls = /* @__PURE__ */ new Map();
   const deliveredFeedback = /* @__PURE__ */ new Set();
   const sseClients = /* @__PURE__ */ new Set();
+  const verbose = debug || process.env.LAVISH_AXI_DEBUG === "1";
+  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 });
@@ -1205,13 +1212,14 @@ async function serve({ port, stateFile: stateFile2, version = "" }) {
     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") {
         clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
       }
-      watchSession(session, watchers, events);
+      logEvent?.(`session opened key=${key} file=${file}`);
+      await watchSession(session, watchers, events, logEvent);
       res.json({ key, file, url, status: "opened" });
     } catch (error) {
       next(error);
@@ -1219,6 +1227,14 @@ async function serve({ port, stateFile: stateFile2, version = "" }) {
   });
   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));
@@ -1228,34 +1244,49 @@ async function serve({ port, stateFile: stateFile2, version = "" }) {
         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);
@@ -1320,7 +1351,7 @@ async function serve({ port, stateFile: stateFile2, version = "" }) {
         res.status(404).send("Session not found");
         return;
       }
-      watchSession(session, watchers, events);
+      await watchSession(session, watchers, events, logEvent);
       res.type("html").send(createChromeHtml(session));
     } catch (error) {
       next(error);
@@ -1449,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;
@@ -1498,23 +1530,55 @@ function resolveArtifactAsset(root, assetPath) {
   }
   return file;
 }
-function watchSession(session, watchers, events) {
+async function watchSession(session, watchers, events, logEvent) {
   if (watchers.has(session.key)) {
     return;
   }
-  const root = path3.dirname(session.file);
-  const watcher = chokidar.watch(root, {
-    ignored: /(^|[/\\])(\.git|node_modules|dist|build|\.lavish-axi)([/\\]|$)/,
-    ignoreInitial: true,
-    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 }
-  });
+  const target = await resolveWatchTarget(session);
+  if (watchers.has(session.key)) {
+    return;
+  }
+  logEvent?.(`watch session=${session.key} scope=${target.scope} path=${target.path}`);
+  const watcher = chokidar.watch(target.path, target.options);
   let timer = null;
-  watcher.on("all", () => {
+  watcher.on("all", (event, file) => {
+    logEvent?.(`watch event=${event} session=${session.key} file=${file ?? ""}`);
     clearTimeout(timer);
     timer = setTimeout(() => events.emit("reload", session.key), 100);
   });
+  watcher.on("error", (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    logEvent?.(`watch error session=${session.key} message=${message}`);
+  });
   watchers.set(session.key, watcher);
 }
+async function resolveWatchTarget(session) {
+  const baseOptions = {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 }
+  };
+  try {
+    const html = await readFile2(session.file, "utf8");
+    if (hasLiveReloadRootOptIn(html)) {
+      return {
+        path: path3.dirname(session.file),
+        scope: "directory",
+        options: {
+          ...baseOptions,
+          ignored: /(^|[/\\])(\.git|node_modules|dist|build|\.lavish-axi)([/\\]|$)/
+        }
+      };
+    }
+  } catch {
+  }
+  return { path: session.file, scope: "file", options: baseOptions };
+}
+function hasLiveReloadRootOptIn(html) {
+  if (typeof html !== "string") return false;
+  const searchableHtml = html.replace(/<!--[\s\S]*?-->/g, "");
+  if (/<html\b[^>]*\sdata-lavish-live-reload-root(?:[\s=>/]|$)[^>]*>/i.test(searchableHtml)) return true;
+  return /<meta\b(?=[^>]*name=["']lavish-live-reload["'])(?=[^>]*content=["']root["'])[^>]*>/i.test(searchableHtml);
+}
 function setPollActive(key, activePolls, deliveredFeedback, events, active) {
   const previousPresence = computePresence(key, activePolls, deliveredFeedback);
   const count = activePolls.get(key) || 0;
@@ -1758,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.10";
+var VERSION = "0.1.12";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -1913,7 +1977,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 }) {
@@ -1956,7 +2023,8 @@ async function designCommand() {
 }
 async function serverCommand(args) {
   const port = Number(flagValue(args, "--port") || defaultPort());
-  const server = await serve({ port, stateFile: stateFile(), version: VERSION });
+  const debug = args.includes("--verbose") || process.env.LAVISH_AXI_DEBUG === "1";
+  const server = await serve({ port, stateFile: stateFile(), version: VERSION, debug });
   await server.done;
   return "";
 }
@@ -1981,7 +2049,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;
@@ -2070,36 +2138,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) {
@@ -2152,11 +2268,11 @@ Examples:
 `,
   design: `Usage: lavish-axi design
 
-Show technical reference for the Tailwind CSS browser runtime v4, DaisyUI v5 components, and DaisyUI themes that Lavish auto-injects into artifacts. Do not add these libraries separately.
+Show a copy-pasteable CDN snippet for Tailwind CSS browser runtime v4 + DaisyUI v5 + themes, plus technical reference for DaisyUI components. Lavish artifacts stay portable HTML. Prefer the CDN snippet over hand-writing styles unless explicitly instructed otherwise by the user. If the user asks for another design system or plain HTML, follow that request.
 `,
-  server: `Usage: lavish-axi server [--port 4387]
+  server: `Usage: lavish-axi server [--port 4387] [--verbose]
 
-Run the local Lavish Editor server.
+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.10",
+  "version": "0.1.12",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",