lavish-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kun Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+<h1 align="center">lavish-axi</h1>
+<p align="center">
+  <a href="https://github.com/kunchenguid/lavish/actions/workflows/ci.yml"
+    ><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/lavish/ci.yml?style=flat-square&label=ci"
+  /></a>
+  <a href="https://github.com/kunchenguid/lavish/actions/workflows/release-please.yml"
+    ><img alt="Release" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/lavish/release-please.yml?style=flat-square&label=release"
+  /></a>
+  <a href="https://www.npmjs.com/package/lavish-axi"
+    ><img alt="npm" src="https://img.shields.io/npm/v/lavish-axi?style=flat-square"
+  /></a>
+  <a href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
+    ><img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
+  /></a>
+  <a href="https://x.com/kunchenguid"
+    ><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
+  /></a>
+  <a href="https://discord.gg/Wsy2NpnZDu"
+    ><img alt="Discord" src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
+  /></a>
+</p>
+
+<h3 align="center">For when a rich editor is not rich enough.</h3>
+
+HTML is the new markdown. Lavish is the new editor for your HTML artifacts.
+
+Agents are good at producing rich HTML artifacts, but the human-agent collaboration loop on such artifacts is lacking and falls back into screenshots and long responses for “tell me what to change.”
+That loses the thing HTML is best at: interactivity.
+
+Lavish Editor opens an agent-generated HTML file in a local browser, lets you pinpoint elements and send feedback.
+
+- **Browser-native review** - Serve local HTML artifacts with relative JS/CSS/assets intact.
+- **Precise feedback** - Click elements, queue annotation & prompts , and send them back to the agent.
+- **Agent-ergonomic interface** - Follows [AXI principles](https://axi.md), use TOON output, long polling, and contextual disclosure that keep autonomous agents on track.
+
+## Quick Start
+
+Tell your agent:
+
+```sh
+Use `npx lavish-axi` to write a technical plan for what we discussed.
+```
+
+## Install
+
+**npm**
+
+```sh
+npm install -g lavish-axi
+```
+
+**From source**
+
+```sh
+git clone https://github.com/kunchenguid/lavish.git
+cd lavish
+npm ci
+npm run build
+npm link
+```
+
+## How It Works
+
+```
+┌───────────────┐
+│ Agent writes  │
+│ artifact.html │
+└───────┬───────┘
+        ▼
+┌────────────────────────┐
+│ lavish-axi <file_path> │
+│ opens local browser UI │
+└───────┬────────────────┘
+        ▼
+┌────────────────────────┐
+│ Human annotates or     │
+│ sends chat feedback    │
+└───────┬────────────────┘
+        ▼
+┌────────────────────────┐
+│ lavish-axi poll waits  │
+│ and returns prompts    │
+└────────────────────────┘
+```
+
+- **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 and snapshots.
+- **Local-first state** - Session state stays under `.lavish-axi/` in the workspace.
+
+## CLI Reference
+
+| Command                       | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| `lavish-axi`                  | Show current sessions and usage guidance.                    |
+| `lavish-axi <html-file>`      | Open or resume a Lavish Editor session.                      |
+| `lavish-axi poll <html-file>` | Long-poll until the user sends feedback or ends the session. |
+| `lavish-axi end <html-file>`  | End a session.                                               |
+
+### 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.             |
+
+## Development
+
+```sh
+npm run build          # Bundle the publishable CLI
+npm test               # Run node:test tests
+npm run lint           # Run ESLint
+npm run format:check   # Check Prettier formatting
+npm run typecheck      # Run TypeScript checkJs validation
+```

package/dist/cli.mjs

@@ -0,0 +1,1007 @@
+#!/usr/bin/env node
+
+// src/cli.js
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import os2 from "node:os";
+import path4 from "node:path";
+import { fileURLToPath } from "node:url";
+import { AxiError, runAxiCli } from "axi-sdk-js";
+
+// src/paths.js
+import { mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function stateDir() {
+  return process.env.LAVISH_AXI_STATE_DIR || path.join(os.homedir(), ".lavish-axi");
+}
+function stateFile() {
+  return path.join(stateDir(), "state.json");
+}
+async function ensureStateDir() {
+  await mkdir(stateDir(), { recursive: true });
+}
+function defaultPort() {
+  return Number(process.env.LAVISH_AXI_PORT || 4387);
+}
+
+// src/server.js
+import { EventEmitter } from "node:events";
+import { readFile as readFile2 } from "node:fs/promises";
+import path3 from "node:path";
+import chokidar from "chokidar";
+import express from "express";
+
+// src/html-transform.js
+function injectLavishSdk(html, key) {
+  const script = `<script src="/sdk.js?key=${encodeURIComponent(key)}"></script>`;
+  if (/<\/body\s*>/i.test(html)) {
+    return html.replace(/<\/body\s*>/i, `${script}</body>`);
+  }
+  return `${html}
+${script}`;
+}
+
+// src/session-store.js
+import crypto from "node:crypto";
+import { readFile, realpath, writeFile } from "node:fs/promises";
+import path2 from "node:path";
+var SessionStore = class {
+  constructor(file) {
+    this.file = file;
+  }
+  async listSessions() {
+    const state = await this.readState();
+    return Object.values(state.sessions).sort((a, b) => a.file.localeCompare(b.file));
+  }
+  async findByFile(file) {
+    const absolute = await canonicalFile(file);
+    const state = await this.readState();
+    return state.sessions[sessionKey(absolute)] || null;
+  }
+  async findByKey(key) {
+    const state = await this.readState();
+    return state.sessions[key] || null;
+  }
+  async upsertSession(file, url) {
+    const absolute = await canonicalFile(file);
+    const key = sessionKey(absolute);
+    const state = await this.readState();
+    const existing = state.sessions[key] || {};
+    const session = {
+      key,
+      file: absolute,
+      url,
+      status: existing.status === "ended" ? "open" : existing.status || "open",
+      pending_prompts: existing.pending_prompts || 0,
+      prompts: existing.prompts || [],
+      dom_snapshot: existing.dom_snapshot || "",
+      chat: existing.chat || [],
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    state.sessions[key] = session;
+    await this.writeState(state);
+    return session;
+  }
+  async queuePrompts(key, payload) {
+    const state = await this.readState();
+    const session = state.sessions[key];
+    if (!session) {
+      return null;
+    }
+    const prompts = Array.isArray(payload.prompts) ? payload.prompts : [];
+    const normalizedPrompts = prompts.map(normalizePrompt);
+    const userMessages = normalizedPrompts.filter((prompt) => prompt.tag === "message" && prompt.prompt).map((prompt) => ({ role: "user", text: prompt.prompt, at: (/* @__PURE__ */ new Date()).toISOString() }));
+    session.prompts = [...session.prompts || [], ...normalizedPrompts];
+    session.chat = [...session.chat || [], ...userMessages];
+    session.pending_prompts = session.prompts.length;
+    session.dom_snapshot = String(payload.domSnapshot || payload.dom_snapshot || "");
+    session.status = "feedback";
+    session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    await this.writeState(state);
+    return session;
+  }
+  async takeFeedback(key) {
+    const state = await this.readState();
+    const session = state.sessions[key];
+    if (!session) {
+      return { status: "missing" };
+    }
+    if (session.status === "ended") {
+      return { status: "ended" };
+    }
+    const prompts = session.prompts || [];
+    if (prompts.length === 0) {
+      return { status: "waiting" };
+    }
+    const result = {
+      status: "feedback",
+      dom_snapshot: session.dom_snapshot || "",
+      prompts
+    };
+    session.prompts = [];
+    session.pending_prompts = 0;
+    session.dom_snapshot = "";
+    session.status = "open";
+    session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    await this.writeState(state);
+    return result;
+  }
+  async endSession(key) {
+    const state = await this.readState();
+    const session = state.sessions[key];
+    if (!session) {
+      return null;
+    }
+    session.status = "ended";
+    session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    await this.writeState(state);
+    return session;
+  }
+  async addAgentReply(key, text) {
+    const state = await this.readState();
+    const session = state.sessions[key];
+    if (!session) {
+      return null;
+    }
+    session.chat = [...session.chat || [], { role: "agent", text: String(text || ""), at: (/* @__PURE__ */ new Date()).toISOString() }];
+    session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    await this.writeState(state);
+    return session;
+  }
+  async readState() {
+    try {
+      const raw = await readFile(this.file, "utf8");
+      const parsed = JSON.parse(raw);
+      return { sessions: parsed.sessions || {} };
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        return { sessions: {} };
+      }
+      throw error;
+    }
+  }
+  async writeState(state) {
+    await writeFile(this.file, `${JSON.stringify(state, null, 2)}
+`);
+  }
+};
+async function canonicalFile(file) {
+  const absolute = path2.resolve(file);
+  return realpath(absolute);
+}
+function sessionKey(file) {
+  return crypto.createHash("sha256").update(file).digest("hex").slice(0, 16);
+}
+function normalizePrompt(prompt) {
+  return {
+    uid: String(prompt.uid || ""),
+    prompt: String(prompt.prompt || ""),
+    selector: String(prompt.selector || ""),
+    tag: String(prompt.tag || ""),
+    text: String(prompt.text || "")
+  };
+}
+
+// src/server.js
+async function serve({ port, stateFile: stateFile2 }) {
+  const app = express();
+  const store = new SessionStore(stateFile2);
+  const events = new EventEmitter();
+  const watchers = /* @__PURE__ */ new Map();
+  const activePolls = /* @__PURE__ */ new Map();
+  app.use(express.json({ limit: "2mb" }));
+  app.get("/health", (req, res) => {
+    res.json({ ok: true });
+  });
+  app.post("/api/sessions", async (req, res, next) => {
+    try {
+      const file = await canonicalFile(req.body.file);
+      const key = sessionKey(file);
+      const url = `http://localhost:${port}/session/${key}`;
+      const session = await store.upsertSession(file, url);
+      watchSession(session, watchers, events);
+      res.json({ key, file, url, status: "opened" });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get("/api/poll", async (req, res, next) => {
+    try {
+      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));
+      const immediate = await store.takeFeedback(key);
+      if (immediate.status !== "waiting") {
+        res.json(immediate);
+        return;
+      }
+      setPollActive(key, activePolls, events, true);
+      const timer = timeoutMs === null ? null : setTimeout(async () => {
+        cleanup();
+        res.json(await store.takeFeedback(key));
+      }, timeoutMs);
+      const onFeedback = async (changedKey) => {
+        if (changedKey !== key || res.headersSent) {
+          return;
+        }
+        cleanup();
+        res.json(await store.takeFeedback(key));
+      };
+      let cleaned = false;
+      const cleanup = () => {
+        if (cleaned) return;
+        cleaned = true;
+        if (timer) clearTimeout(timer);
+        events.off("feedback", onFeedback);
+        events.off("ended", onFeedback);
+        setPollActive(key, activePolls, events, false);
+      };
+      events.on("feedback", onFeedback);
+      events.on("ended", onFeedback);
+      req.on("close", cleanup);
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.post("/api/:key/prompts", async (req, res, next) => {
+    try {
+      const session = await store.queuePrompts(req.params.key, req.body || {});
+      if (!session) {
+        res.status(404).json({ error: "session not found" });
+        return;
+      }
+      events.emit("feedback", req.params.key);
+      res.json({ status: "queued", pending_prompts: session.pending_prompts });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.post("/api/:key/end", async (req, res, next) => {
+    try {
+      await store.endSession(req.params.key);
+      events.emit("ended", req.params.key);
+      res.json({ status: "ended" });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.post("/api/:key/agent-reply", async (req, res, next) => {
+    try {
+      const text = String(req.body?.text || "");
+      const session = await store.addAgentReply(req.params.key, text);
+      if (!session) {
+        res.status(404).json({ error: "session not found" });
+        return;
+      }
+      events.emit("agent-reply", req.params.key, text);
+      res.json({ status: "sent" });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.post("/api/end", async (req, res, next) => {
+    try {
+      const file = await canonicalFile(req.body.file);
+      const key = sessionKey(file);
+      await store.endSession(key);
+      events.emit("ended", key);
+      res.json({ status: "ended" });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get("/session/:key", async (req, res, next) => {
+    try {
+      const session = await store.findByKey(req.params.key);
+      if (!session) {
+        res.status(404).send("Session not found");
+        return;
+      }
+      watchSession(session, watchers, events);
+      res.type("html").send(createChromeHtml(session));
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get("/artifact/:key", (req, res) => {
+    res.redirect(`/artifact/${req.params.key}/index.html`);
+  });
+  app.get(/^\/artifact\/([^/]+)\/index\.html$/, async (req, res, next) => {
+    try {
+      const key = req.params[0];
+      const session = await store.findByKey(key);
+      if (!session) {
+        res.status(404).send("Session not found");
+        return;
+      }
+      const html = await readFile2(session.file, "utf8");
+      res.type("html").send(injectLavishSdk(html, key));
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get(/^\/artifact\/([^/]+)\/(.+)$/, async (req, res, next) => {
+    try {
+      const key = req.params[0];
+      const assetPath = req.params[1];
+      const session = await store.findByKey(key);
+      if (!session) {
+        res.status(404).send("Session not found");
+        return;
+      }
+      const root = path3.dirname(session.file);
+      const file = resolveArtifactAsset(root, assetPath);
+      if (!file) {
+        res.status(403).send("Forbidden");
+        return;
+      }
+      res.sendFile(file);
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get("/events/:key", async (req, res, next) => {
+    try {
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive"
+      });
+      const session = await store.findByKey(req.params.key);
+      const sendReload = (key) => {
+        if (key === req.params.key) {
+          res.write("event: reload\ndata: {}\n\n");
+        }
+      };
+      const sendAgentReply = (key, text) => {
+        if (key === req.params.key) {
+          res.write(`event: agent-reply
+data: ${JSON.stringify({ text })}
+
+`);
+        }
+      };
+      const sendWorking = (key, working) => {
+        if (key === req.params.key) {
+          res.write(`event: agent-working
+data: ${JSON.stringify({ working })}
+
+`);
+        }
+      };
+      res.write(`event: chat-sync
+data: ${JSON.stringify({ chat: session?.chat || [] })}
+
+`);
+      res.write(`event: agent-working
+data: ${JSON.stringify({ working: !activePolls.has(req.params.key) })}
+
+`);
+      events.on("reload", sendReload);
+      events.on("agent-reply", sendAgentReply);
+      events.on("agent-working", sendWorking);
+      req.on("close", () => {
+        events.off("reload", sendReload);
+        events.off("agent-reply", sendAgentReply);
+        events.off("agent-working", sendWorking);
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+  app.get("/sdk.js", (req, res) => {
+    res.type("application/javascript").send(createSdkJs(String(req.query.key || "")));
+  });
+  app.use((error, req, res, _next) => {
+    res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
+  });
+  await new Promise((resolve) => {
+    app.listen(port, "127.0.0.1", resolve);
+  });
+}
+function resolveArtifactAsset(root, assetPath) {
+  const file = path3.resolve(root, assetPath);
+  const relative = path3.relative(root, file);
+  if (relative.startsWith("..") || path3.isAbsolute(relative)) {
+    return null;
+  }
+  return file;
+}
+function watchSession(session, watchers, events) {
+  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 }
+  });
+  let timer = null;
+  watcher.on("all", () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => events.emit("reload", session.key), 100);
+  });
+  watchers.set(session.key, watcher);
+}
+function setPollActive(key, activePolls, events, active) {
+  const count = activePolls.get(key) || 0;
+  const nextCount = active ? count + 1 : Math.max(0, count - 1);
+  if (nextCount === count) return;
+  if (nextCount === 0) {
+    activePolls.delete(key);
+  } else {
+    activePolls.set(key, nextCount);
+  }
+  if (count > 0 === nextCount > 0) return;
+  events.emit("agent-working", key, nextCount === 0);
+}
+function createChromeHtml(session) {
+  const initialChat = JSON.stringify(session.chat || []);
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Lavish Editor</title>
+<style>
+body{margin:0;background:#0f1115;color:#f7f3ea;font:14px/1.4 ui-sans-serif,system-ui,sans-serif;overflow:hidden}
+.bar{height:56px;display:flex;align-items:center;gap:12px;padding:0 16px;background:#171a21;border-bottom:1px solid #2a2f3a;box-sizing:border-box}
+.brand{font-weight:750;letter-spacing:.02em}.file{color:#b9c0cf;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1}
+button{border:0;border-radius:10px;padding:9px 12px;background:#f4c95d;color:#17130a;font-weight:700;cursor:pointer}button:disabled{opacity:.55;cursor:not-allowed}
+button.secondary{background:#2a2f3a;color:#f7f3ea}button.danger{background:#f06464;color:white}
+.layout{height:calc(100vh - 56px);min-height:0;display:grid;grid-template-columns:1fr 360px}.frame{background:white}.panel{border-left:1px solid #2a2f3a;background:#11141a;display:flex;flex-direction:column;min-width:0;min-height:0}
+.panel h2{font-size:15px;margin:16px 16px 8px}.chat{flex:1;min-height:0;overflow:auto;padding:0 16px 12px;display:flex;flex-direction:column;gap:10px}.bubble{border-radius:14px;padding:10px 12px;background:#1c212b;border:1px solid #303745}.bubble.user{background:#25230f;border-color:#5d4d1b}.bubble.agent{background:#172419;border-color:#315f3a}.bubble.agent-working{display:flex;align-items:center;gap:8px;color:#d8deea}.spinner{width:14px;height:14px;border-radius:999px;border:2px solid #315f3a;border-top-color:#8fe39e;animation:spin .8s linear infinite}.bubble small{display:block;color:#aeb6c6;margin-bottom:4px}@keyframes spin{to{transform:rotate(360deg)}}.composer{display:grid;gap:8px;padding:12px 16px;border-top:1px solid #2a2f3a;min-width:0;flex-shrink:0;box-sizing:border-box}.annotation-pills{display:flex;flex-wrap:wrap;gap:6px;min-width:0}.pill-wrap{position:relative;max-width:100%}.pill{display:flex;align-items:center;gap:6px;max-width:100%;border:1px solid #3c4557;border-radius:999px;background:#1c212b;color:#d8deea;padding:5px 7px 5px 9px;font-size:12px;font-weight:750}.pill-preview{display:block;max-width:220px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis}.pill-close{width:18px;height:18px;border:0;border-radius:999px;padding:0;background:#303745;color:#d8deea;line-height:18px;font-size:14px}.pill-tooltip{display:none;position:absolute;z-index:5;left:0;bottom:calc(100% + 8px);width:min(320px,80vw);border:1px solid #3c4557;border-radius:12px;background:#171a21;color:#d8deea;padding:10px;font-size:12px;font-weight:500;box-shadow:0 16px 44px rgba(0,0,0,.35)}.tooltip-label{color:#8c96aa;font-size:10px;font-weight:900;letter-spacing:.08em;text-transform:uppercase;margin:0 0 4px}.pill-tooltip-target{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:#0f1115;border:1px solid #303745;border-radius:8px;padding:6px;margin-bottom:8px;overflow-wrap:anywhere}.pill-tooltip-prompt{white-space:pre-wrap;overflow-wrap:anywhere}.pill-wrap:hover .pill-tooltip{display:block}.composer textarea{width:100%;max-width:100%;min-width:0;min-height:82px;resize:vertical;border-radius:12px;border:1px solid #303745;background:#0f1115;color:#f7f3ea;padding:10px;font:inherit;box-sizing:border-box}.actions{display:flex;gap:8px}
+iframe{width:100%;height:100%;border:0;background:white}
+</style>
+</head>
+<body>
+<div class="bar"><div class="brand">Lavish Editor</div><div class="file">${escapeHtml(session.file)}</div><button id="annotation">Annotation: On</button><button class="danger" id="end">End Session</button></div>
+<div class="layout"><div class="frame"><iframe id="artifact" sandbox="allow-scripts allow-forms allow-popups allow-downloads" src="/artifact/${session.key}/index.html"></iframe></div><aside class="panel"><h2>Conversation</h2><div class="chat" id="chatLog"></div><div class="composer"><div class="annotation-pills" id="annotationPills"></div><textarea id="chatInput" placeholder="Write a message for the agent..."></textarea><div class="actions"><button id="send">Send to Agent</button></div></div></aside></div>
+<script>
+const key=${JSON.stringify(session.key)};
+const initialChat=${initialChat};
+const frame=document.getElementById('artifact');
+const annotationPills=document.getElementById('annotationPills');
+const chatLog=document.getElementById('chatLog');
+const chatInput=document.getElementById('chatInput');
+const sendButton=document.getElementById('send');
+const queued=[];
+let annotation=true;
+let agentPolling=false;
+let pendingSnapshot='';
+let workingBubble=null;
+function render(){annotationPills.innerHTML=queued.map((p,i)=>'<div class="pill-wrap"><div class="pill"><span class="pill-preview">'+escapeHtml(p.prompt)+'</span><button class="pill-close" type="button" aria-label="Remove queued prompt" onclick="removeQueuedPrompt('+i+',event)">\xD7</button></div><div class="pill-tooltip">'+(p.selector?'<div class="tooltip-label">Target</div><div class="pill-tooltip-target">'+escapeHtml(p.selector)+'</div>':'')+'<div class="tooltip-label">Prompt</div><div class="pill-tooltip-prompt">'+escapeHtml(p.prompt)+'</div></div></div>').join('')}
+function escapeHtml(s){return String(s).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]))}
+function addChat(role,text){if(!text)return;const el=document.createElement('div');el.className='bubble '+role;el.innerHTML='<small>'+(role==='agent'?'Agent':'You')+'</small><div>'+escapeHtml(text)+'</div>';chatLog.appendChild(el);chatLog.scrollTop=chatLog.scrollHeight}
+function syncChat(chat){for(const el of [...chatLog.querySelectorAll('.bubble.user,.bubble.agent:not(.agent-working)')])el.remove();for(const item of chat)addChat(item.role,item.text);if(workingBubble)chatLog.appendChild(workingBubble);chatLog.scrollTop=chatLog.scrollHeight}
+function setAgentPolling(active){agentPolling=!!active;sendButton.disabled=!agentPolling;if(agentPolling){if(workingBubble)workingBubble.remove();workingBubble=null;return}if(!workingBubble){workingBubble=document.createElement('div');workingBubble.className='bubble agent agent-working';workingBubble.innerHTML='<span class="spinner"></span><span>Working...</span>';chatLog.appendChild(workingBubble)}chatLog.scrollTop=chatLog.scrollHeight}
+function removeQueuedPrompt(index,event){if(event)event.stopPropagation();queued.splice(index,1);render()}
+function postToFrame(message){frame.contentWindow&&frame.contentWindow.postMessage(message,'*')}
+window.addEventListener('message',event=>{if(event.source!==frame.contentWindow)return;const msg=event.data||{};if(msg.type==='lavish:queuePrompt'){queued.push(msg.prompt);render()}if(msg.type==='lavish:snapshot'){pendingSnapshot=msg.snapshot||'';submitQueued()}if(msg.type==='lavish:sendQueuedPrompts'){sendQueued()}if(msg.type==='lavish:endSession'){endSession()}});
+document.getElementById('annotation').onclick=()=>{annotation=!annotation;document.getElementById('annotation').textContent='Annotation: '+(annotation?'On':'Off');postToFrame({type:'lavish:setAnnotationMode',enabled:annotation})};
+sendButton.onclick=sendQueued;document.getElementById('end').onclick=endSession;
+frame.addEventListener('load',()=>postToFrame({type:'lavish:setAnnotationMode',enabled:annotation}));
+function sendQueued(){if(!agentPolling)return;const text=chatInput.value.trim();if(text){queued.push({uid:'',prompt:text,selector:'',tag:'message',text:'Freeform message'});addChat('user',text);chatInput.value='';render()}if(!queued.length)return;postToFrame({type:'lavish:requestSnapshot'})}
+async function submitQueued(){const prompts=queued.splice(0,queued.length);render();setAgentPolling(false);await fetch('/api/'+key+'/prompts',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({prompts,domSnapshot:pendingSnapshot})})}
+async function endSession(){await fetch('/api/'+key+'/end',{method:'POST'});document.body.innerHTML='<div class="bar"><div class="brand">Lavish Editor</div><div class="file">Session ended. The agent polling loop can stop.</div></div>'}
+const events=new EventSource('/events/'+key);events.addEventListener('reload',()=>{frame.src=frame.src});events.addEventListener('agent-reply',event=>addChat('agent',JSON.parse(event.data).text));events.addEventListener('chat-sync',event=>syncChat(JSON.parse(event.data).chat||[]));events.addEventListener('agent-working',event=>setAgentPolling(!JSON.parse(event.data).working));render();initialChat.forEach(item=>addChat(item.role,item.text));setAgentPolling(false);
+</script>
+</body>
+</html>`;
+}
+function createSdkJs(key) {
+  return `(() => {
+const key=${JSON.stringify(key)};
+let annotationMode=true;
+let hovered=null;
+let selected=null;
+let host=null;
+let shadow=null;
+let counter=0;
+const ids=new WeakMap();
+function uid(el){if(!ids.has(el))ids.set(el,String(++counter));return ids.get(el)}
+function selector(el){if(!el||!el.tagName)return'';const parts=[];let node=el;while(node&&node.nodeType===1&&parts.length<5){let part=node.tagName.toLowerCase();if(node.id){part+='#'+CSS.escape(node.id);parts.unshift(part);break}const parent=node.parentElement;if(parent){const same=[...parent.children].filter(x=>x.tagName===node.tagName);if(same.length>1)part+=':nth-of-type('+(same.indexOf(node)+1)+')'}parts.unshift(part);node=parent}return parts.join(' > ')}
+function context(el){return{uid:uid(el),selector:selector(el),tag:(el.tagName||'').toLowerCase(),text:(el.innerText||el.textContent||'').trim().replace(/\\s+/g,' ').slice(0,240)}}
+function isLavishUi(el){return !!(el&&el.closest&&el.closest('[data-lavish-ui]'))}
+function highlightElement(el){if(el){el.style.outline='2px solid #f4c95d';el.style.outlineOffset='2px'}}
+function clearHighlight(el){if(el)el.style.outline=''}
+function setAnnotationMode(enabled){annotationMode=!!enabled;let style=document.getElementById('lavish-cursor-style');if(annotationMode&&!style){style=document.createElement('style');style.id='lavish-cursor-style';style.textContent='*{cursor:default!important}';document.head.appendChild(style)}if(!annotationMode&&style)style.remove();if(!annotationMode)closeCard()}
+function queuePrompt(prompt,options={}){const item={...context(options.element||document.activeElement||document.body),prompt:String(prompt||'')};if(options.uid)item.uid=String(options.uid);if(options.selector)item.selector=String(options.selector);if(options.tag)item.tag=String(options.tag);if(options.text)item.text=String(options.text);if(options.data)item.prompt+='\\n\\nContext data:\\n'+JSON.stringify(options.data,null,2);parent.postMessage({type:'lavish:queuePrompt',prompt:item},'*')}
+function sendQueuedPrompts(){parent.postMessage({type:'lavish:sendQueuedPrompts'},'*')}
+function endSession(){parent.postMessage({type:'lavish:endSession'},'*')}
+function snapshot(){const lines=[];function walk(el,depth){if(!(el instanceof Element)||depth>6||isLavishUi(el))return;const c=context(el);const name=c.text?' "'+c.text.slice(0,80).replace(/"/g,"'")+'"':'';lines.push('  '.repeat(depth)+'uid='+c.uid+' '+c.tag+name);for(const child of el.children)walk(child,depth+1)}walk(document.body,0);return lines.join('\\n')}
+function ensureShadow(){if(shadow)return shadow;host=document.createElement('div');host.className='lavish-annotation-root';host.setAttribute('data-lavish-ui','annotation-root');document.documentElement.appendChild(host);shadow=host.attachShadow({mode:'open'});const style=document.createElement('style');style.textContent=':host{all:initial;position:fixed;z-index:2147483647;left:0;top:0;color-scheme:dark;font-family:ui-sans-serif,system-ui,sans-serif}*{box-sizing:border-box}.lavish-annotation-card{position:fixed;width:min(320px,calc(100vw - 24px));padding:12px;border-radius:14px;background:#11141a;color:#f7f3ea;border:1px solid #f4c95d;box-shadow:0 20px 70px rgba(0,0,0,.35);font:14px/1.4 ui-sans-serif,system-ui,sans-serif}.lavish-annotation-card textarea{width:100%;min-height:86px;resize:vertical;border-radius:10px;border:1px solid #303745;background:#0f1115;color:#f7f3ea;padding:9px;font:inherit}.lavish-annotation-card .lavish-row{display:flex;gap:8px;justify-content:flex-end;margin-top:8px}.lavish-annotation-card button{border:0;border-radius:9px;padding:8px 10px;font-weight:800;cursor:pointer}.lavish-annotation-card .lavish-send{background:#f4c95d;color:#17130a}.lavish-annotation-card .lavish-cancel{background:#2a2f3a;color:#f7f3ea}';shadow.appendChild(style);return shadow}
+function closeCard(){if(shadow){for(const el of [...shadow.querySelectorAll('.lavish-annotation-card')])el.remove()}clearHighlight(selected);selected=null}
+function showAnnotationCard(target){const root=ensureShadow();closeCard();selected=target;highlightElement(selected);const c=context(target);const rect=target.getBoundingClientRect();const card=document.createElement('div');card.className='lavish-annotation-card';card.innerHTML='<div style="font-weight:800;margin-bottom:6px">Annotate &lt;'+c.tag+'&gt;</div><textarea placeholder="Tell the agent what to change about this element..."></textarea><div class="lavish-row"><button class="lavish-cancel" type="button">Cancel</button><button class="lavish-send" type="button">Queue Prompt</button></div>';root.appendChild(card);const left=Math.min(Math.max(12,rect.left),window.innerWidth-card.offsetWidth-12);const top=Math.min(Math.max(12,rect.bottom+8),window.innerHeight-card.offsetHeight-12);card.style.left=left+'px';card.style.top=top+'px';const textarea=card.querySelector('textarea');card.querySelector('.lavish-cancel').onclick=closeCard;card.querySelector('.lavish-send').onclick=()=>{const prompt=textarea.value.trim();if(prompt)queuePrompt(prompt,c);closeCard()};setTimeout(()=>textarea.focus(),0)}
+window.lavish={queuePrompt,sendQueuedPrompts,endSession,getQueuedPrompts:()=>[],setStatus:message=>parent.postMessage({type:'lavish:status',message:String(message)},'*'),snapshot};
+window.addEventListener('message',event=>{const msg=event.data||{};if(msg.type==='lavish:setAnnotationMode')setAnnotationMode(msg.enabled);if(msg.type==='lavish:requestSnapshot')parent.postMessage({type:'lavish:snapshot',snapshot:snapshot()},'*')});
+document.addEventListener('mouseover',event=>{if(!annotationMode||isLavishUi(event.target))return;if(event.target===selected)return;if(hovered&&hovered!==selected)clearHighlight(hovered);hovered=event.target;highlightElement(hovered)},true);
+document.addEventListener('mouseout',()=>{if(hovered&&hovered!==selected){clearHighlight(hovered);hovered=null}},true);
+document.addEventListener('click',event=>{if(!annotationMode||isLavishUi(event.target))return;event.preventDefault();event.stopPropagation();showAnnotationCard(event.target)},true);
+setAnnotationMode(annotationMode);
+})();`;
+}
+function escapeHtml(value) {
+  return String(value).replace(
+    /[&<>"']/g,
+    (char) => ({
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;"
+    })[char]
+  );
+}
+
+// src/telemetry.js
+var HARDCODED_FALLBACK_HOST = "https://a.kunchenguid.com";
+var UMAMI_PATH = "/api/send";
+var DEFAULT_HOSTNAME = "cli";
+var DEFAULT_TITLE = "Lavish Editor CLI";
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e3;
+function resolveTelemetryConfig(input) {
+  const optOut = String(input.env.LAVISH_AXI_TELEMETRY || "").trim().toLowerCase();
+  if (optOut === "0" || optOut === "false" || optOut === "off") {
+    return { enabled: false, host: "", websiteID: "" };
+  }
+  const websiteID = String(input.env.LAVISH_AXI_UMAMI_WEBSITE_ID || "").trim() || input.buildWebsiteID.trim();
+  if (!websiteID) {
+    return { enabled: false, host: "", websiteID: "" };
+  }
+  const host = String(input.env.LAVISH_AXI_UMAMI_HOST || "").trim() || input.buildHost.trim() || HARDCODED_FALLBACK_HOST;
+  return { enabled: true, host, websiteID };
+}
+function getBuildTimeUmamiHost() {
+  return "";
+}
+function getBuildTimeUmamiWebsiteID() {
+  return "";
+}
+function createTelemetryClient(config) {
+  if (!config.enabled || !config.websiteID) {
+    return new NoopTelemetryClient();
+  }
+  const endpoint = normalizeEndpoint(config.host);
+  if (!endpoint) {
+    return new NoopTelemetryClient();
+  }
+  return new HttpTelemetryClient(endpoint, config);
+}
+var defaultClient = null;
+function initDefaultTelemetry(init) {
+  const resolved = resolveTelemetryConfig({
+    env: init.env || process.env,
+    buildHost: getBuildTimeUmamiHost(),
+    buildWebsiteID: getBuildTimeUmamiWebsiteID()
+  });
+  defaultClient = createTelemetryClient({
+    enabled: resolved.enabled,
+    host: resolved.host,
+    websiteID: resolved.websiteID,
+    app: init.app,
+    version: init.version,
+    platform: init.platform,
+    arch: init.arch
+  });
+  return defaultClient;
+}
+var NoopTelemetryClient = class {
+  track() {
+  }
+  pageview() {
+  }
+  async close() {
+  }
+};
+var HttpTelemetryClient = class {
+  constructor(endpoint, config) {
+    this.endpoint = endpoint;
+    this.websiteID = config.websiteID;
+    this.app = config.app;
+    this.version = config.version;
+    this.platform = config.platform || "";
+    this.arch = config.arch || "";
+    this.fetchImpl = config.fetch || fetch;
+    this.timeoutMs = config.requestTimeoutMs || DEFAULT_REQUEST_TIMEOUT_MS;
+    this.userAgent = `${config.app}/${config.version} telemetry`;
+    this.inFlight = /* @__PURE__ */ new Set();
+    this.closed = false;
+  }
+  track(name, fields = {}) {
+    if (this.closed) return;
+    const trimmed = String(name || "").trim();
+    if (!trimmed) return;
+    this.send(trimmed, eventURL(this.app, trimmed), fields);
+  }
+  pageview(path5, fields = {}) {
+    if (this.closed) return;
+    this.send("", normalizePagePath(path5), fields);
+  }
+  async close(timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    this.closed = true;
+    if (this.inFlight.size === 0 || timeoutMs <= 0) return;
+    const drained = Promise.allSettled(Array.from(this.inFlight)).then(() => void 0);
+    await Promise.race([
+      drained,
+      new Promise((resolve) => {
+        setTimeout(resolve, timeoutMs).unref?.();
+      })
+    ]);
+  }
+  send(name, url, fields) {
+    const data = { ...fields };
+    if (this.platform && data.platform === void 0) data.platform = this.platform;
+    if (this.arch && data.arch === void 0) data.arch = this.arch;
+    if (data.version === void 0) data.version = this.version;
+    const payload = {
+      type: "event",
+      payload: {
+        website: this.websiteID,
+        hostname: DEFAULT_HOSTNAME,
+        title: DEFAULT_TITLE,
+        url,
+        name,
+        data,
+        timestamp: Math.floor(Date.now() / 1e3)
+      }
+    };
+    let body;
+    try {
+      body = JSON.stringify(payload);
+    } catch {
+      return;
+    }
+    const request = this.fire(body);
+    this.inFlight.add(request);
+    request.finally(() => this.inFlight.delete(request));
+  }
+  async fire(body) {
+    try {
+      const response = await this.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": this.userAgent
+        },
+        body,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      try {
+        await response.body?.cancel?.();
+      } catch {
+      }
+    } catch {
+    }
+  }
+};
+function normalizeEndpoint(host) {
+  let url;
+  try {
+    url = new URL(String(host || "").trim());
+  } catch {
+    return null;
+  }
+  if (!url.protocol || !url.host) return null;
+  const pathname = url.pathname.replace(/\/+$/, "");
+  url.pathname = pathname.endsWith(UMAMI_PATH) ? pathname : pathname + UMAMI_PATH;
+  return url.toString();
+}
+function eventURL(app, name) {
+  if (!name) return `app://${app}`;
+  return `app://${app}/${name.replace(/\./g, "/")}`;
+}
+function normalizePagePath(path5) {
+  const trimmed = String(path5 || "").trim();
+  if (!trimmed) return "/";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+// src/cli.js
+var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "server"]);
+var DESCRIPTION = "Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. First generate an interactive HTML artifact for the user to inspect, then run `lavish-axi <html-file>` so the user can visually review it, annotate elements, queue prompts, and send feedback back through `lavish-axi poll`.";
+var VERSION = "0.1.0";
+async function run(argv) {
+  await ensureStateDir();
+  const normalizedArgv = normalizeArgv(argv);
+  const command = telemetryCommandName(argv);
+  const telemetry = initDefaultTelemetry({
+    app: "lavish-axi",
+    version: VERSION,
+    platform: process.platform,
+    arch: process.arch
+  });
+  telemetry.pageview(`/${command}`, { command });
+  try {
+    await runAxiCli({
+      description: DESCRIPTION,
+      version: VERSION,
+      argv: normalizedArgv,
+      topLevelHelp: TOP_LEVEL_HELP,
+      hooks: { binaryNames: ["lavish-axi"] },
+      home: async () => createHomeOutput({
+        bin: process.argv[1] || "lavish-axi",
+        sessions: await visibleSessions()
+      }),
+      commands: {
+        open: openCommand,
+        poll: pollCommand,
+        end: endCommand,
+        server: serverCommand
+      },
+      getCommandHelp
+    });
+    telemetry.track("command", { command, status: "success" });
+  } catch (error) {
+    telemetry.track("command", { command, status: "error" });
+    throw error;
+  } finally {
+    await telemetry.close(1e3);
+  }
+}
+function collapseHomeDirectory(file, home) {
+  if (file === home) {
+    return "~";
+  }
+  if (file.startsWith(`${home}${path4.sep}`)) {
+    return `~${file.slice(home.length)}`;
+  }
+  return file;
+}
+function normalizeArgv(argv) {
+  const first = argv[0];
+  if (!first || COMMANDS.has(first)) {
+    return argv;
+  }
+  if (first.startsWith("-")) {
+    return argv.some((arg) => isHtmlPath(arg)) ? ["open", ...argv] : argv;
+  }
+  return ["open", ...argv];
+}
+function telemetryCommandName(argv) {
+  const normalized = normalizeArgv(argv);
+  return normalized[0] && !normalized[0].startsWith("-") ? normalized[0] : "home";
+}
+function createHomeOutput({ bin, sessions }) {
+  return {
+    bin: collapseHomeDirectory(bin, os2.homedir()),
+    description: DESCRIPTION,
+    sessions: sessions.map((session) => ({
+      file: session.file,
+      status: session.status,
+      url: session.url,
+      pending_prompts: session.pending_prompts || 0
+    })),
+    use_cases: [
+      "Implementation plans with diagrams, mockups, data flow, and code snippets",
+      "Design explorations with multiple visual options side by side",
+      "PR and code review explainers with annotated diffs and findings",
+      "Interactive prototypes with sliders, knobs, forms, and animation tuning",
+      "Reports, research summaries, incident writeups, and learning guides",
+      "Custom editing interfaces for triage, config editing, prompt tuning, dataset curation, and structured config editing"
+    ],
+    artifact_guidance: [
+      "Use clear sections, headings, tabs, cards, tables, diagrams, and spatial layout instead of long prose",
+      "Include concrete artifacts such as mockups, SVG diagrams, annotated code snippets, diffs, data-flow charts, and examples",
+      "For exploration, show multiple options side by side and label the tradeoff each option makes",
+      "For code review, render the relevant diff or snippets with inline annotations and severity-coded findings",
+      "For custom editors, include controls that let the user adjust values, then call `window.lavish.queuePrompt(...)` with the requested change",
+      "End interactive workflows with an obvious way for the user to queue prompts and send them back"
+    ],
+    visual_guidance: [
+      "Choose a clear visual point of view that matches the artifact: editorial, technical dashboard, dense control room, refined memo, playful prototype, brutalist review board, etc.",
+      "Use typography, spacing, color, and layout deliberately; avoid generic system-font cards on white unless that restraint is the actual design choice",
+      "Use visual hierarchy to make the most important decisions, risks, tradeoffs, and next actions obvious at a glance",
+      "Prefer diagrams, tables, annotated snippets, side-by-side comparisons, and spatial layouts over long prose",
+      "For explorations, make options visually distinct and label the tradeoff each option makes",
+      "For interactive artifacts, provide obvious controls and queue the user's chosen values with `window.lavish.queuePrompt(...)`",
+      "Make the artifact responsive and readable; visual polish should improve comprehension, not distract from review"
+    ],
+    help: [
+      "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session",
+      "Run `lavish-axi poll <html-file>` to wait for user feedback",
+      "Run `lavish-axi end <html-file>` to end a session"
+    ]
+  };
+}
+function createOpenOutput({ file, url, status }) {
+  return {
+    session: { file, url, status },
+    next_step: `Tell the user to open ${url} to review the artifact in Lavish Editor, then run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback or ends the session. Do not pass --timeout-ms during normal agent use. Do not set a short shell timeout; either run it without a timeout or set the shell timeout above 10 minutes. After applying feedback, run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms to show your response in Lavish Editor and wait for more feedback.`
+  };
+}
+async function openCommand(args) {
+  const file = args.find((arg) => !arg.startsWith("-"));
+  if (!file) {
+    throw new AxiError("HTML file path is required", "VALIDATION_ERROR", ["Run `lavish-axi <html-file>`"]);
+  }
+  await assertHtmlFile(file);
+  const absolute = await canonicalFile(file);
+  const baseUrl = await ensureServer();
+  const response = await postJson(`${baseUrl}/api/sessions`, { file: absolute });
+  if (shouldOpenBrowser(args, process.env)) {
+    try {
+      const open = (await import("open")).default;
+      await open(response.url);
+    } catch {
+      response.status = "ready";
+    }
+  }
+  return createOpenOutput({ file: absolute, url: response.url, status: response.status || "opened" });
+}
+function shouldOpenBrowser(args, env) {
+  return !args.includes("--no-open") && env.LAVISH_AXI_NO_OPEN !== "1";
+}
+async function pollCommand(args) {
+  const file = args[0];
+  if (!file) {
+    throw new AxiError("HTML file path is required", "VALIDATION_ERROR", ["Run `lavish-axi poll <html-file>`"]);
+  }
+  const absolute = await canonicalFile(file);
+  const baseUrl = await ensureServer();
+  const agentReply = flagValue(args, "--agent-reply");
+  if (agentReply) {
+    await postJson(`${baseUrl}/api/${sessionKey(absolute)}/agent-reply`, { text: agentReply });
+  }
+  const timeoutMs = flagValue(args, "--timeout-ms");
+  const timeoutQuery = timeoutMs ? `&timeoutMs=${encodeURIComponent(timeoutMs)}` : "";
+  const response = await fetchJson(`${baseUrl}/api/poll?file=${encodeURIComponent(absolute)}${timeoutQuery}`);
+  return createPollOutput({ file: absolute, response });
+}
+function createPollOutput({ file, response }) {
+  if (response.status === "missing") {
+    throw new AxiError("No active Lavish Editor session for this file", "NOT_FOUND", [
+      `Run \`lavish-axi ${file}\` first`
+    ]);
+  }
+  if (response.status === "feedback") {
+    return {
+      session: { file, status: "feedback" },
+      dom_snapshot: response.dom_snapshot || "",
+      prompts: response.prompts || [],
+      next_step: `Apply the requested changes to ${file}, then run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms unless the user ended the session. The poll command waits until the user sends more feedback or ends the session; do not set a short shell timeout, or set the shell timeout above 10 minutes.`
+    };
+  }
+  if (response.status === "ended") {
+    return { session: { file, status: "ended" } };
+  }
+  return {
+    session: { file, status: response.status || "waiting" },
+    next_step: `No user feedback arrived before the optional timeout. Run \`lavish-axi poll ${file}\` without --timeout-ms to wait indefinitely.`
+  };
+}
+async function endCommand(args) {
+  const file = args[0];
+  if (!file) {
+    throw new AxiError("HTML file path is required", "VALIDATION_ERROR", ["Run `lavish-axi end <html-file>`"]);
+  }
+  const absolute = await canonicalFile(file);
+  const baseUrl = await ensureServer();
+  const response = await postJson(`${baseUrl}/api/end`, { file: absolute });
+  return { session: { file: absolute, status: response.status || "ended" } };
+}
+async function serverCommand(args) {
+  const port = Number(flagValue(args, "--port") || defaultPort());
+  await serve({ port, stateFile: stateFile() });
+  return "";
+}
+async function visibleSessions() {
+  const store = new SessionStore(stateFile());
+  return (await store.listSessions()).filter((session) => session.status !== "ended");
+}
+async function assertHtmlFile(file) {
+  if (!isHtmlPath(file)) {
+    throw new AxiError("Lavish Editor expects an HTML file", "VALIDATION_ERROR", ["Run `lavish-axi <html-file>`"]);
+  }
+  try {
+    await access(file);
+  } catch {
+    throw new AxiError(`File not found: ${file}`, "NOT_FOUND", [
+      "Create the HTML artifact first, then run `lavish-axi <html-file>`"
+    ]);
+  }
+}
+function isHtmlPath(file) {
+  return file.toLowerCase().endsWith(".html") || file.toLowerCase().endsWith(".htm");
+}
+async function ensureServer() {
+  const port = defaultPort();
+  const baseUrl = `http://localhost:${port}`;
+  if (await isHealthy(baseUrl)) {
+    return baseUrl;
+  }
+  await startServer(port);
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline) {
+    if (await isHealthy(baseUrl)) {
+      return baseUrl;
+    }
+    await delay(100);
+  }
+  throw new AxiError("Lavish Editor server did not start", "SERVER_ERROR", [
+    `Run \`lavish-axi server --port ${port}\` to inspect server startup`
+  ]);
+}
+async function startServer(port) {
+  await ensureStateDir();
+  const bin = fileURLToPath(new URL("../bin/lavish-axi.js", import.meta.url));
+  const child = spawn(process.execPath, [bin, "server", "--port", String(port)], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, LAVISH_AXI_NO_OPEN: "1" }
+  });
+  child.unref();
+}
+async function isHealthy(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/health`);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
+  }
+  return response.json();
+}
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
+  }
+  return response.json();
+}
+function flagValue(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) {
+    return null;
+  }
+  return args[index + 1] || null;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getCommandHelp(command) {
+  return COMMAND_HELP[command] || null;
+}
+var TOP_LEVEL_HELP = `lavish-axi - Lavish Editor AXI
+
+Usage:
+  lavish-axi
+  lavish-axi <html-file>
+  lavish-axi poll <html-file> [--agent-reply "..."]
+  lavish-axi end <html-file>
+
+Note: poll long-polls indefinitely by default until the user sends feedback or ends the session. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. do not set a short shell timeout; either run it without a timeout or use a very high threshold above 10 minutes.
+
+`;
+var COMMAND_HELP = {
+  open: `Usage: lavish-axi <html-file> [--no-open]
+
+Open or resume a Lavish Editor review session for an HTML artifact. Use --no-open when you need to ensure the server/session exists without opening another browser window.
+`,
+  poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."]
+
+This command long-polls indefinitely for queued user prompts, then returns them to the agent. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. do not set a short shell timeout; either run it without a timeout or use a very high threshold above 10 minutes so the user has time to review and send feedback. Use --agent-reply after applying prior feedback to display your response in Lavish Editor before waiting again.
+`,
+  end: `Usage: lavish-axi end <html-file>
+
+End a Lavish Editor session.
+`,
+  server: `Usage: lavish-axi server [--port 4387]
+
+Run the local Lavish Editor server.
+`
+};
+
+// bin/lavish-axi.js
+await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "lavish-axi",
+  "version": "0.1.0",
+  "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
+  "type": "module",
+  "bin": {
+    "lavish-axi": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "start": "node dist/cli.mjs",
+    "lint": "eslint bin src test scripts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "npm run build",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "axi-sdk-js": "^0.1.5",
+    "chokidar": "^4.0.3",
+    "express": "^5.2.1",
+    "open": "^10.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.6.2",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "axi",
+    "agent",
+    "cli",
+    "html",
+    "review",
+    "collaboration"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kunchenguid/lavish.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kunchenguid/lavish/issues"
+  },
+  "homepage": "https://github.com/kunchenguid/lavish#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}