lavish-axi 0.1.33 → 0.1.34

package/README.md

@@ -125,6 +125,7 @@ pnpm link
 ┌────────────────────────┐
 │ lavish-axi poll waits  │
 │ and returns prompts    │
+│ or layout warnings     │
 └────────────────────────┘
 ```
 
@@ -138,9 +139,10 @@ pnpm link
 - **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.
+- **Layout warnings** - After fonts load and layout settles, the injected SDK audits the real browser render for page horizontal overflow, element overflow, clipped or visibly spilling text, and overlapping text.
+  Intentional horizontal scrollers using `overflow-x: auto` or `scroll` are excluded from horizontal checks, and `overflow-y: auto` or `scroll` is treated as intentional for vertical overflow.
+  Current findings are returned from `lavish-axi poll` as `layout_warnings` with `selector`, `kind`, `overflowPx`, `viewportWidth`, `severity`, and `persistent`.
+  Fresh error-severity findings should be fixed and rechecked before asking the human to review; repeated or warning-only findings can be surfaced to the human with a note when the cause is not obvious.
 - **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.
 - **Export and sharing** - `lavish-axi export` writes `<name>.export.html` by inlining local assets only, stripping the annotation SDK, and leaving remote CDN/font references as links that still need network access.
   `lavish-axi share` publishes the same local-inlined HTML to [ht-ml.app](https://ht-ml.app), a third-party hosting service not part of Lavish.

package/dist/cli.mjs

@@ -4277,6 +4277,57 @@ function isNativeInteractiveControl(el) {
     "button,input,select,textarea,option,optgroup,label,summary,[contenteditable]:not([contenteditable='false'])"
   ));
 }
+function fragmentsSignificantlyOverlap(fragmentsA, fragmentsB, { minAreaRatio = 0.25, minAreaPx = 24 } = {}) {
+  function rectAreaOf(rect) {
+    return Math.max(0, rect.width) * Math.max(0, rect.height);
+  }
+  function intersectionAreaOf(a, b) {
+    const width = Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left));
+    const height = Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
+    return width * height;
+  }
+  for (const a of fragmentsA) {
+    const threshold = Math.min(rectAreaOf(a) * minAreaRatio, minAreaPx);
+    for (const b of fragmentsB) {
+      if (intersectionAreaOf(a, b) >= threshold) return true;
+    }
+  }
+  return false;
+}
+function classifyHorizontalOverflow({ scrollWidth, clientWidth, overflowX, hasText, isTruncated, epsilon = 1 }) {
+  const overflowPx = clientWidth > 0 ? scrollWidth - clientWidth : 0;
+  if (overflowPx <= epsilon) return null;
+  const clipsText = hasText && (overflowX === "hidden" || overflowX === "clip") && !isTruncated;
+  return { overflowPx, kind: clipsText ? "clipped-text" : "element-scroll-overflow" };
+}
+function classifyVerticalOverflow({ scrollHeight, clientHeight, overflowY, hasText, isTruncated, epsilon = 1 }) {
+  const overflowPx = clientHeight > 0 ? scrollHeight - clientHeight : 0;
+  if (overflowPx <= epsilon) return null;
+  const scrollable = overflowY === "auto" || overflowY === "scroll";
+  if (scrollable || !hasText || isTruncated) return null;
+  const clips = overflowY === "hidden" || overflowY === "clip";
+  return { overflowPx, kind: "clipped-text", clips };
+}
+function resolveVisibleSpillCandidates(spillCandidates, { epsilon = 1 } = {}) {
+  function spillBottomEdge(candidate) {
+    const explicit = Number(candidate.spillBottom);
+    if (Number.isFinite(explicit)) return explicit;
+    const rectBottom = Number(candidate.rect?.bottom);
+    const overflowPx = Number(candidate.overflowPx);
+    if (!Number.isFinite(rectBottom) || !Number.isFinite(overflowPx)) return null;
+    return rectBottom + overflowPx;
+  }
+  function sameSpillEdge(candidate, other) {
+    const candidateBottom = spillBottomEdge(candidate);
+    const otherBottom = spillBottomEdge(other);
+    return candidateBottom !== null && otherBottom !== null && Math.abs(candidateBottom - otherBottom) <= epsilon;
+  }
+  return spillCandidates.filter(
+    (candidate) => !spillCandidates.some(
+      (other) => other.el !== candidate.el && candidate.el.contains(other.el) && sameSpillEdge(candidate, other)
+    )
+  );
+}
 function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInteractiveControl) {
   let annotationMode = true;
   let hovered = null;
@@ -4475,11 +4526,6 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
   function rectArea(rect) {
     return Math.max(0, rect.width) * Math.max(0, rect.height);
   }
-  function intersectionArea(a, b) {
-    const width = Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left));
-    const height = Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
-    return width * height;
-  }
   function isVisibleForLayoutAudit(el, rect = el.getBoundingClientRect()) {
     if (!el || isLavishUi(el) || rect.width <= 0 || rect.height <= 0) return false;
     const style = getComputedStyle(el);
@@ -4543,31 +4589,56 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
   function isIntentionalTextTruncation(style) {
     return style.textOverflow === "ellipsis" || Number.parseInt(style.webkitLineClamp || "0", 10) > 0;
   }
-  function auditElementOverflow(el, viewportWidth, findings, seen) {
+  function auditElementOverflow(el, viewportWidth, findings, seen, spillCandidates) {
     if (el === document.body || el === document.documentElement || hasIntentionalHorizontalScrollerAncestor(el)) return;
     const rect = el.getBoundingClientRect();
     if (!isVisibleForLayoutAudit(el, rect)) return;
     const style = getComputedStyle(el);
-    const scrollOverflowPx = el.clientWidth > 0 ? el.scrollWidth - el.clientWidth : 0;
-    if (scrollOverflowPx > layoutAuditOverflowEpsilon) {
-      const clipsText = hasReadableText(el) && (style.overflowX === "hidden" || style.overflowX === "clip") && !isIntentionalTextTruncation(style);
+    const hasText = hasReadableText(el);
+    const isTruncated = isIntentionalTextTruncation(style);
+    const horizontal = classifyHorizontalOverflow({
+      scrollWidth: el.scrollWidth,
+      clientWidth: el.clientWidth,
+      overflowX: style.overflowX,
+      hasText,
+      isTruncated,
+      epsilon: layoutAuditOverflowEpsilon
+    });
+    if (horizontal) {
       pushLayoutFinding(findings, seen, {
         selector: selector(el),
-        kind: clipsText ? "clipped-text" : "element-scroll-overflow",
-        overflowPx: scrollOverflowPx,
+        kind: horizontal.kind,
+        overflowPx: horizontal.overflowPx,
         viewportWidth,
-        severity: clipsText ? "error" : overflowSeverity(scrollOverflowPx)
+        severity: horizontal.kind === "clipped-text" ? "error" : overflowSeverity(horizontal.overflowPx)
       });
     }
-    const verticalClipPx = el.clientHeight > 0 ? el.scrollHeight - el.clientHeight : 0;
-    if (verticalClipPx > layoutAuditOverflowEpsilon && hasReadableText(el) && (style.overflowY === "hidden" || style.overflowY === "clip") && !isIntentionalTextTruncation(style)) {
-      pushLayoutFinding(findings, seen, {
-        selector: selector(el),
-        kind: "clipped-text",
-        overflowPx: verticalClipPx,
-        viewportWidth,
-        severity: "error"
-      });
+    const vertical = classifyVerticalOverflow({
+      scrollHeight: el.scrollHeight,
+      clientHeight: el.clientHeight,
+      overflowY: style.overflowY,
+      hasText,
+      isTruncated,
+      epsilon: layoutAuditOverflowEpsilon
+    });
+    if (vertical) {
+      if (vertical.clips) {
+        pushLayoutFinding(findings, seen, {
+          selector: selector(el),
+          kind: vertical.kind,
+          overflowPx: vertical.overflowPx,
+          viewportWidth,
+          severity: "error"
+        });
+      } else {
+        spillCandidates.push({
+          el,
+          selector: selector(el),
+          overflowPx: vertical.overflowPx,
+          viewportWidth,
+          spillBottom: rect.bottom + vertical.overflowPx
+        });
+      }
     }
     const parent2 = el.parentElement;
     if (!parent2 || parent2 === document.body || parent2 === document.documentElement) return;
@@ -4585,36 +4656,56 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
       });
     }
   }
+  function resolveSpillCandidates(spillCandidates, findings, seen) {
+    for (const candidate of resolveVisibleSpillCandidates(spillCandidates, { epsilon: layoutAuditOverflowEpsilon })) {
+      pushLayoutFinding(findings, seen, {
+        selector: candidate.selector,
+        kind: "clipped-text",
+        overflowPx: candidate.overflowPx,
+        viewportWidth: candidate.viewportWidth,
+        severity: "error"
+      });
+    }
+  }
+  function elementLineFragments(el) {
+    const rects = [...el.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+    if (rects.length) return rects;
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0 ? [rect] : [];
+  }
   function auditOverlappingText(elements, viewportWidth, findings, seen) {
-    const candidates = elements.filter((el) => el.children.length === 0 && hasReadableText(el)).filter((el) => isVisibleForLayoutAudit(el)).slice(0, 200);
+    const candidates = elements.filter((el) => el.children.length === 0 && hasReadableText(el)).filter((el) => isVisibleForLayoutAudit(el)).filter((el) => getComputedStyle(el).position === "static").slice(0, 200);
     for (const el of candidates) {
-      const rect = el.getBoundingClientRect();
-      if (rectArea(rect) < 16) continue;
-      const points = [
-        { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
-        { x: rect.left + Math.min(4, rect.width / 2), y: rect.top + Math.min(4, rect.height / 2) },
-        { x: rect.right - Math.min(4, rect.width / 2), y: rect.bottom - Math.min(4, rect.height / 2) }
-      ];
-      for (const point of points) {
-        if (point.x < 0 || point.y < 0 || point.x > viewportWidth || point.y > window.innerHeight) continue;
-        const top = document.elementFromPoint(point.x, point.y);
-        if (!(top instanceof Element) || top === el || el.contains(top) || top.contains(el) || isLavishUi(top))
-          continue;
-        if (hasIntentionalHorizontalScrollerAncestor(top)) continue;
-        const elPosition = getComputedStyle(el).position;
-        const topPosition = getComputedStyle(top).position;
-        if (elPosition !== "static" || topPosition !== "static") continue;
-        const topRect = top.getBoundingClientRect();
-        const overlapArea = intersectionArea(rect, topRect);
-        if (overlapArea < Math.min(rectArea(rect) * 0.25, 24)) continue;
-        pushLayoutFinding(findings, seen, {
-          selector: selector(el),
-          kind: "overlapping-text",
-          overflowPx: 0,
-          viewportWidth,
-          severity: "error"
-        });
-        break;
+      const fragments = elementLineFragments(el);
+      let flagged = false;
+      for (const rect of fragments) {
+        if (flagged) break;
+        if (rectArea(rect) < 16) continue;
+        const points = [
+          { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+          { x: rect.left + Math.min(4, rect.width / 2), y: rect.top + Math.min(4, rect.height / 2) },
+          { x: rect.right - Math.min(4, rect.width / 2), y: rect.bottom - Math.min(4, rect.height / 2) }
+        ];
+        for (const point of points) {
+          if (point.x < 0 || point.y < 0 || point.x > viewportWidth || point.y > window.innerHeight) continue;
+          const top = document.elementFromPoint(point.x, point.y);
+          if (!(top instanceof Element) || top === el || el.contains(top) || top.contains(el) || isLavishUi(top))
+            continue;
+          if (hasIntentionalHorizontalScrollerAncestor(top)) continue;
+          if (getComputedStyle(top).position !== "static") continue;
+          if (!fragmentsSignificantlyOverlap([rect], elementLineFragments(top))) continue;
+          pushLayoutFinding(findings, seen, {
+            selector: selector(el),
+            kind: "overlapping-text",
+            overflowPx: 0,
+            viewportWidth,
+            // Heuristic and sampling-based even after fragment-aware matching, so it stays a
+            // warning rather than holding the open-time gate the way a real clip/overflow does.
+            severity: "warning"
+          });
+          flagged = true;
+          break;
+        }
       }
     }
   }
@@ -4633,7 +4724,9 @@ function createArtifactSdk(deriveQueueKey, isNativeInteractive = isNativeInterac
       });
     }
     const elements = collectLayoutAuditElements();
-    for (const el of elements) auditElementOverflow(el, viewportWidth, findings, seen);
+    const spillCandidates = [];
+    for (const el of elements) auditElementOverflow(el, viewportWidth, findings, seen, spillCandidates);
+    resolveSpillCandidates(spillCandidates, findings, seen);
     auditOverlappingText(elements, viewportWidth, findings, seen);
     return findings;
   }
@@ -4918,6 +5011,7 @@ var SessionStore = class {
       pending_prompts: existing.pending_prompts || 0,
       prompts: existingPrompts,
       layout_warnings: [],
+      delivered_layout_warning_keys: existing.delivered_layout_warning_keys || [],
       dom_snapshot: existing.dom_snapshot || "",
       chat: existing.chat || [],
       updated_at: (/* @__PURE__ */ new Date()).toISOString()
@@ -4950,13 +5044,23 @@ var SessionStore = class {
     if (!session) {
       return null;
     }
-    const layoutWarnings = normalizeLayoutWarnings(payload.layout_warnings || payload.layoutWarnings || []);
+    const deliveredWarningKeys = session.delivered_layout_warning_keys || [];
+    const deliveredKeys = new Set(deliveredWarningKeys);
+    const layoutWarnings = normalizeLayoutWarnings(
+      payload.layout_warnings || payload.layoutWarnings || [],
+      deliveredKeys
+    );
+    const activeWarningKeys = new Set(layoutWarnings.map(layoutWarningKey));
+    const nextDeliveredWarningKeys = deliveredWarningKeys.filter((key2) => activeWarningKeys.has(key2)).slice(-200);
+    const deliveredKeysChanged = nextDeliveredWarningKeys.length !== deliveredWarningKeys.length || nextDeliveredWarningKeys.some((key2, index) => key2 !== deliveredWarningKeys[index]);
     const previousSignature = JSON.stringify(session.layout_warnings || []);
     const nextSignature = JSON.stringify(layoutWarnings);
-    if (previousSignature === nextSignature) {
+    const warningsChanged = previousSignature !== nextSignature;
+    if (!warningsChanged && !deliveredKeysChanged) {
       return { session, changed: false, hasWarnings: layoutWarnings.length > 0 };
     }
     session.layout_warnings = layoutWarnings;
+    session.delivered_layout_warning_keys = nextDeliveredWarningKeys;
     if (layoutWarnings.length > 0 && session.status !== "ended") {
       session.status = "feedback";
     } else if ((session.prompts || []).length === 0 && session.status !== "ended") {
@@ -4964,7 +5068,7 @@ var SessionStore = class {
     }
     session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
     await this.writeState(state);
-    return { session, changed: true, hasWarnings: layoutWarnings.length > 0 };
+    return { session, changed: warningsChanged, hasWarnings: layoutWarnings.length > 0 };
   }
   async takeFeedback(key) {
     const state = await this.readState();
@@ -4987,6 +5091,11 @@ var SessionStore = class {
     session.layout_warnings = [];
     session.pending_prompts = 0;
     session.dom_snapshot = "";
+    if (layoutWarnings.length > 0) {
+      const deliveredKeys = new Set(session.delivered_layout_warning_keys || []);
+      for (const warning of layoutWarnings) deliveredKeys.add(layoutWarningKey(warning));
+      session.delivered_layout_warning_keys = [...deliveredKeys].slice(-200);
+    }
     if (session.status !== "ended") {
       session.status = "open";
     }
@@ -5052,15 +5161,23 @@ function normalizePrompt(prompt) {
   if (target) normalized.target = target;
   return normalized;
 }
-function normalizeLayoutWarnings(layoutWarnings) {
+function layoutWarningKey(warning) {
+  return `${warning.kind}:${warning.selector}`;
+}
+function normalizeLayoutWarnings(layoutWarnings, deliveredKeys = /* @__PURE__ */ new Set()) {
   if (!Array.isArray(layoutWarnings)) return [];
-  return layoutWarnings.filter((warning) => warning && typeof warning === "object" && !Array.isArray(warning)).map((warning) => ({
-    selector: String(warning.selector || ""),
-    kind: String(warning.kind || "layout-warning"),
-    overflowPx: normalizeFiniteNumber(warning.overflowPx),
-    viewportWidth: normalizeFiniteNumber(warning.viewportWidth),
-    severity: warning.severity === "warning" ? "warning" : "error"
-  }));
+  return layoutWarnings.filter((warning) => warning && typeof warning === "object" && !Array.isArray(warning)).map((warning) => {
+    const selector = String(warning.selector || "");
+    const kind = String(warning.kind || "layout-warning");
+    return {
+      selector,
+      kind,
+      overflowPx: normalizeFiniteNumber(warning.overflowPx),
+      viewportWidth: normalizeFiniteNumber(warning.viewportWidth),
+      severity: warning.severity === "warning" ? "warning" : "error",
+      persistent: deliveredKeys.has(layoutWarningKey({ kind, selector }))
+    };
+  });
 }
 function normalizeFiniteNumber(value) {
   const number = Number(value);
@@ -5818,6 +5935,10 @@ const key=${JSON.stringify(key)};
 void key;
 const deriveQueueKey=${deriveLavishQueueKey.toString()};
 const isNativeInteractiveControl=${isNativeInteractiveControl.toString()};
+const fragmentsSignificantlyOverlap=${fragmentsSignificantlyOverlap.toString()};
+const resolveVisibleSpillCandidates=${resolveVisibleSpillCandidates.toString()};
+const classifyHorizontalOverflow=${classifyHorizontalOverflow.toString()};
+const classifyVerticalOverflow=${classifyVerticalOverflow.toString()};
 (${createArtifactSdk.toString()})(deriveQueueKey, isNativeInteractiveControl);
 })();`;
 }
@@ -6004,7 +6125,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.33";
+var VERSION = "0.1.34";
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
@@ -6099,7 +6220,7 @@ function createHomeOutput({ bin, sessions, includeSessions = true }) {
       "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session",
       "Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`",
       "Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work",
-      "Run `lavish-axi poll <html-file>` to wait for user feedback 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 layout_warnings before involving the human. 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 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 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",
@@ -6129,7 +6250,7 @@ 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, fix overflow, clipped text, or overlapping unreadable content and re-check before involving the human. 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.`
   };
 }
 async function openCommand(args) {
@@ -6234,7 +6355,7 @@ function createPollOutput({ file, response }) {
       dom_snapshot: response.dom_snapshot || "",
       prompts: response.prompts || [],
       ...layoutWarnings.length > 0 ? { layout_warnings: layoutWarnings } : {},
-      next_step: createFeedbackNextStep(file, layoutWarnings.length)
+      next_step: createFeedbackNextStep(file, layoutWarnings)
     };
   }
   if (response.status === "ended") {
@@ -6245,10 +6366,28 @@ function createPollOutput({ file, response }) {
     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, layoutWarningCount) {
-  const layoutPrefix = layoutWarningCount > 0 ? `${layoutWarningCount} layout warning${layoutWarningCount === 1 ? "" : "s"} detected - fix horizontal overflow, clipped text, or overlapping unreadable content in ${file}, then reload or re-open the artifact and re-check before involving the human. ` : `Apply the requested changes to ${file}. `;
+function createFeedbackNextStep(file, layoutWarnings) {
+  const count = layoutWarnings.length;
+  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.`;
 }
+function layoutWarningsPrefix(file, layoutWarnings) {
+  const count = layoutWarnings.length;
+  const plural = count === 1 ? "" : "s";
+  const allPersistent = layoutWarnings.every((warning) => warning.persistent);
+  const allLowSeverity = layoutWarnings.every((warning) => warning.severity !== "error");
+  const allRepeatOrLowSeverity = layoutWarnings.every((warning) => warning.persistent || warning.severity !== "error");
+  if (allPersistent) {
+    return `${count} layout warning${plural} detected, and every one was already reported in a prior poll and is still unresolved - if you already attempted a fix, it is fine to proceed to the human with a short note about what remains instead of looping further edits and reloads. `;
+  }
+  if (allLowSeverity) {
+    return `${count} low-severity layout warning${plural} detected (no error-severity findings) - fix them if the cause is obvious in ${file}, otherwise it is fine to proceed to the human with a note instead of iterating further. `;
+  }
+  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. `;
+}
 async function endCommand(args) {
   const file = firstPositionalArg(args);
   if (!file) {
@@ -6783,7 +6922,7 @@ 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 layout_warnings before involving the human. 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.
 
 `;
 var COMMAND_HELP = {
@@ -6793,7 +6932,7 @@ Open or resume a Lavish Editor review session for an HTML artifact. Use --no-ope
 `,
   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 layout_warnings before involving the human. 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.
 `,
   end: `Usage: lavish-axi end <html-file>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "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

@@ -34,7 +34,7 @@ Use lavish-axi when the user asks for a visual artifact, HTML explainer, interac
 3. Run `npx -y lavish-axi poll <html-file>` to long-poll for the user's annotations, queued prompts, and browser-reported `layout_warnings`.
    The poll stays silent until the user acts or the real browser reports fresh layout warnings - leave it running, never kill it.
    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.
-4. If poll returns `layout_warnings`, fix overflow, clipped text, or overlapping unreadable content and re-check before involving the human.
+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.
 
@@ -65,7 +65,7 @@ For flows, architecture, state, or sequence diagrams, do not hand-build boxes-an
 - Run `npx -y lavish-axi <html-file>` to open or resume a Lavish Editor session
 - Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`
 - Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work
-- Run `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 layout_warnings before involving the human. 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 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 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