lavish-axi 0.1.34 → 0.1.36

package/README.md

@@ -31,10 +31,10 @@ 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 agent-generated HTML files in a local browser, lets you pinpoint elements or selected text and send feedback to the agent to address.
+Lavish Editor opens agent-generated HTML files in a local browser, lets you pinpoint elements, selected text, or Mermaid diagram nodes and send feedback to the agent to address.
 
 - **Local-first** - Review local HTML artifacts with a local CLI and no cloud dependency in the core feedback loop; hosted sharing through third-party ht-ml.app is explicit and opt-in.
-- **Human-AI collaboration** - Annotate elements, selected text ranges, and send messages to the agent without leaving Lavish Editor.
+- **Human-AI collaboration** - Annotate elements, selected text ranges, and Mermaid diagram nodes, and send messages to the agent without leaving Lavish Editor.
 - **Battery included** - Lavish Editor teaches your agent good visualization for common use cases such as product or technical plans, design explorations and more out of the box.
 
 Lavish Editor is an [AXI](https://axi.md), which means -
@@ -54,6 +54,8 @@ npx skills add kunchenguid/lavish-axi --skill lavish
 That is the entire setup - no npm install needed.
 The skill teaches your agent to run Lavish through `npx -y lavish-axi`, so the CLI comes along on demand.
 Its frontmatter also includes Hermes Agent metadata, so Hermes-compatible harnesses can categorize and surface it as a first-class productivity skill.
+This installs the public `lavish` skill.
+The repository also contains an internal `lavish-design` brand skill for maintainers; default `npx skills add ... --list` and skills.sh discovery hide it unless `INSTALL_INTERNAL_SKILLS=1` is set.
 
 Then, in agents that expose skills as slash commands (Claude Code, for example), invoke it directly:
 
@@ -155,11 +157,17 @@ pnpm link
 - **Feedback controls** - Native controls (radios, checkboxes, inputs, selects, buttons, labels, disclosure summaries, contenteditable) are interactive automatically, so they do not need `data-lavish-action`.
   For reversible choices, let option clicks update local state, then queue exactly one final answer from a per-question submit or Queue answer button with `window.lavish.queuePrompt()`.
   Mark only custom (non-native) clickable elements with `data-lavish-action` so Lavish does not annotate them, and use `data-lavish-question` or `queueKey` when pre-send updates for the same question should replace each other.
-  The browser chrome keeps editing actions in the overflow menu (copy path, reload artifact, copy DOM snapshot, export standalone HTML, publish link, end session) and can submit queued prompts with **Send & end session**, which delivers the prompts before ending the session.
+  The browser chrome keeps editing actions in the overflow menu (copy path, reload artifact, copy DOM snapshot, export standalone HTML, publish link, end session) and can submit queued prompts with **Send & end session**, which sends the prompts and user-ended attribution together.
 - **Keyboard shortcuts** - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline.
   In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately.
+  Cmd+I or Ctrl+I toggles between annotate and explore mode from either the browser chrome or the artifact iframe, including while focus is in a textarea or control.
 - **Agent presence** - The browser shows when no agent is listening, keeps queued feedback and fresh layout warnings for the next successful `lavish-axi poll` send even across reloads, and only blocks human sends while the agent is working on delivered feedback. The no-timeout poll writes an immediate stderr banner and periodic stderr heartbeats while stdout stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost.
+- **Session end etiquette** - Lavish tracks who ended a session: a human clicking **End session** (or **Send & end session**) in the browser is a user-initiated end, while `lavish-axi end <html-file>` is agent-initiated.
+  A plain `lavish-axi <html-file>` after a user-initiated end refuses to reopen the browser and returns guidance instead; pass `--reopen` only when the user asks for further review or something important needs their visual attention.
+  Agent-initiated ends keep reopening normally, same as before.
+  `lavish-axi poll`'s `ended` response and the `feedback` response for the final batch before an end both carry `next_step` guidance telling the agent to stop polling and deliver remaining updates in chat instead of reopening.
 - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
+- **Mermaid diagrams** - Rendered Mermaid diagrams become pannable and zoomable while you explore (drag to pan, scroll to zoom) and freeze when you turn on annotation so a click lands on a single node. Clicking a node annotates the whole node and sends the agent its diagram id, node id, and rendered label instead of just a CSS selector. Lavish only enhances the live render, so the saved HTML still opens identically anywhere.
 - **Server cleanup** - The detached server stops after the last session ends when nothing is connected, or after `LAVISH_AXI_IDLE_TIMEOUT_MS` (default 30 minutes) with no browser or poll connections.
   Set `LAVISH_AXI_IDLE_TIMEOUT_MS=0` or `off` to disable idle self-shutdown.
 - **Local-first state** - Session state stays under `~/.lavish-axi/` by default, or `LAVISH_AXI_STATE_DIR` when set.
@@ -171,9 +179,9 @@ pnpm link
 | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `lavish-axi`                    | Show current sessions and usage guidance.                                                                                                                                                                                                                                 |
 | `lavish-axi update`             | Check for or apply the latest npm release through the AXI SDK self-updater.                                                                                                                                                                                               |
-| `lavish-axi <html-file>`        | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default.                                                                                                                                                                                |
-| `lavish-axi poll <html-file>`   | Long-poll until the user sends feedback, ends the session, or the browser reports fresh `layout_warnings`; leave no-timeout polls running, or re-run them if interrupted.                                                                                                 |
-| `lavish-axi end <html-file>`    | End a session.                                                                                                                                                                                                                                                            |
+| `lavish-axi <html-file>`        | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. Refuses to reopen a session the user explicitly ended from the browser unless `--reopen` is passed.                                                                            |
+| `lavish-axi poll <html-file>`   | Long-poll until the user sends feedback, ends the session, or the browser reports fresh `layout_warnings`; leave no-timeout polls running, or re-run them if interrupted. On `status: ended`, stop polling and do not reopen uninvited.                                   |
+| `lavish-axi end <html-file>`    | End a session as the agent; unlike a user-initiated end from the browser, this still allows a plain reopen later.                                                                                                                                                         |
 | `lavish-axi export <html-file>` | Write a portable copy of the artifact: one HTML file with its local assets inlined, so it opens with no server and no sibling files. Remote CDN/font references are left as links.                                                                                        |
 | `lavish-axi share <html-file>`  | Publish the artifact (local assets inlined) to [ht-ml.app](https://ht-ml.app), a third-party host not part of Lavish, and print a visitable URL plus a secret update key; shares are public by default, and `--password` makes viewers enter the password before viewing. |
 | `lavish-axi stop`               | Shut down the background server.                                                                                                                                                                                                                                          |
@@ -192,6 +200,7 @@ For flows, architecture, state, or sequence diagrams, open the diagram playbook
 | ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `lavish-axi <html-file>` | `--no-open`           | Ensure the server/session exists without opening another browser window.                                                                                                                                                            |
 | `lavish-axi <html-file>` | `--no-gate`           | Skip the open-time layout curtain for this browser open.                                                                                                                                                                            |
+| `lavish-axi <html-file>` | `--reopen`            | Reopen a session the user explicitly ended from the browser; without it, a plain open refuses and explains why instead of reopening uninvited.                                                                                      |
 | `lavish-axi update`      | `--check`             | Report current vs latest npm version without installing an update.                                                                                                                                                                  |
 | `lavish-axi export`      | `--out <path>`        | Write the export to a specific path instead of `<name>.export.html` next to the source.                                                                                                                                             |
 | `lavish-axi share`       | `--password <pw>`     | Make the third-party ht-ml.app page private; viewers must supply the password.                                                                                                                                                      |

package/dist/chrome-client.js

@@ -7,6 +7,12 @@ const filePath = String(sessionData.file || "");
 const queueStorageKey = "lavish-axi:queued:" + key;
 const internalQueueKeyField = "_lavishQueueKey";
 const initialChat = Array.isArray(sessionData.initialChat) ? sessionData.initialChat : [];
+const MODE_TOGGLE_HOTKEY_KEY = String(sessionData.modeToggleHotkeyKey || "").toLowerCase();
+
+function isModeToggleHotkeyEvent(event) {
+  if (event.shiftKey || event.altKey) return false;
+  return Boolean(event.metaKey || event.ctrlKey) && String(event.key || "").toLowerCase() === MODE_TOGGLE_HOTKEY_KEY;
+}
 
 const frame = /** @type {HTMLIFrameElement} */ (document.getElementById("artifact"));
 const annotationPills = /** @type {HTMLDivElement} */ (document.getElementById("annotationPills"));
@@ -328,21 +334,26 @@ async function submitQueued() {
     submitQueuedAgain = false;
     if (!succeeded) {
       endAfterSubmit = false;
-    } else if (shouldSubmitAgain && queued.length) {
-      submitQueued();
-    } else if (endAfterSubmit) {
-      endAfterSubmit = false;
-      await endSession();
+    } else if (!ended && shouldSubmitAgain) {
+      if (queued.length) {
+        submitQueued();
+      } else if (endAfterSubmit) {
+        endAfterSubmit = false;
+        endSession();
+      }
     }
   }
 }
 
 async function submitQueuedOnce() {
   const prompts = queued.slice();
+  const shouldEndSession = endAfterSubmit;
+  const body = { prompts: prompts.map(stripInternalPromptFields), domSnapshot: pendingSnapshot };
+  if (shouldEndSession) body.endSession = true;
   const response = await fetch("/api/" + key + "/prompts", {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ prompts: prompts.map(stripInternalPromptFields), domSnapshot: pendingSnapshot }),
+    body: JSON.stringify(body),
   });
   if (!response.ok) throw new Error("failed to submit queued prompts");
   for (const prompt of prompts) {
@@ -351,6 +362,11 @@ async function submitQueuedOnce() {
   }
   persistQueuedPrompts();
   render();
+  if (shouldEndSession) {
+    endAfterSubmit = false;
+    markSessionEnded();
+    return;
+  }
   if (agentPresence === "listening") setAgentPresence("working");
 }
 
@@ -474,6 +490,11 @@ async function endSession() {
   if (ended) return;
   const response = await fetch("/api/" + key + "/end", { method: "POST" });
   if (!response.ok) throw new Error("failed to end session");
+  markSessionEnded();
+}
+
+function markSessionEnded() {
+  if (ended) return;
   ended = true;
   closeMenus();
   annotationSwitch.disabled = true;
@@ -686,15 +707,19 @@ window.addEventListener("message", (event) => {
   }
   if (msg.type === "lavish:sendQueuedPrompts") sendQueued();
   if (msg.type === "lavish:endSession") endSession();
+  if (msg.type === "lavish:toggleAnnotationMode") toggleAnnotationMode();
 });
 
 loadFrame();
 
-annotationSwitch.onclick = () => {
+function toggleAnnotationMode() {
+  if (ended) return;
   annotation = !annotation;
   annotationSwitch.setAttribute("aria-pressed", String(annotation));
   postToFrame({ type: "lavish:setAnnotationMode", enabled: annotation });
-};
+}
+
+annotationSwitch.onclick = toggleAnnotationMode;
 
 sendButton.onclick = () => sendQueued(false);
 sendFromMenuButton.onclick = () => sendQueued(false);
@@ -739,6 +764,17 @@ document.addEventListener("keydown", (event) => {
     }
   }
 });
+// Capture phase so the mode hotkey fires no matter where focus is in the chrome - including
+// mid-keystroke in chatInput or an annotation-card textarea - without disturbing normal typing.
+document.addEventListener(
+  "keydown",
+  (event) => {
+    if (!isModeToggleHotkeyEvent(event)) return;
+    event.preventDefault();
+    toggleAnnotationMode();
+  },
+  true,
+);
 frame.addEventListener("load", () => {
   postToFrame({ type: "lavish:setAnnotationMode", enabled: annotation && !ended });
   // Replay the pre-reload scroll position so hot reloads don't jump the artifact to the top.

package/dist/cli.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/cli.js
 import { spawn, spawnSync } from "node:child_process";
@@ -4188,7 +4193,67 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 import chokidar from "chokidar";
 import express from "express";
 
+// src/mermaid-node.js
+var mermaid_node_exports = {};
+__export(mermaid_node_exports, {
+  isMermaidSvg: () => isMermaidSvg,
+  mermaidNodeElement: () => mermaidNodeElement,
+  mermaidNodeFrom: () => mermaidNodeFrom,
+  normalizeMermaidNodeTarget: () => normalizeMermaidNodeTarget,
+  readNodeLabel: () => readNodeLabel
+});
+function isMermaidSvg(svg) {
+  if (!svg) return false;
+  const id = svg.id || "";
+  if (id.startsWith("mermaid-") || id.startsWith("mermaid_")) return true;
+  if (svg.getAttribute?.("aria-roledescription")) return true;
+  return !!(svg.closest && svg.closest(".mermaid, [data-lavish-mermaid]"));
+}
+function readNodeLabel(labelEl) {
+  if (!labelEl) return "";
+  let source = labelEl;
+  if (labelEl.querySelector?.("br") && labelEl.cloneNode) {
+    source = labelEl.cloneNode(true);
+    for (const br of source.querySelectorAll("br")) br.replaceWith(document.createTextNode(" "));
+  }
+  return (source.textContent || "").trim().replace(/\s+/g, " ").slice(0, 120);
+}
+function mermaidNodeElement(el) {
+  if (!el || !el.closest) return null;
+  const node = el.closest("g.node, g.nodes > g");
+  if (!node) return null;
+  const svg = node.closest("svg");
+  return svg && isMermaidSvg(svg) ? node : null;
+}
+function mermaidNodeFrom(el, selector) {
+  const node = mermaidNodeElement(el);
+  if (!node) return null;
+  const svg = node.closest("svg");
+  const labelEl = node.querySelector(".nodeLabel, .label, foreignObject span, text");
+  return {
+    type: "mermaid-node",
+    diagramId: svg.id || "",
+    nodeId: node.id || "",
+    label: readNodeLabel(labelEl),
+    selector: typeof selector === "function" ? selector(node) : ""
+  };
+}
+function normalizeMermaidNodeTarget(target) {
+  return {
+    type: "mermaid-node",
+    diagramId: String(target.diagramId || ""),
+    nodeId: String(target.nodeId || ""),
+    label: String(target.label || ""),
+    selector: String(target.selector || "")
+  };
+}
+
 // src/artifact-sdk.js
+var MODE_TOGGLE_HOTKEY_KEY = "i";
+function isModeToggleHotkeyEvent(event) {
+  if (event.shiftKey || event.altKey) return false;
+  return Boolean(event.metaKey || event.ctrlKey) && String(event.key || "").toLowerCase() === MODE_TOGGLE_HOTKEY_KEY;
+}
 function deriveLavishQueueKey(element, options = {}) {
   function stringValue(value) {
     return value === null || value === void 0 ? "" : String(value);
@@ -4328,7 +4393,8 @@ function resolveVisibleSpillCandidates(spillCandidates, { epsilon = 1 } = {}) {
     )
   );
 }
-function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInteractiveControl) {
+function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInteractiveControl, mermaid = mermaid_node_exports) {
+  const { isMermaidSvg: isMermaidSvg2, mermaidNodeFrom: mermaidNodeFrom2, mermaidNodeElement: mermaidNodeElement2 } = mermaid;
   let annotationMode = true;
   let hovered = null;
   let selected = null;
@@ -4340,6 +4406,12 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     if (!ids.has(el)) ids.set(el, String(++counter));
     return ids.get(el);
   }
+  function escapeAnnotationText(value) {
+    return String(value).replace(
+      /[&<>"']/g,
+      (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]
+    );
+  }
   function selector(el) {
     if (!el || !el.tagName) return "";
     const parts = [];
@@ -4362,12 +4434,138 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     return parts.join(" > ");
   }
   function context(el) {
-    return {
+    const base = {
       uid: uid(el),
       selector: selector(el),
       tag: (el.tagName || "").toLowerCase(),
       text: (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 240)
     };
+    const mermaidNode = mermaidNodeFrom2(el, selector);
+    if (mermaidNode) {
+      base.tag = "mermaid-node";
+      base.text = mermaidNode.label || base.text;
+      base.target = mermaidNode;
+    }
+    return base;
+  }
+  function annotationTargetEl(el) {
+    return mermaidNodeElement2(el) || el;
+  }
+  const mermaidViewports = /* @__PURE__ */ new WeakMap();
+  function findMermaidSvgs() {
+    const svgs = /* @__PURE__ */ new Set();
+    for (const svg of document.querySelectorAll("svg")) {
+      if (isMermaidSvg2(svg)) svgs.add(svg);
+    }
+    return [...svgs];
+  }
+  function createViewport(svg) {
+    const bbox = svg.getBBox ? safeBBox(svg) : null;
+    const initial = readViewBox(svg) || (bbox ? { x: bbox.x, y: bbox.y, w: bbox.width, h: bbox.height } : null);
+    if (!initial) return null;
+    svg.setAttribute("viewBox", `${initial.x} ${initial.y} ${initial.w} ${initial.h}`);
+    const view = { ...initial };
+    let frozen = false;
+    let panning = null;
+    function apply() {
+      svg.setAttribute("viewBox", `${view.x} ${view.y} ${view.w} ${view.h}`);
+    }
+    function reset() {
+      Object.assign(view, initial);
+      apply();
+    }
+    function zoomAt(clientX, clientY, factor) {
+      const rect = svg.getBoundingClientRect();
+      if (!rect.width || !rect.height) return;
+      const px = (clientX - rect.left) / rect.width;
+      const py = (clientY - rect.top) / rect.height;
+      const fx = view.x + view.w * px;
+      const fy = view.y + view.h * py;
+      const next = Math.min(Math.max(view.w * factor, initial.w / 40), initial.w * 8);
+      const scale = next / view.w;
+      view.w = next;
+      view.h *= scale;
+      view.x = fx - (fx - view.x) * scale;
+      view.y = fy - (fy - view.y) * scale;
+      apply();
+    }
+    function onWheel(event) {
+      if (frozen) return;
+      event.preventDefault();
+      zoomAt(event.clientX, event.clientY, event.deltaY > 0 ? 1.15 : 1 / 1.15);
+    }
+    function onPointerDown(event) {
+      if (frozen || event.button !== 0) return;
+      panning = { x: event.clientX, y: event.clientY, vx: view.x, vy: view.y };
+      svg.setPointerCapture?.(event.pointerId);
+      svg.style.cursor = "grabbing";
+    }
+    function onPointerMove(event) {
+      if (!panning) return;
+      const rect = svg.getBoundingClientRect();
+      if (!rect.width || !rect.height) return;
+      view.x = panning.vx - (event.clientX - panning.x) / rect.width * view.w;
+      view.y = panning.vy - (event.clientY - panning.y) / rect.height * view.h;
+      apply();
+    }
+    function onPointerUp(event) {
+      panning = null;
+      svg.releasePointerCapture?.(event.pointerId);
+      svg.style.cursor = frozen ? "" : "grab";
+    }
+    svg.addEventListener("wheel", onWheel, { passive: false });
+    svg.addEventListener("pointerdown", onPointerDown);
+    svg.addEventListener("pointermove", onPointerMove);
+    svg.addEventListener("pointerup", onPointerUp);
+    svg.addEventListener("pointercancel", onPointerUp);
+    function setFrozen(next) {
+      frozen = !!next;
+      panning = null;
+      svg.style.cursor = frozen ? "" : "grab";
+      svg.style.touchAction = frozen ? "" : "none";
+    }
+    setFrozen(false);
+    return { reset, setFrozen };
+  }
+  function safeBBox(svg) {
+    try {
+      return svg.getBBox();
+    } catch {
+      return null;
+    }
+  }
+  function readViewBox(svg) {
+    const raw = svg.getAttribute?.("viewBox");
+    if (!raw) return null;
+    const parts = raw.trim().split(/[\s,]+/).map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) return null;
+    return { x: parts[0], y: parts[1], w: parts[2], h: parts[3] };
+  }
+  function enhanceMermaid() {
+    for (const svg of findMermaidSvgs()) {
+      if (mermaidViewports.has(svg)) continue;
+      const viewport = createViewport(svg);
+      if (viewport) {
+        viewport.setFrozen(annotationMode);
+        mermaidViewports.set(svg, viewport);
+      }
+    }
+  }
+  let mermaidEnhanceScheduled = false;
+  function scheduleMermaidEnhance() {
+    if (mermaidEnhanceScheduled) return;
+    mermaidEnhanceScheduled = true;
+    const run2 = () => {
+      mermaidEnhanceScheduled = false;
+      enhanceMermaid();
+    };
+    if (typeof window.requestAnimationFrame === "function") window.requestAnimationFrame(run2);
+    else window.setTimeout(run2, 50);
+  }
+  function setMermaidFrozen(frozen) {
+    for (const svg of findMermaidSvgs()) {
+      mermaidViewports.get(svg)?.setFrozen(frozen);
+    }
   }
   function closestElement(node) {
     if (!node) return document.body;
@@ -4465,6 +4663,7 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     }
     if (!annotationMode && style) style.remove();
     if (!annotationMode) closeCard();
+    setMermaidFrozen(annotationMode);
   }
   function queuePrompt(prompt, options = {}) {
     const originElement = options.element || document.activeElement || document.body;
@@ -4832,17 +5031,20 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     const root = ensureShadow();
     closeCard();
     const c = options.context || context(target);
+    let anchor = target;
     if (options.range) {
       highlightTextRange(options.range);
     } else {
-      selected = target;
+      anchor = annotationTargetEl(target);
+      selected = anchor;
       highlightElement(selected);
     }
-    const rect = options.range ? options.range.getBoundingClientRect() : target.getBoundingClientRect();
+    const rect = options.range ? options.range.getBoundingClientRect() : anchor.getBoundingClientRect();
     const card = document.createElement("div");
     card.className = "lavish-annotation-card";
-    const heading = c.tag === "text" ? "Annotate text" : "Annotate &lt;" + c.tag + "&gt;";
-    const placeholder = c.tag === "text" ? "Tell the agent what to change about this text..." : "Tell the agent what to change about this element...";
+    const nodeLabel = c.tag === "mermaid-node" ? c.target?.label || c.text || "" : "";
+    const heading = c.tag === "text" ? "Annotate text" : c.tag === "mermaid-node" ? "Annotate node" + (nodeLabel ? ": " + escapeAnnotationText(nodeLabel) : "") : "Annotate &lt;" + c.tag + "&gt;";
+    const placeholder = c.tag === "text" ? "Tell the agent what to change about this text..." : c.tag === "mermaid-node" ? "Tell the agent what to change about this diagram node..." : "Tell the agent what to change about this element...";
     card.innerHTML = '<div class="lavish-heading">' + heading + '</div><textarea placeholder="' + placeholder + '"></textarea><div class="lavish-hint">Enter to queue &middot; ' + (/Mac|iP(hone|ad|od)/.test(navigator.platform) ? "\u2318" : "Ctrl") + '+Enter to send now</div><div class="lavish-row"><button class="lavish-cancel" type="button">Cancel</button><button class="lavish-send" type="button">Queue</button></div>';
     root.appendChild(card);
     const left = Math.min(Math.max(12, rect.left), window.innerWidth - card.offsetWidth - 12);
@@ -4896,6 +5098,15 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
       window.scrollTo(Number(msg.x) || 0, Number(msg.y) || 0);
     }
   });
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if (!isModeToggleHotkeyEvent(event)) return;
+      event.preventDefault();
+      parent.postMessage({ type: "lavish:toggleAnnotationMode" }, "*");
+    },
+    true
+  );
   let scrollFrame = 0;
   window.addEventListener(
     "scroll",
@@ -4913,9 +5124,10 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
     (event) => {
       if (!annotationMode || isLavishUi(event.target) || isLavishAction(event.target) || isInteractiveControl(event.target))
         return;
-      if (event.target === selected) return;
+      const target = annotationTargetEl(event.target);
+      if (target === selected) return;
       if (hovered && hovered !== selected) clearHighlight(hovered);
-      hovered = event.target;
+      hovered = target;
       highlightElement(hovered);
     },
     true
@@ -4963,6 +5175,12 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
   } else {
     startLayoutAudit();
   }
+  enhanceMermaid();
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", enhanceMermaid, { once: true });
+  }
+  const mermaidObserver = new MutationObserver(() => scheduleMermaidEnhance());
+  mermaidObserver.observe(document.documentElement, { childList: true, subtree: true });
 }
 
 // src/html-transform.js
@@ -5027,13 +5245,16 @@ var SessionStore = class {
       return null;
     }
     const prompts = Array.isArray(payload.prompts) ? payload.prompts : [];
+    const shouldEndSession = Boolean(payload.endSession || payload.end_session);
+    const alreadyEnded = session.status === "ended";
     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.status = shouldEndSession || alreadyEnded ? "ended" : "feedback";
+    if (shouldEndSession) session.ended_by = "user";
     session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
     await this.writeState(state);
     return session;
@@ -5078,14 +5299,18 @@ var SessionStore = class {
     }
     const prompts = session.prompts || [];
     const layoutWarnings = session.layout_warnings || [];
+    const alreadyEnded = session.status === "ended";
     if (prompts.length === 0 && layoutWarnings.length === 0) {
-      return session.status === "ended" ? { status: "ended" } : { status: "waiting" };
+      return alreadyEnded ? { status: "ended", ended_by: session.ended_by } : { status: "waiting" };
     }
     const result = {
       status: "feedback",
       dom_snapshot: session.dom_snapshot || "",
       prompts,
-      ...layoutWarnings.length > 0 ? { layout_warnings: layoutWarnings } : {}
+      ...layoutWarnings.length > 0 ? { layout_warnings: layoutWarnings } : {},
+      // This is the final delivery before the session shows as ended - flag it so the agent
+      // knows not to expect (or force) a reopened browser afterward.
+      ...alreadyEnded ? { session_ended: true, ended_by: session.ended_by } : {}
     };
     session.prompts = [];
     session.layout_warnings = [];
@@ -5096,20 +5321,26 @@ var SessionStore = class {
       for (const warning of layoutWarnings) deliveredKeys.add(layoutWarningKey(warning));
       session.delivered_layout_warning_keys = [...deliveredKeys].slice(-200);
     }
-    if (session.status !== "ended") {
+    if (!alreadyEnded) {
       session.status = "open";
     }
     session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
     await this.writeState(state);
     return result;
   }
-  async endSession(key) {
+  // `endedBy` distinguishes a human ending review from the browser chrome ("user") from an
+  // agent explicitly closing the loop via `lavish-axi end` ("agent"). Only a user-initiated end
+  // blocks a plain reopen - see `SessionStore` callers in server.js.
+  async endSession(key, endedBy = "agent") {
     const state = await this.readState();
     const session = state.sessions[key];
     if (!session) {
       return null;
     }
+    const existingEndedBy = session.status === "ended" ? session.ended_by : void 0;
+    const nextEndedBy = endedBy === "user" || existingEndedBy === "user" ? "user" : "agent";
     session.status = "ended";
+    session.ended_by = nextEndedBy;
     session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
     await this.writeState(state);
     return session;
@@ -5185,6 +5416,7 @@ function normalizeFiniteNumber(value) {
 }
 function normalizeTarget(target) {
   if (!target || typeof target !== "object" || Array.isArray(target)) return null;
+  if (target.type === "mermaid-node") return normalizeMermaidNodeTarget(target);
   return JSON.parse(JSON.stringify(target));
 }
 
@@ -5256,9 +5488,15 @@ async function serve({
     try {
       const file = await canonicalFile(req.body.file);
       const key = sessionKey(file);
+      const reopen = Boolean(req.body.reopen);
+      const existing = await store.findByKey(key);
+      if (existing?.status === "ended" && existing.ended_by === "user" && !reopen) {
+        logEvent?.(`session open blocked (user-ended) key=${key} file=${file}`);
+        res.json({ key, file, url: existing.url, status: "user-ended" });
+        return;
+      }
       const sessionUrl = `http://${hostForUrl(linkHostName)}:${publicPort}/session/${key}`;
       const url = shouldDisableLayoutGateOpen(req.body || {}) ? appendNoGateParam(sessionUrl) : sessionUrl;
-      const existing = await store.findByKey(key);
       const session = await store.upsertSession(file, sessionUrl);
       if (existing?.status === "ended") {
         clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
@@ -5344,13 +5582,16 @@ async function serve({
   });
   app.post("/api/:key/prompts", async (req, res, next) => {
     try {
+      const shouldEndSession = Boolean(req.body?.endSession || req.body?.end_session);
       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);
+      if (shouldEndSession) clearFeedbackDelivery(req.params.key, activePolls, deliveredFeedback, events);
+      events.emit(shouldEndSession ? "ended" : "feedback", req.params.key);
       res.json({ status: "queued", pending_prompts: session.pending_prompts });
+      if (shouldEndSession) await shutdownIfNoLiveSessions();
     } catch (error) {
       next(error);
     }
@@ -5372,7 +5613,7 @@ async function serve({
   });
   app.post("/api/:key/end", async (req, res, next) => {
     try {
-      await store.endSession(req.params.key);
+      await store.endSession(req.params.key, "user");
       clearFeedbackDelivery(req.params.key, activePolls, deliveredFeedback, events);
       events.emit("ended", req.params.key);
       res.json({ status: "ended" });
@@ -5459,7 +5700,7 @@ async function serve({
     try {
       const file = await canonicalFile(req.body.file);
       const key = sessionKey(file);
-      await store.endSession(key);
+      await store.endSession(key, "agent");
       clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
       events.emit("ended", key);
       res.json({ status: "ended" });
@@ -5905,11 +6146,14 @@ function createChromeHtml(session, { layoutGateEnabled = true } = {}) {
     key: session.key,
     file: session.file,
     initialChat: session.chat || [],
-    layoutGateEnabled
+    layoutGateEnabled,
+    modeToggleHotkeyKey: MODE_TOGGLE_HOTKEY_KEY
   });
   const { head: pathHead, tail: pathTail } = displayPathParts(session.file);
   const bodyClass = layoutGateEnabled ? "lavish layout-gate-active" : "lavish";
   const layoutGateHidden = layoutGateEnabled ? "" : " hidden";
+  const modeHotkeyUpper = MODE_TOGGLE_HOTKEY_KEY.toUpperCase();
+  const modeToggleHint = `Toggle annotate/explore mode (\u2318${modeHotkeyUpper} / Ctrl+${modeHotkeyUpper})`;
   return `<!doctype html>
 <html>
 <head>
@@ -5919,7 +6163,7 @@ function createChromeHtml(session, { layoutGateEnabled = true } = {}) {
 <link rel="stylesheet" href="/chrome.css">
 </head>
 <body class="${bodyClass}">
-<div class="bar"><div class="brand"><span class="brand-mark">Lavish</span><span class="brand-support">Editor</span></div><div class="spacer" aria-hidden="true"></div><button class="annotate-switch" id="annotation" type="button" aria-pressed="true"><span class="switch-track" aria-hidden="true"><span class="switch-knob"></span></span><span>Annotate</span></button><div class="more-wrap" id="moreWrap"><button class="more-button" id="moreButton" type="button" title="More" aria-haspopup="menu" aria-expanded="false">${chromeIcons.more}</button><div class="menu more-menu" id="moreMenu" hidden><div class="menu-head"><div class="menu-label">Editing</div><button class="menu-file" id="copyPath" type="button" title="Copy path \xB7 ${escapeHtml(session.file)}">${chromeIcons.file}<span class="menu-file-text"><span class="path-head">${escapeHtml(pathHead)}</span><span class="path-tail">${escapeHtml(pathTail)}</span></span><span class="copy-hint" id="copyHint"><span class="icon-copy">${chromeIcons.copy}</span><span class="icon-check">${chromeIcons.check}</span><span id="copyHintText">Copy</span></span></button></div><div class="menu-rule"></div><button class="menu-item" id="reloadArtifact" type="button">${chromeIcons.refresh}<span>Reload artifact</span></button><button class="menu-item" id="copySnapshot" type="button">${chromeIcons.camera}<span>Copy DOM snapshot</span></button><button class="menu-item" id="exportArtifact" type="button">${chromeIcons.download}<span>Export standalone HTML</span></button><button class="menu-item" id="shareArtifact" type="button">${chromeIcons.globe}<span>Publish link</span></button><div class="menu-rule"></div><button class="menu-item danger" id="end" type="button">${chromeIcons.exit}<span>End session</span></button></div></div></div>
+<div class="bar"><div class="brand"><span class="brand-mark">Lavish</span><span class="brand-support">Editor</span></div><div class="spacer" aria-hidden="true"></div><button class="annotate-switch" id="annotation" type="button" aria-pressed="true" title="${escapeHtml(modeToggleHint)}"><span class="switch-track" aria-hidden="true"><span class="switch-knob"></span></span><span>Annotate</span></button><div class="more-wrap" id="moreWrap"><button class="more-button" id="moreButton" type="button" title="More" aria-haspopup="menu" aria-expanded="false">${chromeIcons.more}</button><div class="menu more-menu" id="moreMenu" hidden><div class="menu-head"><div class="menu-label">Editing</div><button class="menu-file" id="copyPath" type="button" title="Copy path \xB7 ${escapeHtml(session.file)}">${chromeIcons.file}<span class="menu-file-text"><span class="path-head">${escapeHtml(pathHead)}</span><span class="path-tail">${escapeHtml(pathTail)}</span></span><span class="copy-hint" id="copyHint"><span class="icon-copy">${chromeIcons.copy}</span><span class="icon-check">${chromeIcons.check}</span><span id="copyHintText">Copy</span></span></button></div><div class="menu-rule"></div><button class="menu-item" id="reloadArtifact" type="button">${chromeIcons.refresh}<span>Reload artifact</span></button><button class="menu-item" id="copySnapshot" type="button">${chromeIcons.camera}<span>Copy DOM snapshot</span></button><button class="menu-item" id="exportArtifact" type="button">${chromeIcons.download}<span>Export standalone HTML</span></button><button class="menu-item" id="shareArtifact" type="button">${chromeIcons.globe}<span>Publish link</span></button><div class="menu-rule"></div><button class="menu-item danger" id="end" type="button">${chromeIcons.exit}<span>End session</span></button></div></div></div>
 <div class="layout"><div class="frame"><iframe id="artifact" sandbox="allow-scripts allow-forms allow-popups allow-downloads" data-artifact-src="/artifact/${session.key}/index.html"></iframe><div class="layout-issue-banner" id="layoutIssueBanner" hidden>This surface may have layout issues. Your agent has been notified.</div></div><aside class="panel"><h2>Conversation</h2><div class="chat" id="chatLog"></div><div class="composer"><div class="presence-banner" id="presenceBanner" hidden>Your agent is not listening. If this persists, ask your agent to poll for updates from Lavish.</div><div class="annotation-pills" id="annotationPills"></div><textarea id="chatInput" placeholder="Write a message for the agent..."></textarea><div class="actions" id="sendActions"><span class="send-hint" id="sendHint" hidden>Write a message or annotate an element first.</span><div class="split"><button class="button send-main" id="send">Send to Agent</button><button class="button send-caret" id="sendCaret" type="button" title="Send options" aria-haspopup="menu" aria-expanded="false">${chromeIcons.caret}</button></div><div class="menu send-menu" id="sendMenu" hidden><button class="menu-item" id="sendFromMenu" type="button">${chromeIcons.send}<span>Send to Agent</span></button><button class="menu-item danger" id="sendAndEnd" type="button">${chromeIcons.exit}<span>Send &amp; end session</span></button></div></div></div></aside></div>
 <div class="share-overlay" id="shareDialog" role="dialog" aria-modal="true" aria-labelledby="shareTitleText" hidden><form class="share-card" id="shareForm"><div class="share-head"><div><div class="share-kicker">Publish to <a class="share-link" href="https://ht-ml.app" target="_blank" rel="noopener noreferrer">ht-ml.app</a></div><h2 id="shareTitleText">Publish artifact</h2></div><button class="share-close" id="shareClose" type="button" aria-label="Close publish dialog"><svg width="14" height="14" viewBox="0 0 10 10" fill="none" aria-hidden="true" focusable="false"><path d="M1 1L9 9M9 1L1 9" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button></div><p class="share-note">ht-ml.app is a separate, third-party hosting service, not part of Lavish. Publishing sends this artifact to its servers.</p><p class="share-copy">This uploads this artifact to ht-ml.app with local assets inlined. Without a password, the page is PUBLIC and anyone with the link can open it. With a password, the page is PRIVATE and viewers must supply the password to view.</p><p class="share-note">Do not publish secrets. The Lavish annotation SDK is not included.</p><div class="share-grid"><label>Password (optional)<input id="sharePassword" name="password" type="password" autocomplete="new-password" placeholder="Leave blank for a public page"></label></div><div class="share-status" id="shareStatus" role="status"></div><div class="share-result" id="shareResult" hidden><label>Share URL<div class="share-copy-row"><input id="shareUrl" readonly><button class="share-copy-btn" id="copyShareUrl" type="button">Copy URL</button></div></label><label>Update key (secret)<div class="share-copy-row"><input id="shareUpdateKey" readonly><button class="share-copy-btn" id="copyUpdateKey" type="button">Copy key</button></div></label><p class="share-note">Keep the update key private. ht-ml.app returns it once and it is the only way to update or delete this page later.</p></div><div class="share-actions"><button class="share-cancel" id="shareCancel" type="button">Cancel</button><button class="button" id="sharePublish" type="submit">Publish</button></div></form></div>
 <div class="ended-overlay layout-gate-overlay" id="layoutGateOverlay"${layoutGateHidden}><div class="ended-card"><div class="ended-title" id="layoutGateTitle">Checking layout.<br>One moment.</div><p class="ended-copy" id="layoutGateCopy">Lavish is waiting for fonts and final geometry before revealing this artifact.</p><button class="button ended-action" id="layoutGateAction" type="button">Show anyway</button></div></div>
@@ -5930,16 +6174,23 @@ function createChromeHtml(session, { layoutGateEnabled = true } = {}) {
 </html>`;
 }
 function createSdkJs(key) {
+  const mermaidHelperEntries = Object.entries(mermaid_node_exports).filter(([, value]) => typeof value === "function");
+  const mermaidHelperDecls = mermaidHelperEntries.map(([name, fn]) => `const ${name}=${fn.toString()};`).join("\n");
+  const mermaidHelperKeys = mermaidHelperEntries.map(([name]) => name).join(", ");
   return `(() => {
 const key=${JSON.stringify(key)};
 void key;
 const deriveQueueKey=${deriveLavishQueueKey.toString()};
 const isNativeInteractiveControl=${isNativeInteractiveControl.toString()};
+const MODE_TOGGLE_HOTKEY_KEY=${JSON.stringify(MODE_TOGGLE_HOTKEY_KEY)};
+const isModeToggleHotkeyEvent=${isModeToggleHotkeyEvent.toString()};
 const fragmentsSignificantlyOverlap=${fragmentsSignificantlyOverlap.toString()};
 const resolveVisibleSpillCandidates=${resolveVisibleSpillCandidates.toString()};
 const classifyHorizontalOverflow=${classifyHorizontalOverflow.toString()};
 const classifyVerticalOverflow=${classifyVerticalOverflow.toString()};
-(${createArtifactSdk.toString()})(deriveQueueKey, isNativeInteractiveControl);
+${mermaidHelperDecls}
+const mermaidHelpers={ ${mermaidHelperKeys} };
+(${createArtifactSdk.toString()})(deriveQueueKey, isNativeInteractiveControl, mermaidHelpers);
 })();`;
 }
 function escapeHtml(value) {
@@ -6125,7 +6376,7 @@ function normalizePagePath(path6) {
 var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "stop", "server", "playbook", "design", "setup", "export", "share"]);
 var RESERVED = new Set(RESERVED_COMMANDS);
 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.34";
+var VERSION = "0.1.36";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -6217,11 +6468,11 @@ function createHomeOutput({ bin, sessions, includeSessions = true }) {
     ],
     playbooks: listPlaybooks(),
     help: [
-      "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session",
+      "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session. If the user explicitly ended the session from the browser, this refuses to reopen it and explains why instead of reopening uninvited - pass `--reopen` only when the user asks for further review or something important needs their visual attention",
       "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 or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost",
-      "Run `lavish-axi end <html-file>` to end a session",
+      "Run `lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead",
+      "Run `lavish-axi end <html-file>` to end a session as the agent - ending it this way still allows a plain reopen later. When the user ends it from the browser instead, a later `lavish-axi <html-file>` refuses to reopen it without `--reopen`",
       "Run `lavish-axi export <html-file> [--out <path>]` to write a portable copy of the artifact - one HTML file with its LOCAL assets inlined - so it opens with no Lavish server and no sibling files. Remote CDN/font references are left as links, so it needs network to render those. Users can also export from the browser chrome's overflow menu",
       "Run `lavish-axi share <html-file> [--password <pw>] [--token <t>]` to publish the artifact on ht-ml.app (https://ht-ml.app), a third-party hosting service not part of Lavish, and get back a visitable URL. Shares are PUBLIC by default, so anyone with the link can open them. Pass --password to publish a PRIVATE password-protected page; viewers must supply the password to view. Local assets are inlined; remote refs load over the network. It returns the url plus a secret update_key for managing the page later. Use --token or LAVISH_AXI_HTML_APP_TOKEN only when you have an optional bearer token; it is never required. Users can also publish from the browser chrome's overflow menu",
       "Run `lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)",
@@ -6250,7 +6501,13 @@ function createPlaybookOutput(args) {
 function createOpenOutput({ file, url, status }) {
   return {
     session: { file, url, status },
-    next_step: `Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or the real browser reports layout_warnings from the in-iframe layout audit, and it stays silent the whole time - that is normal, never kill it. If layout_warnings arrive, follow the poll response's next_step: fix and re-check fresh error-severity overflow or clipped-text findings before involving the human, but persistent or low-severity warnings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if the poll still gets killed or times out, just re-run it - queued feedback is never lost. 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.`
+    next_step: `Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or the real browser reports layout_warnings from the in-iframe layout audit, and it stays silent the whole time - that is normal, never kill it. If layout_warnings arrive, follow the poll response's next_step: fix and re-check fresh error-severity overflow or clipped-text findings before involving the human, but persistent or low-severity warnings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if the poll still gets killed or times out, just re-run it - queued feedback is never lost. 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. If the user ends the session, stop polling and do not reopen it by re-running \`lavish-axi ${file}\` unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
+  };
+}
+function createUserEndedOpenOutput({ file, url }) {
+  return {
+    session: { file, url, status: "user-ended" },
+    next_step: `The user explicitly ended this Lavish Editor session from the browser, so \`lavish-axi ${file}\` did not reopen it. Do not reopen unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
   };
 }
 async function openCommand(args) {
@@ -6261,8 +6518,12 @@ async function openCommand(args) {
   await assertHtmlFile(file);
   const absolute = await canonicalFile(file);
   const noGate = args.includes("--no-gate");
+  const reopen = args.includes("--reopen");
   const baseUrl = await ensureServer({ forceRestart: shouldForceRestartForLocalBuild(process.argv[1] || "") });
-  const response = await postJson(`${baseUrl}/api/sessions`, { file: absolute, noGate });
+  const response = await postJson(`${baseUrl}/api/sessions`, { file: absolute, noGate, reopen });
+  if (response.status === "user-ended") {
+    return createUserEndedOpenOutput({ file: absolute, url: response.url });
+  }
   if (shouldOpenBrowser(args, process.env)) {
     try {
       const open = (await import("open")).default;
@@ -6350,24 +6611,40 @@ function createPollOutput({ file, response }) {
   }
   if (response.status === "feedback") {
     const layoutWarnings = Array.isArray(response.layout_warnings) ? response.layout_warnings : [];
+    const sessionEnded = Boolean(response.session_ended);
+    const endedBy = typeof response.ended_by === "string" ? response.ended_by : void 0;
     return {
-      session: { file, status: "feedback" },
+      session: {
+        file,
+        status: "feedback",
+        ...sessionEnded ? { session_ended: true, ...endedBy ? { ended_by: endedBy } : {} } : {}
+      },
       dom_snapshot: response.dom_snapshot || "",
       prompts: response.prompts || [],
       ...layoutWarnings.length > 0 ? { layout_warnings: layoutWarnings } : {},
-      next_step: createFeedbackNextStep(file, layoutWarnings)
+      next_step: createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy)
     };
   }
   if (response.status === "ended") {
-    return { session: { file, status: "ended" } };
+    return {
+      session: { file, status: "ended", ...response.ended_by ? { ended_by: response.ended_by } : {} },
+      next_step: createEndedNextStep(file, response.ended_by)
+    };
   }
   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 - queued feedback is never lost, so re-running the poll is always safe.`
   };
 }
-function createFeedbackNextStep(file, layoutWarnings) {
+function createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy) {
   const count = layoutWarnings.length;
+  if (sessionEnded) {
+    const layoutNote = count > 0 ? `${count} layout warning${count === 1 ? "" : "s"} arrived alongside this final feedback. ` : "";
+    if (endedBy === "user") {
+      return `${layoutNote}This was the last feedback before the user ended the session. Stop polling ${file} and do not reopen it - deliver any remaining updates directly in this conversation instead. Only run \`lavish-axi ${file} --reopen\` if the user explicitly asks for further review or something genuinely important needs their visual attention.`;
+    }
+    return `${layoutNote}This was the last feedback before the Lavish Editor session ended. Stop polling ${file}. Deliver any remaining updates directly in this conversation, or run \`lavish-axi ${file}\` to open a fresh session if the user needs further visual review.`;
+  }
   const layoutPrefix = count > 0 ? layoutWarningsPrefix(file, layoutWarnings) : `Apply the requested changes to ${file}. `;
   return `${layoutPrefix}Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms unless the user ended the session. The poll waits silently until the user sends more feedback, ends the session, or reports fresh layout_warnings - never kill it. If your harness limits how long a foreground command may run, run the poll as a background task; if it still gets killed or times out, just re-run it - queued feedback is never lost.`;
 }
@@ -6386,7 +6663,13 @@ function layoutWarningsPrefix(file, layoutWarnings) {
   if (allRepeatOrLowSeverity) {
     return `${count} layout warning${plural} detected, with no fresh error-severity findings - fix any obvious low-severity issue in ${file}, otherwise it is fine to proceed to the human with a note instead of iterating further. `;
   }
-  return `${count} layout warning${plural} detected - fix horizontal overflow or clipped text in ${file}, then reload or re-open the artifact and re-check before involving the human. `;
+  return `${count} layout warning${plural} detected - fix horizontal overflow or clipped text in ${file}, then re-check in the browser before involving the human. Lavish live-reloads the artifact automatically after you save, so you do not need to re-run \`lavish-axi ${file}\` for this. `;
+}
+function createEndedNextStep(file, endedBy) {
+  if (endedBy === "user") {
+    return `The user ended this Lavish Editor session. Stop polling ${file} - do not run \`lavish-axi ${file}\` to reopen it. Deliver any remaining updates directly in this conversation instead. Only reopen with \`lavish-axi ${file} --reopen\` if the user explicitly asks for further review or something genuinely important needs their visual attention.`;
+  }
+  return `This Lavish Editor session for ${file} has ended. Stop polling. Deliver any remaining updates directly in this conversation, or run \`lavish-axi ${file}\` to open a fresh session if the user needs further visual review.`;
 }
 async function endCommand(args) {
   const file = firstPositionalArg(args);
@@ -6910,7 +7193,7 @@ var TOP_LEVEL_HELP = `lavish-axi - Lavish Editor AXI
 
 Usage:
   lavish-axi
-  lavish-axi <html-file> [--no-open] [--no-gate]
+  lavish-axi <html-file> [--no-open] [--no-gate] [--reopen]
   lavish-axi poll <html-file> [--agent-reply "..."]
   lavish-axi end <html-file>
   lavish-axi export <html-file> [--out <path>]
@@ -6922,21 +7205,21 @@ Usage:
 
 ${DESIGN_SYSTEM_HINT}
 
-Note: poll long-polls indefinitely by default until the user sends feedback, ends the session, or the browser reports fresh layout_warnings, staying silent while it waits - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.
+Note: poll long-polls indefinitely by default until the user sends feedback, ends the session, or the browser reports fresh layout_warnings, staying silent while it waits - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When the user ends a session from the browser, stop polling and do not reopen it uninvited - pass --reopen to <html-file> only when the user asks for further review or something important needs their visual attention.
 
 `;
 var COMMAND_HELP = {
-  open: `Usage: lavish-axi <html-file> [--no-open] [--no-gate]
+  open: `Usage: lavish-axi <html-file> [--no-open] [--no-gate] [--reopen]
 
-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. Use --no-gate to skip the open-time layout curtain for this browser 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. Use --no-gate to skip the open-time layout curtain for this browser open. If the user explicitly ended the session from the browser, this refuses to reopen it and returns guidance instead - pass --reopen to force it open when the user asks for further review or something important needs their visual attention. Sessions ended by the agent (\`lavish-axi end\`) reopen normally without the flag.
 `,
   poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."]
 
-This command long-polls indefinitely for queued user prompts and browser-reported layout_warnings, then returns them to the agent. It stays silent while it waits - that is normal, never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if it still gets killed or times out, just re-run it - queued feedback is never lost. Use --agent-reply after applying prior feedback to display your response in Lavish Editor before waiting again.
+This command long-polls indefinitely for queued user prompts and browser-reported layout_warnings, then returns them to the agent. It stays silent while it waits - that is normal, never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if it still gets killed or times out, just re-run it - queued feedback is never lost. Use --agent-reply after applying prior feedback to display your response in Lavish Editor before waiting again. When status is ended, stop polling and do not reopen the session uninvited - deliver remaining updates directly in this conversation instead.
 `,
   end: `Usage: lavish-axi end <html-file>
 
-End a Lavish Editor session.
+End a Lavish Editor session as the agent. A session ended this way still reopens normally on the next \`lavish-axi <html-file>\`, unlike a user ending it from the browser, which requires --reopen.
 `,
   export: `Usage: lavish-axi export <html-file> [--out <path>]
 

package/package.json

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

package/skills/lavish/SKILL.md

@@ -37,6 +37,7 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 4. If poll returns `layout_warnings`, follow the returned `next_step`: fix and re-check fresh error-severity findings, but proceed with a note instead of looping when every current warning is persistent or low-severity.
 5. Apply human feedback, then poll again with `--agent-reply "<message>"` to reply in the browser and keep the loop going.
 6. Run `npx -y lavish-axi end <html-file>` when the review is finished.
+7. If the user ends the session from the browser instead, `npx -y lavish-axi <html-file>` refuses to reopen it and says so - only pass `--reopen` when the user asks for further review or something genuinely important needs their visual attention. Otherwise deliver remaining updates directly in this conversation.
 
 ## Visual guidance
 
@@ -62,11 +63,11 @@ For flows, architecture, state, or sequence diagrams, do not hand-build boxes-an
 
 ## Commands & rules
 
-- Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session
+- Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session. If the user explicitly ended the session from the browser, this refuses to reopen it and explains why instead of reopening uninvited - pass `--reopen` only when the user asks for further review or something important needs their visual attention
 - 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 `npx -y lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost
-- Run `npx -y lavish-axi end <html-file>` to end a session
+- Run `npx -y lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead
+- Run `npx -y lavish-axi end <html-file>` to end a session as the agent - ending it this way still allows a plain reopen later. When the user ends it from the browser instead, a later `npx -y lavish-axi <html-file>` refuses to reopen it without `--reopen`
 - Run `npx -y lavish-axi export <html-file> [--out <path>]` to write a portable copy of the artifact - one HTML file with its LOCAL assets inlined - so it opens with no Lavish server and no sibling files. Remote CDN/font references are left as links, so it needs network to render those. Users can also export from the browser chrome's overflow menu
 - Run `npx -y lavish-axi share <html-file> [--password <pw>] [--token <t>]` to publish the artifact on ht-ml.app (https://ht-ml.app), a third-party hosting service not part of Lavish, and get back a visitable URL. Shares are PUBLIC by default, so anyone with the link can open them. Pass --password to publish a PRIVATE password-protected page; viewers must supply the password to view. Local assets are inlined; remote refs load over the network. It returns the url plus a secret update_key for managing the page later. Use --token or LAVISH_AXI_HTML_APP_TOKEN only when you have an optional bearer token; it is never required. Users can also publish from the browser chrome's overflow menu
 - Run `npx -y lavish-axi stop` to shut down the background server (it also self-stops when idle or after the last session ends with nothing connected)