lavish-axi 0.1.31 → 0.1.32

package/README.md

@@ -117,8 +117,9 @@ pnpm link
         ▼
 ┌────────────────────────┐
 │ Human annotates text   │
-│ or elements, or        │
-│ sends chat feedback    │
+│ or elements, sends     │
+│ chat, or browser audit │
+│ reports layout issues  │
 └───────┬────────────────┘
         ▼
 ┌────────────────────────┐
@@ -128,21 +129,27 @@ pnpm link
 ```
 
 - **File-path identity** - Sessions are keyed by the canonical HTML file path, so agents do not need opaque IDs.
-- **Portable artifacts** - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, and feedback controls.
+- **Portable artifacts** - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, feedback controls, and render-time layout checks.
   Lavish does not inject any design system, so the saved HTML file renders identically whether you open it through `lavish-axi` or directly in a browser.
   Before writing HTML, choose a design system in strict priority order: follow a user-requested look first; otherwise inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's Tailwind or theme config, CSS variables or design tokens, component library, brand assets, or existing styled pages.
   If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo.
-  Only when both come up empty, run `lavish-axi design` for a copy-pasteable Tailwind CSS v4 + DaisyUI v5 CDN fallback.
-  That fallback guidance recommends DaisyUI's `luxury` theme by default and warns not to `@apply` DaisyUI classes inside Tailwind browser-runtime style blocks.
+  Only when both come up empty, run `lavish-axi design` for a copy-pasteable Tailwind CSS v4 + DaisyUI v5 CDN fallback, a content-to-playbook router, and Mermaid diagram tooling.
+  That fallback guidance recommends DaisyUI's `luxury` theme by default, warns not to `@apply` DaisyUI classes inside Tailwind browser-runtime style blocks, includes an optional layout safety CSS snippet for dense nested grid/flex layouts, and provides a pinned Mermaid CDN snippet with initialization for flows, architecture, state, and sequence diagrams.
+- **Open-time layout gate** - The browser chrome masks each artifact until the real in-iframe layout audit reports no error-severity findings.
+  Warning-only artifacts reveal normally; error findings notify the agent through the same `layout_warnings` poll path and keep the curtain up until a clean reload.
+  The user can click **Show anyway**, and a bounded safety timeout reveals with a persistent layout-issues banner so review is never blocked indefinitely.
+- **Layout warnings** - After fonts load and layout settles, the injected SDK audits the real browser render for page horizontal overflow, element overflow, clipped text, and overlapping text.
+  Intentional horizontal scrollers using `overflow-x: auto` or `scroll` are excluded.
+  Fresh warnings are returned from `lavish-axi poll` as `layout_warnings` with `selector`, `kind`, `overflowPx`, `viewportWidth`, and `severity`, so agents can fix unreadable layouts before asking the human to review.
 - **Local assets** - Copy local images, CSS, fonts, and scripts next to the HTML artifact and reference them with relative paths from that directory; root-prefixed paths such as `/assets/logo.png` will not resolve through Lavish's artifact route.
 - **Live reload** - Lavish watches the HTML artifact file by default and preserves the artifact iframe scroll position across reloads. To also reload on sibling asset changes, add `data-lavish-live-reload-root` to the root element or `<meta name="lavish-live-reload" content="root">`.
-- **Feedback controls** - Native form controls (radios, checkboxes, inputs, selects, buttons, labels, contenteditable) are interactive automatically, so they do not need `data-lavish-action`.
+- **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, end session) and can submit queued prompts with **Send & end session**, which delivers the prompts before ending the session.
 - **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.
-- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback for the next successful `lavish-axi poll` send even across reloads, and only blocks sending while the agent is working on delivered feedback. 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.
+- **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.
 - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
 - **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.
@@ -151,26 +158,30 @@ pnpm link
 
 ## 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; leave no-timeout polls running, or re-run them if interrupted. |
-| `lavish-axi end <html-file>`  | End a session.                                                                                                              |
-| `lavish-axi stop`             | Shut down the background server.                                                                                            |
-| `lavish-axi playbook [id]`    | List focused artifact guidance or show one playbook.                                                                        |
-| `lavish-axi design`           | Show the Tailwind + DaisyUI CDN fallback, including the `luxury` default theme and DaisyUI `@apply` warning.                |
-| `lavish-axi setup hooks`      | Install or repair optional SessionStart hooks for Claude Code, Codex, and OpenCode; restart the agent session afterward.    |
-| `lavish-axi server`           | Run the local Lavish Editor server.                                                                                         |
+| Command                       | Description                                                                                                                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 stop`             | Shut down the background server.                                                                                                                                            |
+| `lavish-axi playbook [id]`    | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML.                                                           |
+| `lavish-axi design`           | Show the Tailwind + DaisyUI CDN fallback, content-to-playbook router, Mermaid diagram tooling, `luxury` default theme, DaisyUI `@apply` warning, and layout safety snippet. |
+| `lavish-axi setup hooks`      | Install or repair optional SessionStart hooks for Claude Code, Codex, and OpenCode; restart the agent session afterward.                                                    |
+| `lavish-axi server`           | Run the local Lavish Editor server.                                                                                                                                         |
 
 Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.
-One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so read every playbook relevant to the artifact for the best quality.
+One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so agents must match against each `use_when` trigger and open every matching playbook before writing HTML.
+For flows, architecture, state, or sequence diagrams, open the diagram playbook and use the Mermaid tooling from `lavish-axi design` unless SVG is needed for richly annotated nodes; avoid hand-built div/flexbox boxes-and-arrows.
 
 ### Flags
 
 | Command                  | Flag                  | Description                                                                                                                                                                                                                         |
 | ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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 update`      | `--check`             | Report current vs latest npm version without installing an update.                                                                                                                                                                  |
 | `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 and leave the long poll running.                                                                                                                                       |
 | `lavish-axi stop`        | `--port <port>`       | Shut down a server running on a non-default port.                                                                                                                                                                                   |

package/dist/chrome-client.js

@@ -30,13 +30,31 @@ const copyHint = /** @type {HTMLSpanElement} */ (document.getElementById("copyHi
 const copyHintText = /** @type {HTMLSpanElement} */ (document.getElementById("copyHintText"));
 const presenceBanner = /** @type {HTMLDivElement} */ (document.getElementById("presenceBanner"));
 const endedOverlay = /** @type {HTMLDivElement} */ (document.getElementById("endedOverlay"));
+const layoutGateOverlay = /** @type {HTMLDivElement} */ (document.getElementById("layoutGateOverlay"));
+const layoutGateTitle = /** @type {HTMLDivElement} */ (document.getElementById("layoutGateTitle"));
+const layoutGateCopy = /** @type {HTMLParagraphElement} */ (document.getElementById("layoutGateCopy"));
+const layoutGateAction = /** @type {HTMLButtonElement} */ (document.getElementById("layoutGateAction"));
+const layoutIssueBanner = /** @type {HTMLDivElement} */ (document.getElementById("layoutIssueBanner"));
 const sendHint = /** @type {HTMLSpanElement} */ (document.getElementById("sendHint"));
+const artifactSrc = frame.dataset.artifactSrc || frame.getAttribute?.("data-artifact-src") || frame.src || "";
 
 const queued = loadQueuedPrompts();
 let annotation = true;
 let ended = false;
 let agentPresence = "waiting";
 let pendingSnapshot = "";
+const layoutGateEnabled = sessionData.layoutGateEnabled !== false;
+const configuredLayoutGateMaxHoldMs = Number(sessionData.layoutGateMaxHoldMs);
+const layoutGateMaxHoldMs =
+  Number.isFinite(configuredLayoutGateMaxHoldMs) && configuredLayoutGateMaxHoldMs > 0
+    ? Math.min(configuredLayoutGateMaxHoldMs, 60_000)
+    : 12_000;
+let layoutGateVisible = false;
+let layoutGateArmed = false;
+let layoutGateManuallyBypassed = !layoutGateEnabled;
+let layoutGateCycle = 0;
+/** @type {ReturnType<typeof setTimeout> | undefined} */
+let layoutGateTimer;
 const snapshotRequests = [];
 let endAfterSubmit = false;
 let workingBubble = null;
@@ -322,6 +340,122 @@ async function submitQueuedOnce() {
   if (agentPresence === "listening") setAgentPresence("working");
 }
 
+function normalizeLayoutWarningsPayload(value) {
+  return Array.isArray(value) ? value.filter((item) => item && typeof item === "object") : [];
+}
+
+function isErrorLayoutWarning(warning) {
+  return String(warning?.severity || "").toLowerCase() === "error";
+}
+
+function setLayoutIssueBanner(visible, text = "This surface may have layout issues. Your agent has been notified.") {
+  if (!layoutIssueBanner) return;
+  layoutIssueBanner.textContent = text;
+  layoutIssueBanner.hidden = !visible;
+}
+
+function clearLayoutGateTimer() {
+  if (layoutGateTimer) clearTimeout(layoutGateTimer);
+  layoutGateTimer = undefined;
+}
+
+function setLayoutGateCard(state) {
+  if (!layoutGateTitle || !layoutGateCopy) return;
+
+  if (state === "held") {
+    layoutGateTitle.innerHTML = "Fixing a layout issue...";
+    layoutGateCopy.textContent =
+      "The real browser found overflow or overlapping content. Your agent has been notified and this will reveal after the next clean reload.";
+    return;
+  }
+
+  layoutGateTitle.innerHTML = "Checking layout.<br>One moment.";
+  layoutGateCopy.textContent = "Lavish is waiting for fonts and final geometry before revealing this artifact.";
+}
+
+function setLayoutGateActive(active) {
+  layoutGateVisible = active;
+  if (layoutGateOverlay) layoutGateOverlay.hidden = !active;
+  document.body?.classList?.toggle("layout-gate-active", active);
+}
+
+function revealLayoutGate({ showBanner = false, bannerText = undefined } = {}) {
+  clearLayoutGateTimer();
+  layoutGateArmed = false;
+  setLayoutGateActive(false);
+  setLayoutIssueBanner(showBanner, bannerText);
+}
+
+function forceRevealLayoutGate(reason) {
+  if (!layoutGateEnabled || ended) return;
+  if (reason === "manual") layoutGateManuallyBypassed = true;
+  const bannerText =
+    reason === "timeout"
+      ? "This surface may have layout issues. Lavish revealed it after the safety timeout so review is never blocked."
+      : "This surface may have layout issues. You chose to show it before the layout check passed.";
+  revealLayoutGate({ showBanner: true, bannerText });
+}
+
+function startLayoutGateCycle() {
+  if (!layoutGateEnabled || layoutGateManuallyBypassed || ended) return;
+
+  layoutGateCycle += 1;
+  layoutGateArmed = true;
+  setLayoutIssueBanner(false);
+  setLayoutGateCard("checking");
+  setLayoutGateActive(true);
+  clearLayoutGateTimer();
+
+  const cycle = layoutGateCycle;
+  layoutGateTimer = setTimeout(() => {
+    if (cycle !== layoutGateCycle || !layoutGateVisible || ended) return;
+    forceRevealLayoutGate("timeout");
+  }, layoutGateMaxHoldMs);
+  layoutGateTimer?.unref?.();
+}
+
+function handleLayoutWarningsForGate(layoutWarnings) {
+  const warnings = normalizeLayoutWarningsPayload(layoutWarnings);
+  const hasErrors = warnings.some(isErrorLayoutWarning);
+
+  if (!layoutGateEnabled) return;
+
+  if (layoutGateManuallyBypassed) {
+    setLayoutIssueBanner(hasErrors);
+    return;
+  }
+
+  if (!layoutGateArmed && !layoutGateVisible) return;
+
+  if (!hasErrors) {
+    revealLayoutGate();
+    return;
+  }
+
+  setLayoutGateCard("held");
+  setLayoutGateActive(true);
+}
+
+function initializeLayoutGate() {
+  if (!layoutGateEnabled) {
+    setLayoutGateActive(false);
+    setLayoutIssueBanner(false);
+    return;
+  }
+
+  if (layoutGateAction) layoutGateAction.onclick = () => forceRevealLayoutGate("manual");
+  startLayoutGateCycle();
+}
+
+async function submitLayoutWarnings(layoutWarnings) {
+  const response = await fetch("/api/" + key + "/layout-warnings", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ layout_warnings: normalizeLayoutWarningsPayload(layoutWarnings) }),
+  });
+  if (!response.ok) throw new Error("failed to submit layout warnings");
+}
+
 async function endSession() {
   if (ended) return;
   const response = await fetch("/api/" + key + "/end", { method: "POST" });
@@ -333,6 +467,8 @@ async function endSession() {
   chatInput.disabled = true;
   updateSendState();
   if (presenceBanner) presenceBanner.hidden = true;
+  layoutGateManuallyBypassed = true;
+  revealLayoutGate();
   postToFrame({ type: "lavish:setAnnotationMode", enabled: false });
   endedOverlay.hidden = false;
 }
@@ -354,9 +490,13 @@ function copyDomSnapshot() {
 }
 
 function resetFrame() {
+  startLayoutGateCycle();
   // The iframe is sandboxed, so reload by resetting the iframe URL from chrome.
-  // eslint-disable-next-line no-self-assign
-  frame.src = frame.src;
+  frame.src = artifactSrc || frame.src;
+}
+
+function loadFrame() {
+  if (artifactSrc) frame.src = artifactSrc;
 }
 
 function reloadArtifact() {
@@ -404,10 +544,16 @@ window.addEventListener("message", (event) => {
   if (msg.type === "lavish:scroll") {
     lastScroll = { x: Number(msg.x) || 0, y: Number(msg.y) || 0 };
   }
+  if (msg.type === "lavish:layoutWarnings") {
+    handleLayoutWarningsForGate(msg.layout_warnings);
+    submitLayoutWarnings(msg.layout_warnings).catch(() => {});
+  }
   if (msg.type === "lavish:sendQueuedPrompts") sendQueued();
   if (msg.type === "lavish:endSession") endSession();
 });
 
+loadFrame();
+
 annotationSwitch.onclick = () => {
   annotation = !annotation;
   annotationSwitch.setAttribute("aria-pressed", String(annotation));
@@ -447,6 +593,8 @@ frame.addEventListener("load", () => {
   postToFrame({ type: "lavish:restoreScroll", x: lastScroll.x, y: lastScroll.y });
 });
 
+initializeLayoutGate();
+
 const events = new EventSource("/events/" + key);
 events.addEventListener("reload", () => resetFrame());
 events.addEventListener("chrome-reload", () => reloadAfterServerRestart());

package/dist/chrome.css

@@ -434,6 +434,8 @@ body.lavish {
   min-width: 0;
   min-height: 0;
   background: #fff;
+  position: relative;
+  overflow: hidden;
 }
 .panel {
   width: var(--panel-w);
@@ -685,11 +687,37 @@ body.lavish {
   line-height: 1.45;
   overflow-wrap: anywhere;
 }
+.ended-action {
+  margin-top: var(--space-8);
+}
+.layout-issue-banner {
+  position: absolute;
+  top: var(--space-8);
+  left: var(--space-8);
+  right: var(--space-8);
+  z-index: 20;
+  border: 1px solid rgba(244, 201, 93, 0.35);
+  border-radius: var(--radius-lg);
+  background: rgba(37, 35, 15, 0.92);
+  color: var(--brass-400);
+  padding: var(--space-6) var(--space-8);
+  font-size: var(--text-sm);
+  line-height: var(--lh-sm);
+  box-shadow: var(--shadow-tooltip);
+}
+.layout-issue-banner[hidden] {
+  display: none;
+}
 iframe {
   width: 100%;
   height: 100%;
   border: 0;
   background: white;
+  opacity: 1;
+  transition: opacity var(--dur-fast) var(--ease);
+}
+body.layout-gate-active iframe#artifact {
+  opacity: 0;
 }
 @media (max-width: 860px) {
   body {