@agent-native/core 0.84.35 → 0.84.37

package/corpus/core/src/client/blocks/library/wireframe-kit.tsx

@@ -26,10 +26,10 @@ import type {
  * DECOUPLING: the only behavioral change from the plan copy is theme detection —
  * core blocks read `document.documentElement.classList.contains("dark")` (the
  * MermaidBlock precedent) instead of importing `next-themes`. Everything else
- * (the `.plan-wf` / `[data-rough]` class contract the rough overlay measures,
- * the `--wf-*` / `--ink` / `--paper` token names every primitive reads) is
- * preserved exactly, so the kit looks identical in plan and renders correctly in
- * any app once the matching tokens exist in `core/styles/blocks.css`.
+ * (the `.plan-wf` / `.wf-*` / `[data-rough]` class contract the rough overlay
+ * measures, the `--wf-*` / `--ink` / `--paper` token names every primitive
+ * reads) is preserved exactly, so the kit looks identical in plan and renders
+ * correctly in any app once the matching tokens exist in `core/styles/blocks.css`.
  */
 
 /* ========================================================================== */
@@ -211,7 +211,7 @@ export function Screen({
         // clipping. The frame shell (`ArtboardFrame`) owns the height policy; a
         // caller can still override via `style.height` for a fixed canvas.
         minHeight: "100%",
-        background: V.paper,
+        background: "transparent",
         color: V.ink,
         fontFamily: V.hand,
         fontSize: V.fs,
@@ -1425,9 +1425,9 @@ const gen = rough.generator();
 
 type RoughPath = { d: string; stroke: string; strokeWidth: number };
 
-/** The default selector used for HTML mockups: controls plus explicit opt-ins. */
+/** The default selector used for HTML mockups: standard wireframe primitives plus explicit opt-ins. */
 export const HTML_ROUGH_SELECTOR =
-  "[data-rough],button,input,textarea,select,hr";
+  "[data-rough],button,input,textarea,select,hr,.wf-btn,.wf-card,.wf-box,.wf-pill,.wf-chip,.wf-icon-fallback,[style*='border:'],[style*='border-top:'],[style*='border-right:'],[style*='border-bottom:'],[style*='border-left:']";
 
 /** Stable per-element seed so a frame doesn't re-wobble on every measure. */
 function seedFrom(...parts: Array<string | number>): number {
@@ -1528,6 +1528,50 @@ function elementStroke(node: Element, fallback: string): string {
   return fallback;
 }
 
+function visibleBorderSides(
+  node: Element,
+): Array<"top" | "right" | "bottom" | "left"> {
+  const cs = getComputedStyle(node);
+  const sides: Array<"top" | "right" | "bottom" | "left"> = [];
+  for (const [side, widthProp, colorProp] of [
+    ["top", "borderTopWidth", "borderTopColor"],
+    ["right", "borderRightWidth", "borderRightColor"],
+    ["bottom", "borderBottomWidth", "borderBottomColor"],
+    ["left", "borderLeftWidth", "borderLeftColor"],
+  ] as const) {
+    const width = parseFloat(cs[widthProp]);
+    const color = cs[colorProp];
+    if (
+      width > 0 &&
+      color &&
+      color !== "rgba(0, 0, 0, 0)" &&
+      color !== "transparent"
+    ) {
+      sides.push(side);
+    }
+  }
+  return sides;
+}
+
+function inferRoughKind(node: HTMLElement): string {
+  const explicit = node.getAttribute("data-rough");
+  if (explicit) return explicit;
+  if (node.tagName === "HR") return "line:middle";
+  const sides = visibleBorderSides(node);
+  if (sides.length !== 1) return "rect";
+  switch (sides[0]) {
+    case "top":
+      return "line:top";
+    case "right":
+      return "line:right";
+    case "bottom":
+      return "line:bottom";
+    case "left":
+      return "line:left";
+  }
+  return "rect";
+}
+
 function build(
   scope: HTMLElement,
   opts: {
@@ -1602,7 +1646,7 @@ function build(
     const w = r.width / zoom;
     const h = r.height / zoom;
     if (w < 2 || h < 2) return;
-    const kind = node.getAttribute("data-rough") || "rect";
+    const kind = inferRoughKind(node);
     const rawStroke = elementStroke(node, sketch);
     const stroke =
       sameColor(rawStroke, ink) || (line !== "" && sameColor(rawStroke, line))
@@ -1621,11 +1665,15 @@ function build(
     let drawable: unknown;
     if (kind === "ellipse") {
       drawable = gen.ellipse(x + w / 2, y + h / 2, w, h, o);
+    } else if (kind === "line:left") {
+      drawable = gen.line(x, y, x, y + h, o);
     } else if (kind === "line:right") {
       drawable = gen.line(x + w, y, x + w, y + h, o);
     } else if (kind === "line:bottom") {
       drawable = gen.line(x, y + h, x + w, y + h, o);
-    } else if (kind === "line:top" || node.tagName === "HR") {
+    } else if (kind === "line:top") {
+      drawable = gen.line(x, y, x + w, y, o);
+    } else if (kind === "line:middle") {
       drawable = gen.line(x, y + h / 2, x + w, y + h / 2, o);
     } else {
       const cr = parseFloat(getComputedStyle(node).borderTopLeftRadius) || 0;

package/corpus/core/src/client/blocks/library/wireframe.tsx

@@ -56,8 +56,8 @@ import {
  * - The plan-only prototype runtime, design-element selection, and legacy region
  *   fallback are intentionally NOT ported; those are plan-canvas features, not
  *   part of the document-block render. The kit element vocabulary, the `--wf-*`
- *   token contract, and the `.plan-wf` / `[data-rough]` classes the overlay
- *   measures are preserved exactly.
+ *   token contract, and the `.plan-wf` / `.wf-*` / `[data-rough]` classes the
+ *   overlay measures are preserved exactly.
  *
  * The section carries the app-neutral `an-block` class plus the legacy
  * `plan-block` class so plan renders byte-identically while any other app gets
@@ -164,12 +164,6 @@ function ArtboardFrame({
   const designMode = renderMode === "design";
   const sketchy = !designMode && style === "sketchy" && !skeleton;
   const roughEnabled = sketchy && roughOverlay;
-  const paper = designMode
-    ? "hsl(var(--background))"
-    : "var(--plan-document, hsl(var(--background)))";
-  const frameBorder = skeleton
-    ? "var(--plan-placeholder-line, var(--plan-line, hsl(var(--border))))"
-    : "var(--plan-line, hsl(var(--border)))";
 
   useEffect(() => {
     const element = fitRef.current;
@@ -243,7 +237,6 @@ function ArtboardFrame({
             // a fixed `canvasSize` locks the height for canvas artboards.
             ...(fixedHeight != null ? { height: fixedHeight } : { minHeight }),
             borderRadius: preset.radius,
-            background: paper,
             ...(fitScale !== 1
               ? {
                   transform: `scale(${fitScale})`,
@@ -266,18 +259,10 @@ function ArtboardFrame({
           >
             {render({ theme, style })}
           </div>
-          {!roughEnabled && (
-            <div
-              className="pointer-events-none absolute inset-0"
-              style={{
-                borderRadius: preset.radius,
-                border: `1.5px solid ${frameBorder}`,
-              }}
-            />
-          )}
           <RoughOverlay
             scopeRef={ref}
             enabled={roughEnabled}
+            drawFrame={false}
             frameRadius={preset.radius}
             selector={selector}
           />

package/corpus/core/src/client/chat/widgets/builtin-tool-renderers.tsx

@@ -34,10 +34,37 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function normalizeActionDataWidgetResult(
   context: ToolRendererContext,
 ): DataWidgetResult | null {
+  const renderer = context.chatUI?.renderer;
+  if (isRecord(context.resultJson)) {
+    if (renderer === ACTION_CHAT_UI_DATA_TABLE_RENDERER) {
+      return normalizeDataWidgetResult({
+        ...context.resultJson,
+        widget: DATA_TABLE_WIDGET,
+        table: isRecord(context.resultJson.table)
+          ? context.resultJson.table
+          : context.resultJson,
+      });
+    }
+    if (renderer === ACTION_CHAT_UI_DATA_CHART_RENDERER) {
+      return normalizeDataWidgetResult({
+        ...context.resultJson,
+        widget: DATA_CHART_WIDGET,
+        chartSeries: isRecord(context.resultJson.chartSeries)
+          ? context.resultJson.chartSeries
+          : context.resultJson,
+      });
+    }
+    if (renderer === ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER) {
+      return normalizeDataWidgetResult({
+        ...context.resultJson,
+        widget: DATA_INSIGHTS_WIDGET,
+      });
+    }
+  }
+
   const result = normalizeDataWidgetResult(context.resultJson);
   if (result) return result;
 
-  const renderer = context.chatUI?.renderer;
   if (
     renderer === ACTION_CHAT_UI_DATA_WIDGET_RENDERER ||
     context.toolName === "render-data-widget"
@@ -46,37 +73,6 @@ function normalizeActionDataWidgetResult(
     if (argsResult) return argsResult;
   }
 
-  if (!isRecord(context.resultJson)) return null;
-
-  if (renderer === ACTION_CHAT_UI_DATA_TABLE_RENDERER) {
-    return normalizeDataWidgetResult({
-      widget: DATA_TABLE_WIDGET,
-      table: isRecord(context.resultJson.table)
-        ? context.resultJson.table
-        : context.resultJson,
-      display: isRecord(context.resultJson.display)
-        ? context.resultJson.display
-        : undefined,
-    });
-  }
-  if (renderer === ACTION_CHAT_UI_DATA_CHART_RENDERER) {
-    return normalizeDataWidgetResult({
-      widget: DATA_CHART_WIDGET,
-      chartSeries: isRecord(context.resultJson.chartSeries)
-        ? context.resultJson.chartSeries
-        : context.resultJson,
-      display: isRecord(context.resultJson.display)
-        ? context.resultJson.display
-        : undefined,
-    });
-  }
-  if (renderer === ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER) {
-    return normalizeDataWidgetResult({
-      ...context.resultJson,
-      widget: DATA_INSIGHTS_WIDGET,
-    });
-  }
-
   return null;
 }
 

package/corpus/core/src/client/use-run-stuck-detection.ts

@@ -24,6 +24,10 @@ export interface RunStuckState {
   stuckSinceMs: number | null;
   /** Server timestamp (ms) of the last process-alive heartbeat. */
   heartbeatAt: number | null;
+  /** Milliseconds since `heartbeatAt`, computed against the server clock. */
+  heartbeatSinceMs: number | null;
+  /** How the run was dispatched, e.g. foreground or background-processing. */
+  dispatchMode: string | null;
 }
 
 export interface UseRunStuckDetectionOptions {
@@ -51,6 +55,7 @@ interface ActiveRunResponse {
   status?: string;
   heartbeatAt: number | null;
   lastProgressAt?: number | null;
+  dispatchMode?: string | null;
   /** Server clock at response time, used to compute elapsed server-relative. */
   serverNow?: number;
 }
@@ -62,6 +67,8 @@ const EMPTY_STATE: RunStuckState = {
   lastProgressAt: null,
   stuckSinceMs: null,
   heartbeatAt: null,
+  heartbeatSinceMs: null,
+  dispatchMode: null,
 };
 
 export function useRunStuckDetection({
@@ -102,6 +109,9 @@ export function useRunStuckDetection({
           const nowMs = data.serverNow ?? Date.now();
           const stuckSinceMs =
             lastProgressAt != null ? nowMs - lastProgressAt : null;
+          const heartbeatAt = data.heartbeatAt ?? null;
+          const heartbeatSinceMs =
+            heartbeatAt != null ? nowMs - heartbeatAt : null;
           const isStuck = Boolean(
             data.active &&
             data.status === "running" &&
@@ -114,7 +124,10 @@ export function useRunStuckDetection({
             status: data.status ?? null,
             lastProgressAt,
             stuckSinceMs,
-            heartbeatAt: data.heartbeatAt ?? null,
+            heartbeatAt,
+            heartbeatSinceMs,
+            dispatchMode:
+              typeof data.dispatchMode === "string" ? data.dispatchMode : null,
           });
           // Back off polling when nothing is in flight — there's no point
           // hammering the endpoint while the chat is idle. We still poll

package/corpus/core/src/db/schema.ts

@@ -19,6 +19,7 @@
 import { sql } from "drizzle-orm";
 import {
   pgTable,
+  alias as pgAlias,
   index as pgIndex,
   text as pgText,
   integer as pgInteger,
@@ -28,6 +29,7 @@ import {
 } from "drizzle-orm/pg-core";
 import {
   sqliteTable,
+  alias as sqliteAlias,
   index as sqliteIndex,
   text as sqliteText,
   integer as sqliteInteger,
@@ -50,6 +52,9 @@ function pg(): boolean {
 export const table: typeof sqliteTable = ((...args: any[]) =>
   pg() ? (pgTable as any)(...args) : (sqliteTable as any)(...args)) as any;
 
+export const alias: typeof sqliteAlias = ((...args: any[]) =>
+  pg() ? (pgAlias as any)(...args) : (sqliteAlias as any)(...args)) as any;
+
 export const index: typeof sqliteIndex = ((...args: any[]) =>
   pg() ? (pgIndex as any)(...args) : (sqliteIndex as any)(...args)) as any;
 

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -7278,8 +7278,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             let reason = "user";
             try {
               const body = await readBody(event);
-              if (body?.reason === "no_progress") {
-                reason = "no_progress";
+              if (
+                typeof body?.reason === "string" &&
+                /^[a-z0-9_-]{1,64}$/i.test(body.reason)
+              ) {
+                reason = body.reason;
               }
             } catch {
               // Empty/invalid body — keep the default user abort reason.

package/corpus/core/src/styles/blocks.css

@@ -995,7 +995,7 @@
   min-height: 100%;
   overflow: hidden;
   box-sizing: border-box;
-  background: var(--wf-paper);
+  background: transparent;
   color: var(--wf-ink);
   font-family: var(--wf-font);
   font-size: 14px;
@@ -1177,6 +1177,16 @@
   border-radius: var(--wf-radius);
   padding: 12px;
 }
+.plan-html-frame:not([data-render-mode="design"]) .wf-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+.plan-html-frame:not([data-render-mode="design"]) .wf-row > :last-child {
+  margin-inline-start: auto;
+  text-align: end;
+}
 .plan-html-frame[data-style="sketchy"]:not([data-render-mode="design"])
   :is(.wf-card, .wf-box) {
   border-color: color-mix(in srgb, var(--wf-line) 72%, transparent);
@@ -1197,9 +1207,9 @@
   background: var(--wf-accent-soft);
 }
 
-/* Once rough has drawn, hide crisp borders only on elements rough.js actually
-   redraws. Broad helper containers keep theme-safe filled backgrounds and soft
-   borders so nested cards do not become a pile of overlapping sketch strokes. */
+/* Once rough has drawn, hide crisp borders on the standard wireframe primitives
+   that rough.js redraws. Fills and text stay in CSS; only outlines switch to
+   the hand-drawn overlay. */
 .plan-html-frame[data-rough-ready]
   :is(
     button,
@@ -1207,8 +1217,19 @@
     textarea,
     select,
     hr,
-    [data-rough]:not([data-rough="none"])
-  ) {
+    .wf-btn,
+    .wf-card,
+    .wf-box,
+    .wf-pill,
+    .wf-chip,
+    .wf-icon-fallback,
+    [style*="border:"],
+    [style*="border-top:"],
+    [style*="border-right:"],
+    [style*="border-bottom:"],
+    [style*="border-left:"],
+    [data-rough]
+  ):not([data-rough="none"]) {
   border-color: transparent !important;
 }
 

package/corpus/templates/analytics/app/components/layout/Sidebar.tsx

@@ -1348,9 +1348,6 @@ function AnalyticsChatsSection() {
 
   return (
     <div className="ms-4 min-w-0 space-y-0.5">
-      <p className="min-w-0 truncate px-3 pb-0.5 pt-1 text-[11px] font-medium text-muted-foreground/70">
-        {t("chat.recentChats")}
-      </p>
       {visibleThreads.map((thread) => {
         const title = threadTitle(thread, t("chat.untitledChat"));
         const isActive =
@@ -1395,7 +1392,7 @@ function AnalyticsChatsSection() {
                     <button
                       type="button"
                       onClick={() => openThread(thread.id)}
-                      className="min-w-0 flex-1 px-2 py-1.5 pe-12 text-start text-xs outline-none transition-[padding] focus-visible:ring-2 focus-visible:ring-ring md:pe-2 md:group-hover/item:pe-12 md:group-focus-within/item:pe-12"
+                      className="min-w-0 flex-1 px-2 py-1.5 pe-12 text-start text-xs outline-none focus-visible:ring-2 focus-visible:ring-ring"
                     >
                       <span className="block truncate">{title}</span>
                     </button>

package/corpus/templates/content/actions/list-trashed-content-databases.ts

@@ -1,7 +1,7 @@
 import { defineAction } from "@agent-native/core";
+import { alias } from "@agent-native/core/db/schema";
 import { accessFilter } from "@agent-native/core/sharing";
 import { and, desc, eq, isNotNull, isNull, ne, or } from "drizzle-orm";
-import { alias } from "drizzle-orm/sqlite-core";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";

package/corpus/templates/plan/.agents/skills/visual-plan/references/wireframe.md

@@ -75,15 +75,13 @@ background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
 or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
 are still discouraged; inline flex/grid styles are safer and easier to review.
 
-**Keep Rough.js sparse.** `.wf-card` and `.wf-box` already render with
-theme-safe filled backgrounds (`--wf-card`) and soft tokenized borders that work
-in both light and dark mode. Do not add `data-rough` to broad root wrappers,
-dialog shells, page panels, grid cells, or nested containers unless that single
-container is the visual point. The renderer sketches the outer frame and
-standard controls by default; use `data-rough` only for a deliberate one-off
-shape. If a mockup starts looking like stacked/overlapping sketch lines, remove
-rough targets from parent containers and let backgrounds plus spacing separate
-the surfaces.
+**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
+`.wf-*` primitives, controls, and inline border dividers by default. Do not add
+`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or
+nested containers unless that single container is the visual point. Use
+`data-rough` only for a deliberate one-off shape. If a mockup starts looking
+like stacked/overlapping sketch lines, remove rough targets from parent
+containers and let backgrounds plus spacing separate the surfaces.
 
 **Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
 renderer-owned visual styling, not layout spacing. Do not use guessed spacing

package/corpus/templates/plan/.agents/skills/visual-recap/references/wireframe.md

@@ -75,15 +75,13 @@ background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
 or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
 are still discouraged; inline flex/grid styles are safer and easier to review.
 
-**Keep Rough.js sparse.** `.wf-card` and `.wf-box` already render with
-theme-safe filled backgrounds (`--wf-card`) and soft tokenized borders that work
-in both light and dark mode. Do not add `data-rough` to broad root wrappers,
-dialog shells, page panels, grid cells, or nested containers unless that single
-container is the visual point. The renderer sketches the outer frame and
-standard controls by default; use `data-rough` only for a deliberate one-off
-shape. If a mockup starts looking like stacked/overlapping sketch lines, remove
-rough targets from parent containers and let backgrounds plus spacing separate
-the surfaces.
+**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
+`.wf-*` primitives, controls, and inline border dividers by default. Do not add
+`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or
+nested containers unless that single container is the visual point. Use
+`data-rough` only for a deliberate one-off shape. If a mockup starts looking
+like stacked/overlapping sketch lines, remove rough targets from parent
+containers and let backgrounds plus spacing separate the surfaces.
 
 **Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
 renderer-owned visual styling, not layout spacing. Do not use guessed spacing

package/dist/cli/skills.d.ts

@@ -6,7 +6,7 @@
 import { type AppSkillManifest } from "./app-skill.js";
 import { type ClientId } from "./mcp-config-writers.js";
 import { type CliTelemetry } from "./telemetry.js";
-export declare const WIREFRAME_REFERENCE_MD = "# HTML wireframe quality \u2014 single source of truth\n\nThis file is the canonical quality bar for HTML wireframes / `<Screen>` /\n`WireframeBlock` content, shared word for word by `/visual-plan` and\n`/visual-recap`. Read it in full before authoring ANY wireframe; do not\nauthor wireframes from memory or paraphrase these rules per command.\n\n<!-- SHARED-CORE:wireframe-quality START -->\n\n**A wireframe is an HTML mockup. The renderer owns the look; you write the\ncontent.** Set `data.html` to a self-contained, semantic HTML fragment of the\nscreen and set `data.surface`. The renderer owns the surface footprint/aspect,\nthe dark/light theme, the hand-drawn font, and the rough.js sketch overlay \u2014 you\nnever write `<html>`/`<body>`/`<script>`/`<style>` tags or any\nwidth/height/coordinates. You write real HTML layout and real product\ncontent; the renderer styles and roughens it.\n\n**A wireframe block's data is an HTML screen plus a surface:**\n\n```json\n{\n  \"surface\": \"browser\",\n  \"html\": \"<div style=\\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\\"><h1>Sign in</h1><p class=\\\"wf-muted\\\">Use your work email to continue.</p><div class=\\\"wf-card\\\" style=\\\"display:flex;flex-direction:column;gap:10px\\\"><label>Email<input value=\\\"jane@acme.co\\\" /></label><label>Password<input value=\\\"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\\\" /></label><label style=\\\"display:flex;align-items:center;gap:8px\\\"><input type=\\\"checkbox\\\" checked /> Remember me</label><button class=\\\"primary\\\">Sign in</button></div><a href=\\\"#\\\">Forgot password?</a></div>\"\n}\n```\n\n**Write PLAIN semantic HTML and let the renderer style it.** Bare elements\n(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type=\"checkbox\">`, `a`, `hr`)\nare auto-themed \u2014 no classes needed. Helper classes carry the rest:\n\n- `.wf-card` / `.wf-box` \u2014 a bordered, padded container (a panel, a list item).\n- `.wf-pill` / `.wf-chip` \u2014 a rounded tag or filter; add `.accent`\n  (`<span class=\"wf-pill accent\">`) for the accent-filled variant.\n- `.wf-muted` \u2014 secondary/muted text (or use `<small>`).\n- `button.primary` or any element with `[data-primary]` \u2014 the accent-filled\n  primary button.\n\n**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:\ndrop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a\nwireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.\nMockups should read as flat, bordered surfaces; use spacing, borders, labels,\nand annotations for separation. Only show a shadow when the real product UI\nalready has that shadow and it is essential to the change being reviewed.\n\n**Use renderer icons, not visible icon words.** For icon-only buttons or leading\nicons inside fields, chips, menu items, and toolbars, write an empty marker such\nas `<span data-icon=\"mail\" aria-label=\"Email\"></span>` or\n`<i data-icon=\"lock\"></i>`. The renderer replaces it with a Tabler-style SVG and\nthe `.wf-icon` class sizes it to the surrounding text. Supported names and\naliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,\n`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,\n`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,\n`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words\nlike \"email\", \"lock\", \"search\", \"chevron\", or \"more\" where the product UI would\nshow an icon; use text only when it is a real label a user would read.\n\n**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips\nthese on light/dark, so reading them is what keeps a mockup correct in both\nthemes. For any inline border, background, or text color, reference a token:\n`style=\"border:1.4px solid var(--wf-line)\"`. The tokens are `--wf-ink` (text),\n`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`\n(page background), `--wf-card` (container surface), `--wf-accent` /\n`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,\nand `--wf-radius`. Never hard-code a hex color and never set `font-family` \u2014 the\nrenderer owns the sketch/clean font.\n\n**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as\n`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,\n`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,\nor arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the\nmockup and can make dark-mode canvas frames unreadable. Use bare semantic\nelements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before\npublishing, scan every wireframe `class` and `style` attribute: if a class sets\nbackground, text, border, ring, fill, stroke, gradient, placeholder, decoration,\nor shadow color, rewrite it to renderer tokens or remove it. Layout-only classes\nare still discouraged; inline flex/grid styles are safer and easier to review.\n\n**Keep Rough.js sparse.** `.wf-card` and `.wf-box` already render with\ntheme-safe filled backgrounds (`--wf-card`) and soft tokenized borders that work\nin both light and dark mode. Do not add `data-rough` to broad root wrappers,\ndialog shells, page panels, grid cells, or nested containers unless that single\ncontainer is the visual point. The renderer sketches the outer frame and\nstandard controls by default; use `data-rough` only for a deliberate one-off\nshape. If a mockup starts looking like stacked/overlapping sketch lines, remove\nrough targets from parent containers and let backgrounds plus spacing separate\nthe surfaces.\n\n**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and\nrenderer-owned visual styling, not layout spacing. Do not use guessed spacing\ntokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing\nvariables inside wireframe HTML; if a token is unavailable in the Plan renderer,\npadding collapses and content hugs the border. Use explicit CSS lengths for\nlayout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.\n\n**Lay out with inline `style` flex/grid.** You write the real layout \u2014\n`display:flex; flex-direction:column; gap:10px; padding:16px` and so on \u2014 and the\nrenderer never repositions anything. Compose the actual product: reproduce the\ncurrent screen, then show the modification. Real labels, real counts, real dates,\nreal button text grounded in the screen you read; not lorem or gray bars.\n\n**Surface presets \u2014 match the real footprint, never default to desktop+mobile.**\nPick the `surface` that matches what the user will actually see:\n\n- `browser`: a web page that needs a browser chrome frame around it.\n- `desktop`: a full desktop app page or app shell.\n- `mobile`: a phone screen, only when the work is genuinely mobile.\n- `popover`: a small floating menu, dropdown, or inline popover.\n- `panel`: a side panel, inspector, or sidebar widget.\n\nA sidebar popover renders as a small surface, not a desktop page and a phone\nframe. Do not emit `desktop` + `mobile` variants unless responsive behavior\nactually changes the layout. For a component or widget, show one broader\napp-context frame only when placement affects understanding, then the focused\ncomponent states.\n\n**Model the actual component shell for small surfaces.** A rendered UI change\nbelongs in a wireframe; reserve `diagram` for architecture, dependency, state,\nor data-flow relationships. Popovers, dropdown menus, command palettes, and\ncontext menus use `surface: \"popover\"` unless the surrounding page placement is\nthe point of the change. Dialogs, sheets, inspectors, sidebars, and long\nproperty panels use the matching `panel` / `desktop` surface as appropriate.\nShow the real chrome: trigger or anchor when it matters, title/header row,\ntop-right actions, separators, fields, options, selected states, body content,\nand footer actions that are visible in the workflow.\n\n**Modify, don't redesign.** When the task changes an existing screen, reproduce\nthe current screen's real layout and footprint FIRST, then change only the delta\nand call it out with a single annotation. Do not restack the page into a new\nlayout. For net-new surfaces, compose from the real app shell. Inspect the\nactual app components before drawing an existing product: sidebar density,\ntoolbar actions, overflow menus, property panels, and framework chrome should\nmatch the product unless the plan intentionally changes them.\n\n**Keep product screens pure.** A product wireframe shows the app state a user\nwould actually see. Do not embed file contracts, architecture arrows, repo pills,\nmode explanations, or implementation callouts inside the screen just to explain\nthe plan. Put those in canvas annotations, a separate diagram, or the document\nbody. Secondary UI such as properties, history, sync, export, or agent controls\nshould appear where the real product would put them: an overflow popover, sheet,\npanel, or separate framework sidebar state, not a generic permanent right\ninspector unless that inspector is the actual design.\n\n**Classify mockup scope before implementation.** Before turning a plan mockup\ninto source code, decide whether each artboard represents the whole page/app\nshell, a route body inside an existing shell, or a component/sub-surface. If an\nartboard includes navigation, sidebars, auth banners, or a signup/login form,\nmap those pieces to the real shared shell/auth components instead of nesting the\nentire mockup inside the current page. When a mockup references the product's\nstandard signup/login page, find and reuse that existing implementation; do not\napproximate it from the wireframe.\n\n**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a\npopover, menu, dialog, toast), show the full screen once, then add a small\nseparate artboard whose `html` contains ONLY that sub-surface \u2014 do not re-draw\nthe whole page around it, and do not scale a duplicate up. Pick the matching\n`surface` (e.g. `popover`) so the footprint is right; never widen a popover to\npage width.\n\n**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and\nfill the `html` with neutral, textless placeholder geometry \u2014 boxes and bars\nbuilt as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,\nno labels or copy. The renderer drops borders, sketch, and color into the\nskeleton register automatically. Never escape to a `custom-html` document block\nto fake a loader.\n\n**Editing an existing mockup.** In hosted mode, to change one element, text, or\ncolor in an existing html mockup, do not regenerate the frame \u2014 call\n`update-visual-plan` with\n`contentPatches: [{ op: \"patch-wireframe-html\", blockId, edits: [{ find,\nreplace }] }]`. Each `find` is a unique snippet of the current html (read it\nfirst with `get-visual-plan`); set `all: true` on an edit to replace every\noccurrence. The result is re-sanitized. In local-files privacy mode, do not call\nhosted Plan tools; edit the local MDX source directly and rerun the local\ncheck/serve or verify command for `<plan-dir>`.\n\n**Treat the wireframe border as part of the visible design.** Always wrap HTML\nwireframe content in a root container with real inner padding before drawing\ncards, fields, pills, labels, or controls. Use at least 14-16px of padding,\n`box-sizing: border-box`, `height: 100%`, and `gap` between child rows on the\nroot node itself so the first row never sits flush against the screen border. Do\nnot rely on padding on a nested page section as the first visible inset; the\noutermost element must create the breathing room. Keep text away from borders:\nevery container, field, button, menu item, and annotation needs enough padding\nand line-height to read cleanly in the rendered Plan view.\n\n**For feature-cloud or abundance visuals, optimize the composition over line-by-line\nreading.** Some marketing/product sections need to feel like a large surface area\nof capability rather than a precise app workflow. In those cases, use one padded\nroot with a short headline and a dense, aesthetic cloud of short feature labels,\nchips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,\nand let many labels be glanceable rather than individually essential. Do not\nforce dozens of features into equal cards with long wrapped sentences; that\nusually creates a messy unreadable mockup.\n\n**Lay out children safely so they never collide.** Use HTML flex/grid with\n`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute\npositioning, or fixed child widths that can collide when the renderer switches\nbetween light/dark, sketch/clean, or different zoom levels.\n\n**Do not wrap intentionally single-line labels.** For toolbars, tab rails,\nbreadcrumbs, chip/filter rows, branch and file names, file chips, and code\nfilenames \u2014 any deliberately single-line row \u2014 do not let long text wrap. Put\n`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`\non the individual labels that can grow), so the wireframe demonstrates the actual\nlayout behavior instead of producing ugly stacked or vertical text. Use\nhorizontally scrollable or clipped rails for overflow.\n\n**Fill the frame; keep labels short.** Each artboard is a fixed-size surface \u2014 compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column \u2014 shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).\n\n**Persistent chrome bars span the full frame width.** Top bars, app headers,\ntoolbars, and bottom tab/nav bars are full-width chrome, not centered content.\nLay each one out as a single flex row that fills the frame\n(`style=\"display:flex;align-items:center;width:100%\"`) and push trailing actions\nto the right edge with a flex spacer (`<div style=\"flex:1\"></div>`) between the\nleading group and the trailing group \u2014 never center a bar inside a narrow,\ncentered block, and never let it collapse to the width of its contents. In a\nBefore/After pair the bar stays full-width in BOTH states even when one state has\nfewer controls; the spacer absorbs the difference so the remaining controls hold\ntheir edge alignment instead of sliding to the center.\n\n**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and\nany persistent bottom action row, make the frame itself a flex column at\n`height:100%` (`style=\"display:flex;flex-direction:column;height:100%\"`), give the\nscrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST\nchild of the frame (or set `margin-top:auto` on it). The bar then sits flush at\nthe bottom of the surface instead of floating directly under the content with an\nempty band beneath it.\n\n**Before / after must be comparable.** When showing a state change, preserve the\nunchanged controls in both states so the reviewer can see exactly what moved or\nappeared; do not show an added control as a generic box floating elsewhere in\nthe surface. Place the new/changed affordance where the implementation puts it \u2014\nfor example, a new `Edit with AI` action in a popover header belongs in the\ntop-right header slot, aligned with the title, not in the body or footer. Use\nthe same frame size, scale, outer padding, border radius, and visual density on\nboth sides unless the change itself alters those properties, and let the frame\nheight fit the content rather than leaving a tall empty lower half.\n\n**Name the states with the column header, never inside the frame.** For\ndocument-body wireframes (recaps), put the two\nstates in a `columns` block and set each column's `label` to `Before` and\n`After` \u2014 the renderer draws that label as an `h4` heading above each frame. Do\nNOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a\nlabel placed inside reads as part of the product UI, lands in a random corner,\nand clutters the comparison. The column header is the one and only place the\nstate name belongs. On a canvas, place the two state artboards as neighbors with\nframe labels \u2014 never encode Before/After inside the html.\n\n**Let the surface choose side-by-side vs. stacked.** For document-body\nwireframes (recaps), the `columns` renderer lays\nnarrow surfaces (`mobile`, `popover`, `panel`) out side by side, and\nautomatically stacks wide surfaces (`desktop`, `browser`) vertically at full\ndocument width so a large frame is never crushed into a half-width column and\ncropped. Author both wireframes with the real `surface` and the matching\n`Before`/`After` column labels; do not hand-stack the pair into separate\ntop-level wireframes or duplicate the state name as body content.\n\n**Good example \u2014 a contacts list, surface `browser`.** A small, real screen\ncomposed from the helper classes and tokens, layout in inline flex, no fonts or\nhex colors:\n\n```html\n<div\n  style=\"display:flex;flex-direction:column;gap:12px;padding:16px;height:100%\"\n>\n  <div style=\"display:flex;align-items:center;justify-content:space-between\">\n    <h1>Contacts</h1>\n    <button class=\"primary\">New contact</button>\n  </div>\n  <div style=\"display:flex;gap:6px\">\n    <span class=\"wf-pill accent\">All 128</span>\n    <span class=\"wf-pill\">Favorites</span>\n    <span class=\"wf-pill\">Archived</span>\n  </div>\n  <div\n    class=\"wf-card\"\n    style=\"display:flex;flex-direction:column;gap:0;padding:0\"\n  >\n    <div\n      style=\"display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)\"\n    >\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>\n      </div>\n      <span class=\"wf-pill\">Lead</span>\n    </div>\n    <div style=\"display:flex;align-items:center;gap:10px;padding:10px 12px\">\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>\n      </div>\n      <span class=\"wf-pill\">Customer</span>\n    </div>\n  </div>\n</div>\n```\n\n<!-- SHARED-CORE:wireframe-quality END -->\n";
+export declare const WIREFRAME_REFERENCE_MD = "# HTML wireframe quality \u2014 single source of truth\n\nThis file is the canonical quality bar for HTML wireframes / `<Screen>` /\n`WireframeBlock` content, shared word for word by `/visual-plan` and\n`/visual-recap`. Read it in full before authoring ANY wireframe; do not\nauthor wireframes from memory or paraphrase these rules per command.\n\n<!-- SHARED-CORE:wireframe-quality START -->\n\n**A wireframe is an HTML mockup. The renderer owns the look; you write the\ncontent.** Set `data.html` to a self-contained, semantic HTML fragment of the\nscreen and set `data.surface`. The renderer owns the surface footprint/aspect,\nthe dark/light theme, the hand-drawn font, and the rough.js sketch overlay \u2014 you\nnever write `<html>`/`<body>`/`<script>`/`<style>` tags or any\nwidth/height/coordinates. You write real HTML layout and real product\ncontent; the renderer styles and roughens it.\n\n**A wireframe block's data is an HTML screen plus a surface:**\n\n```json\n{\n  \"surface\": \"browser\",\n  \"html\": \"<div style=\\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\\"><h1>Sign in</h1><p class=\\\"wf-muted\\\">Use your work email to continue.</p><div class=\\\"wf-card\\\" style=\\\"display:flex;flex-direction:column;gap:10px\\\"><label>Email<input value=\\\"jane@acme.co\\\" /></label><label>Password<input value=\\\"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\\\" /></label><label style=\\\"display:flex;align-items:center;gap:8px\\\"><input type=\\\"checkbox\\\" checked /> Remember me</label><button class=\\\"primary\\\">Sign in</button></div><a href=\\\"#\\\">Forgot password?</a></div>\"\n}\n```\n\n**Write PLAIN semantic HTML and let the renderer style it.** Bare elements\n(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type=\"checkbox\">`, `a`, `hr`)\nare auto-themed \u2014 no classes needed. Helper classes carry the rest:\n\n- `.wf-card` / `.wf-box` \u2014 a bordered, padded container (a panel, a list item).\n- `.wf-pill` / `.wf-chip` \u2014 a rounded tag or filter; add `.accent`\n  (`<span class=\"wf-pill accent\">`) for the accent-filled variant.\n- `.wf-muted` \u2014 secondary/muted text (or use `<small>`).\n- `button.primary` or any element with `[data-primary]` \u2014 the accent-filled\n  primary button.\n\n**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:\ndrop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a\nwireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.\nMockups should read as flat, bordered surfaces; use spacing, borders, labels,\nand annotations for separation. Only show a shadow when the real product UI\nalready has that shadow and it is essential to the change being reviewed.\n\n**Use renderer icons, not visible icon words.** For icon-only buttons or leading\nicons inside fields, chips, menu items, and toolbars, write an empty marker such\nas `<span data-icon=\"mail\" aria-label=\"Email\"></span>` or\n`<i data-icon=\"lock\"></i>`. The renderer replaces it with a Tabler-style SVG and\nthe `.wf-icon` class sizes it to the surrounding text. Supported names and\naliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,\n`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,\n`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,\n`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words\nlike \"email\", \"lock\", \"search\", \"chevron\", or \"more\" where the product UI would\nshow an icon; use text only when it is a real label a user would read.\n\n**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips\nthese on light/dark, so reading them is what keeps a mockup correct in both\nthemes. For any inline border, background, or text color, reference a token:\n`style=\"border:1.4px solid var(--wf-line)\"`. The tokens are `--wf-ink` (text),\n`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`\n(page background), `--wf-card` (container surface), `--wf-accent` /\n`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,\nand `--wf-radius`. Never hard-code a hex color and never set `font-family` \u2014 the\nrenderer owns the sketch/clean font.\n\n**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as\n`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,\n`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,\nor arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the\nmockup and can make dark-mode canvas frames unreadable. Use bare semantic\nelements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before\npublishing, scan every wireframe `class` and `style` attribute: if a class sets\nbackground, text, border, ring, fill, stroke, gradient, placeholder, decoration,\nor shadow color, rewrite it to renderer tokens or remove it. Layout-only classes\nare still discouraged; inline flex/grid styles are safer and easier to review.\n\n**Keep Rough.js sparse.** The renderer sketches the outer frame, standard\n`.wf-*` primitives, controls, and inline border dividers by default. Do not add\n`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or\nnested containers unless that single container is the visual point. Use\n`data-rough` only for a deliberate one-off shape. If a mockup starts looking\nlike stacked/overlapping sketch lines, remove rough targets from parent\ncontainers and let backgrounds plus spacing separate the surfaces.\n\n**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and\nrenderer-owned visual styling, not layout spacing. Do not use guessed spacing\ntokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing\nvariables inside wireframe HTML; if a token is unavailable in the Plan renderer,\npadding collapses and content hugs the border. Use explicit CSS lengths for\nlayout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.\n\n**Lay out with inline `style` flex/grid.** You write the real layout \u2014\n`display:flex; flex-direction:column; gap:10px; padding:16px` and so on \u2014 and the\nrenderer never repositions anything. Compose the actual product: reproduce the\ncurrent screen, then show the modification. Real labels, real counts, real dates,\nreal button text grounded in the screen you read; not lorem or gray bars.\n\n**Surface presets \u2014 match the real footprint, never default to desktop+mobile.**\nPick the `surface` that matches what the user will actually see:\n\n- `browser`: a web page that needs a browser chrome frame around it.\n- `desktop`: a full desktop app page or app shell.\n- `mobile`: a phone screen, only when the work is genuinely mobile.\n- `popover`: a small floating menu, dropdown, or inline popover.\n- `panel`: a side panel, inspector, or sidebar widget.\n\nA sidebar popover renders as a small surface, not a desktop page and a phone\nframe. Do not emit `desktop` + `mobile` variants unless responsive behavior\nactually changes the layout. For a component or widget, show one broader\napp-context frame only when placement affects understanding, then the focused\ncomponent states.\n\n**Model the actual component shell for small surfaces.** A rendered UI change\nbelongs in a wireframe; reserve `diagram` for architecture, dependency, state,\nor data-flow relationships. Popovers, dropdown menus, command palettes, and\ncontext menus use `surface: \"popover\"` unless the surrounding page placement is\nthe point of the change. Dialogs, sheets, inspectors, sidebars, and long\nproperty panels use the matching `panel` / `desktop` surface as appropriate.\nShow the real chrome: trigger or anchor when it matters, title/header row,\ntop-right actions, separators, fields, options, selected states, body content,\nand footer actions that are visible in the workflow.\n\n**Modify, don't redesign.** When the task changes an existing screen, reproduce\nthe current screen's real layout and footprint FIRST, then change only the delta\nand call it out with a single annotation. Do not restack the page into a new\nlayout. For net-new surfaces, compose from the real app shell. Inspect the\nactual app components before drawing an existing product: sidebar density,\ntoolbar actions, overflow menus, property panels, and framework chrome should\nmatch the product unless the plan intentionally changes them.\n\n**Keep product screens pure.** A product wireframe shows the app state a user\nwould actually see. Do not embed file contracts, architecture arrows, repo pills,\nmode explanations, or implementation callouts inside the screen just to explain\nthe plan. Put those in canvas annotations, a separate diagram, or the document\nbody. Secondary UI such as properties, history, sync, export, or agent controls\nshould appear where the real product would put them: an overflow popover, sheet,\npanel, or separate framework sidebar state, not a generic permanent right\ninspector unless that inspector is the actual design.\n\n**Classify mockup scope before implementation.** Before turning a plan mockup\ninto source code, decide whether each artboard represents the whole page/app\nshell, a route body inside an existing shell, or a component/sub-surface. If an\nartboard includes navigation, sidebars, auth banners, or a signup/login form,\nmap those pieces to the real shared shell/auth components instead of nesting the\nentire mockup inside the current page. When a mockup references the product's\nstandard signup/login page, find and reuse that existing implementation; do not\napproximate it from the wireframe.\n\n**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a\npopover, menu, dialog, toast), show the full screen once, then add a small\nseparate artboard whose `html` contains ONLY that sub-surface \u2014 do not re-draw\nthe whole page around it, and do not scale a duplicate up. Pick the matching\n`surface` (e.g. `popover`) so the footprint is right; never widen a popover to\npage width.\n\n**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and\nfill the `html` with neutral, textless placeholder geometry \u2014 boxes and bars\nbuilt as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,\nno labels or copy. The renderer drops borders, sketch, and color into the\nskeleton register automatically. Never escape to a `custom-html` document block\nto fake a loader.\n\n**Editing an existing mockup.** In hosted mode, to change one element, text, or\ncolor in an existing html mockup, do not regenerate the frame \u2014 call\n`update-visual-plan` with\n`contentPatches: [{ op: \"patch-wireframe-html\", blockId, edits: [{ find,\nreplace }] }]`. Each `find` is a unique snippet of the current html (read it\nfirst with `get-visual-plan`); set `all: true` on an edit to replace every\noccurrence. The result is re-sanitized. In local-files privacy mode, do not call\nhosted Plan tools; edit the local MDX source directly and rerun the local\ncheck/serve or verify command for `<plan-dir>`.\n\n**Treat the wireframe border as part of the visible design.** Always wrap HTML\nwireframe content in a root container with real inner padding before drawing\ncards, fields, pills, labels, or controls. Use at least 14-16px of padding,\n`box-sizing: border-box`, `height: 100%`, and `gap` between child rows on the\nroot node itself so the first row never sits flush against the screen border. Do\nnot rely on padding on a nested page section as the first visible inset; the\noutermost element must create the breathing room. Keep text away from borders:\nevery container, field, button, menu item, and annotation needs enough padding\nand line-height to read cleanly in the rendered Plan view.\n\n**For feature-cloud or abundance visuals, optimize the composition over line-by-line\nreading.** Some marketing/product sections need to feel like a large surface area\nof capability rather than a precise app workflow. In those cases, use one padded\nroot with a short headline and a dense, aesthetic cloud of short feature labels,\nchips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,\nand let many labels be glanceable rather than individually essential. Do not\nforce dozens of features into equal cards with long wrapped sentences; that\nusually creates a messy unreadable mockup.\n\n**Lay out children safely so they never collide.** Use HTML flex/grid with\n`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute\npositioning, or fixed child widths that can collide when the renderer switches\nbetween light/dark, sketch/clean, or different zoom levels.\n\n**Do not wrap intentionally single-line labels.** For toolbars, tab rails,\nbreadcrumbs, chip/filter rows, branch and file names, file chips, and code\nfilenames \u2014 any deliberately single-line row \u2014 do not let long text wrap. Put\n`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`\non the individual labels that can grow), so the wireframe demonstrates the actual\nlayout behavior instead of producing ugly stacked or vertical text. Use\nhorizontally scrollable or clipped rails for overflow.\n\n**Fill the frame; keep labels short.** Each artboard is a fixed-size surface \u2014 compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column \u2014 shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).\n\n**Persistent chrome bars span the full frame width.** Top bars, app headers,\ntoolbars, and bottom tab/nav bars are full-width chrome, not centered content.\nLay each one out as a single flex row that fills the frame\n(`style=\"display:flex;align-items:center;width:100%\"`) and push trailing actions\nto the right edge with a flex spacer (`<div style=\"flex:1\"></div>`) between the\nleading group and the trailing group \u2014 never center a bar inside a narrow,\ncentered block, and never let it collapse to the width of its contents. In a\nBefore/After pair the bar stays full-width in BOTH states even when one state has\nfewer controls; the spacer absorbs the difference so the remaining controls hold\ntheir edge alignment instead of sliding to the center.\n\n**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and\nany persistent bottom action row, make the frame itself a flex column at\n`height:100%` (`style=\"display:flex;flex-direction:column;height:100%\"`), give the\nscrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST\nchild of the frame (or set `margin-top:auto` on it). The bar then sits flush at\nthe bottom of the surface instead of floating directly under the content with an\nempty band beneath it.\n\n**Before / after must be comparable.** When showing a state change, preserve the\nunchanged controls in both states so the reviewer can see exactly what moved or\nappeared; do not show an added control as a generic box floating elsewhere in\nthe surface. Place the new/changed affordance where the implementation puts it \u2014\nfor example, a new `Edit with AI` action in a popover header belongs in the\ntop-right header slot, aligned with the title, not in the body or footer. Use\nthe same frame size, scale, outer padding, border radius, and visual density on\nboth sides unless the change itself alters those properties, and let the frame\nheight fit the content rather than leaving a tall empty lower half.\n\n**Name the states with the column header, never inside the frame.** For\ndocument-body wireframes (recaps), put the two\nstates in a `columns` block and set each column's `label` to `Before` and\n`After` \u2014 the renderer draws that label as an `h4` heading above each frame. Do\nNOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a\nlabel placed inside reads as part of the product UI, lands in a random corner,\nand clutters the comparison. The column header is the one and only place the\nstate name belongs. On a canvas, place the two state artboards as neighbors with\nframe labels \u2014 never encode Before/After inside the html.\n\n**Let the surface choose side-by-side vs. stacked.** For document-body\nwireframes (recaps), the `columns` renderer lays\nnarrow surfaces (`mobile`, `popover`, `panel`) out side by side, and\nautomatically stacks wide surfaces (`desktop`, `browser`) vertically at full\ndocument width so a large frame is never crushed into a half-width column and\ncropped. Author both wireframes with the real `surface` and the matching\n`Before`/`After` column labels; do not hand-stack the pair into separate\ntop-level wireframes or duplicate the state name as body content.\n\n**Good example \u2014 a contacts list, surface `browser`.** A small, real screen\ncomposed from the helper classes and tokens, layout in inline flex, no fonts or\nhex colors:\n\n```html\n<div\n  style=\"display:flex;flex-direction:column;gap:12px;padding:16px;height:100%\"\n>\n  <div style=\"display:flex;align-items:center;justify-content:space-between\">\n    <h1>Contacts</h1>\n    <button class=\"primary\">New contact</button>\n  </div>\n  <div style=\"display:flex;gap:6px\">\n    <span class=\"wf-pill accent\">All 128</span>\n    <span class=\"wf-pill\">Favorites</span>\n    <span class=\"wf-pill\">Archived</span>\n  </div>\n  <div\n    class=\"wf-card\"\n    style=\"display:flex;flex-direction:column;gap:0;padding:0\"\n  >\n    <div\n      style=\"display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)\"\n    >\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>\n      </div>\n      <span class=\"wf-pill\">Lead</span>\n    </div>\n    <div style=\"display:flex;align-items:center;gap:10px;padding:10px 12px\">\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>\n      </div>\n      <span class=\"wf-pill\">Customer</span>\n    </div>\n  </div>\n</div>\n```\n\n<!-- SHARED-CORE:wireframe-quality END -->\n";
 export declare const CANVAS_REFERENCE_MD = "# Canvas & artboard placement \u2014 single source of truth\n\nThis file is the canonical guide for how the visual-plan canvas works: artboard\nplacement, lane layout, annotations, patching, and the legacy kit tree. Read it\nin full before authoring or editing any canvas/artboard content; do not author\ncanvas layouts from memory or paraphrase these rules per mode.\n\n<!-- SHARED-CORE:canvas-surface START -->\n\n**The coordinate rule.** The `surface` locks each artboard's footprint and\naspect \u2014 never set artboard width/height and never use coordinates inside the\nwireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear\nlanes. Let canvas auto-placement handle simple one-row boards.\n\n**Lay out mixed canvases in lanes.** When a canvas contains broad browser /\ndesktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put\neverything in one horizontal strip. Use board-level artboard `x`/`y` to reserve\nlanes with generous empty space: main flow on one row, compact surfaces in their\nown column or row, and loading/error states in a lower row. Keep at least 96px\nbetween rendered artboard rectangles plus room for annotation gutters; when a\nbroad browser/desktop frame sits beside a compact panel/popover, leave at least\n160px so frame borders, labels, and hover controls never touch. Connect only\nneighboring steps; never draw a long connector that skips across unrelated\nframes. Connector labels must sit in open canvas space. If the label would touch\nor cross either artboard, remove the label and explain the transition with a\nnearby annotation instead. Before handoff, inspect the top canvas at default zoom\nand move any frame whose label, connector, or annotation crosses another frame.\n\n**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. `browser` frames occupy roughly 700 \u00D7 600 board units; `desktop` frames roughly 900 \u00D7 700 board units. Apply these minimum x/y gaps when placing frames explicitly \u2014 any less and frames will touch or overlap:\n\n- x-gap between `browser` frames: **\u2265 1100** (700-unit frame + 400-unit gutter)\n- x-gap between `desktop` frames: **\u2265 1300** (900-unit frame + 400-unit gutter)\n- y-gap between rows of any surface: **\u2265 1400** (includes frame height + section header + buffer)\n\nWhen in doubt, use larger values \u2014 the canvas auto-zooms to fit everything.\n\n**Canvas annotations are designer notes on the artboard.** When a top canvas is\npresent, sprinkle design-review notes near the frames they explain: a short\nheading, supporting text, and bullets \u2014 plain text layers, never bordered or\nshadowed cards, and never a box around a frame. The renderer spaces notes away\nfrom frames, so place each note by the frame it describes. Use an arrow only to\npoint at one specific control or transition; for a broad frame-level note, write\ntext beside the frame with no connector. Connectors are for real sequences only \u2014\nnever fake \"Step 1 \u2192 Step 2\" lines between independent states.\n\n**Do not create overlapping annotations.** Anchor each ordinary note to the\nframe it explains with `targetId` + `placement` (top/right/bottom/left), and\nomit `type` or use `type: \"note\"`. The renderer parks notes in a gutter beside\nthe frame and lays them out automatically. Do not use `type: \"callout\"`,\n`type: \"text\"`, `type: \"arrow\"`, x/y, or points for ordinary notes; those are\nfreeform review-markup layers and must be reserved for intentional markup in\nopen canvas space. Reserve arrows for a note that must point at one specific\ncontrol inside a frame; a note that simply sits beside its frame needs no arrow.\n\n**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`\n(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,\n`replace-blocks`, `update-canvas-annotation`) rather\nthan regenerating the whole plan. `contentPatches` are part of the public MCP\naction schema, so Claude Code, Codex, Cursor, and other hosts can make surgical\nedits. If an agent is working from exported source files, use\n`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds\nfrontmatter plus markdown/document blocks, `canvas.mdx` holds\n`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the\npatch action normalizes the MDX back into the same JSON runtime model. JSON is\nthe canonical runtime shape; MDX is the repo-friendly authoring/export surface.\nIn the browser, humans edit `rich-text` prose inline; agents should still use\n`update-rich-text` content patches or source patches for prose, and use\ncomments/structured patches for canvas, artboard, wireframe, and diagram edits.\nNever send a partial top-level `content` object as a shortcut to add a canvas,\nframe, or block: `content` is a full structured replacement, so omitted blocks\nor surfaces can disappear. If a full replacement is truly unavoidable, read the\ncomplete source/JSON first, include every existing block and surface in the new\npayload, and verify the source/export immediately after the update.\n\n**Never emit a titled artboard with no interior wireframe content.** Every artboard\nyou place on the canvas must carry an `html` wireframe or reference a wireframe\nblock via `blockId`; when using `blockId`, the referenced `wireframe` /\n`legacy-wireframe` block must remain in the plan. If you remove a duplicate\nwireframe from the document body, first move its `data` inline onto the\ncorresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A\nlabel-only frame or a frame pointing at a deleted block renders empty and is\nrejected at parse time. If you only have a title, write it as a section header or\nannotation, not an empty artboard.\n\n**UI mockups belong in the top visual review area.** Static UI/product visuals\nlive on the canvas; multi-step UI flows get both canvas wireframes and a\nprototype. When the user asks for a mockup, UI state, loading state, layout,\nscreen, or visual comparison, make the canvas the primary home for that static\nvisual. When the user asks for a prototype or the plan contains a sequence the\nreviewer must feel, keep the canvas artboards and add `content.prototype` so the\ntop surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay\ninline in the document (the SKILL.md Visual Surface Choice section owns that\nrule) unless the user explicitly asks for a spatial board. Document blocks\ncan explain, compare, or map implementation, but they should not host the\nprimary UI mockup or prototype just because `custom-html`, screenshots, or prose\nare easier to produce. If the canvas/prototype surface cannot represent the\nrequested UI fidelity, still keep the closest top-surface representation and\ncall out or extend the needed renderer capability. A skeleton/loading mockup\nalso lives in a canvas artboard \u2014 never move a mockup out of the canvas.\n\n**Storyboards are canvas artifacts, not document diagrams.** When the requested\noutput is a product flow, onboarding journey, \"light storyboard\", or canvas\nwireframe, author the flow as multiple top-canvas artboards with real screen\ncontent and neighboring connectors. Keep document-body `diagram` blocks for\narchitecture and mechanics that are not themselves user-visible screens. A\nstoryboard made from a single inline HTML diagram is the wrong surface.\n\nFor abstract product concepts, use the canvas to create the first \"I get it\"\nmoment: one real app state near the top showing how the concept appears to a\nuser, followed by separate annotations or diagrams for mechanics. Do not make\nthe first artboard a hybrid of app UI and architecture notes; the app screen\nshould be inspectable as product UI on its own.\n\n**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit\nnodes instead of `html`; the renderer still accepts and displays it so saved\nplans round-trip, but new plans emit `html`. Do not author fresh kit-tree\nscreens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,\n`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard\nwith kit-tree children is a defect: replace it with\n`<Screen surface=\"...\" html={...} />` using the HTML wireframe rules. The HTML\npath is the one that gets the renderer-owned surface sizing, theme tokens,\nsketch/clean toggle, and safe text layout used by good document-body\nwireframes. Likewise, old or imported plans may carry coordinate-based regions\nor free-float x/y on notes; those are legacy escape hatches the renderer still\nshows but you must never produce. The gutter parks notes by `targetId` +\n`placement`, and the coordinate rule at the top of this file governs all\nnew-plan placement.\n\n<!-- SHARED-CORE:canvas-surface END -->\n";
 export declare const DOCUMENT_QUALITY_REFERENCE_MD = "# Plan document quality \u2014 single source of truth\n\nThis file is the canonical quality bar for the plan document below the canvas:\nhow it reads, which blocks to use, how open questions are surfaced, and the\npre-handoff check. Read it in full before authoring the plan document; it is the\nquality bar. Do not write the document from memory or paraphrase these rules per\nmode.\n\n<!-- SHARED-CORE:document-quality START -->\n\n**The document is a serious technical plan, not marketing.** Write it the way a\nstrong Claude or Codex implementation plan reads: outcome-first, prose-first,\nself-contained, and specific. State the objective and what \"done\" means, the\nscope and non-goals, the proposed approach with the key decisions and their\nrationale, ordered steps that name real files, symbols, actions, and data\nshapes, the risks, and a closing verification step (tests, build, or a checkable\nbehavior). Replace vague prose with specifics; never ship a step like \"make it\nwork.\" No hero art, gradients, logos, nav bars, slogans, value props, giant\nlanding-page headings, or marketing cards unless the user explicitly asks.\n\n**Every published plan must stand alone.** Even when the agent is revising an\nexisting plan, the output is a plan to do the work, not a changelog of the\nconversation. Do not write phrases like \"preserve the previous plan\", \"do not\ndrop the old idea\", \"as discussed above\", \"this revision\", \"unlike the prior\nversion\", or \"correction from the earlier plan\". Fold the right decisions into\nthe plan as normal objective, architecture, scope, and roadmap prose. A reviewer\nwho opens the plan from a link with no chat history should understand it. Avoid\nnegative framing that only makes sense against absent context (\"not the old\nmode\", \"not just X\") unless the contrast is defined in the plan and genuinely\nhelps; state the positive model directly.\n\n**Make abstract plans instantly legible.** If the idea is broad, strategic, or\nintended for a third-party reviewer, put one concrete product snapshot near the\ntop before dense architecture, mode tables, manifests, or roadmaps. For\nUI-capable concepts, that snapshot is usually a top-canvas app state plus a\nshort paragraph that says what the user sees and what changes under the hood.\nThen put mechanics, data flow, sync boundaries, and implementation detail in\nseparate diagrams or document sections.\n\n**Preserve the user's level of abstraction.** A motivating use case is not\nautomatically the architecture. When the prompt describes a broader framework,\nproduct mode, or reusable primitive, separate the reusable core from specific\napps, providers, customers, scripts, or launch examples. Use the concrete\nexample to make the plan understandable, then make clear which parts are core,\nwhich are app-specific adapters, and which are future examples.\n\n**When top visuals exist, they and the document never duplicate each other.**\nFor UI work, the UI story lives in the top visual surface: canvas artboards for\nstatic inspection, plus prototype tabs when the flow should be functional. The\ndocument carries the technical depth the visuals cannot show \u2014 concrete\nfile/symbol maps, API and data contracts, code snippets, migration or\nimplementation phases, risks, and validation. For architecture/code reviews,\ninvert that: the document is the visual surface, and each recommendation\ncarries its own nearby inline `diagram` / `data-model` block plus file\nevidence (the `diagram` bullet below owns how to author those diagrams).\nRepeat a wireframe in the document only for a genuinely new detail view or\ncomparison. Skip the visual surface entirely for non-visual work and write a\nclean rich document. For a simple binary UI visual choice, show the two\ndirections in the canvas only; do not repeat the same options as body\nwireframes or prose. Put the actual choice in the bottom \"Open Questions\" form.\n\n**Use the right block, and make it carry substance.** For the authoritative,\nmachine-checked list of block types and their data schemas, call `get-plan-blocks`\n\u2014 it returns the live registry vocabulary (type, MDX tag, placement, key fields)\nso you never emit a block the editor cannot render or round-trip:\n\n- `rich-text` for plan prose with real bold/italic/code/links and nested lists.\n- `annotated-code` for the file map: when a load-bearing file is worth\n  highlighting, prefer the annotated walkthrough over a bare `code` block \u2014 carry\n  the real, syntax-highlighted code AND anchor short margin notes to the lines\n  that actually change (the new action, the changed schema, the wiring point), so\n  the reader sees what matters and why instead of code for code's sake. Each\n  annotation is `{ lines: \"12\" | \"12-18\"; label?; note }`; keep a few high-signal\n  notes per file, not one per line. Highlight only the files worth reading; never\n  an exhaustive list of every touched file, and never a prose-only description of\n  a file. Drop to a plain `code` block only for a throwaway snippet with nothing\n  to call out. When more than one file matters, group the blocks in a vertical\n  `tabs` block (the standard tab primitive) rather than a bespoke container. If\n  the exact code is unknown, show the smallest plausible planned shape or a\n  commented stub naming what to fill in. (`code-tabs` and `implementation-map`\n  are legacy: their renderers stay for old plans, but do not author new ones.)\n- For a decision: if the reviewer must still pick between a genuinely-open\n  either/or, put it in the bottom Open Questions `question-form` as a `single`\n  question \u2014 one option per real alternative, each with a short detail and\n  `recommended: true` on the one you would choose; do not also restate the same\n  choice elsewhere. If you have already committed to an approach, state it as\n  settled prose or a `callout` with `tone=\"decision\"`, optionally with a\n  `columns` block for a side-by-side comparison of the options you weighed \u2014 not\n  as a confusing mid-document form for a question you have already answered.\n- `columns` for side-by-side before/after or current/target comparisons where\n  each side needs real nested blocks; label the columns clearly and avoid\n  stacking comparison blocks vertically when parallel reading is the point.\n- `diagram` for two-dimensional architecture, dependency, data-flow, or state\n  relationships, only when it clarifies something real. Prefer standard\n  two-dimensional layouts \u2014 paired before/after panels, layered diagrams,\n  swimlanes, dependency maps, matrices, or grouped regions; do not default to\n  left-to-right chains, and use a line only when the relationship is truly a\n  sequence. Do not use a body `diagram` as the primary artifact for a requested\n  product canvas, light storyboard, UI flow, screen flow, or wireframe; those\n  belong in the top canvas as artboards with `Screen` wireframes first. Use\n  diagrams below that canvas only for architecture, data flow, or implementation\n  mechanics. For architecture/code\n  diagrams, prefer `data.html` / `data.css` with semantic HTML and inline SVG so\n  the diagram can use panels, layers, matrices, arrows, annotations, and\n  responsive layout directly. Author diagram HTML with renderer-owned primitives\n  like `.diagram-panel`, `.diagram-card`, `.diagram-node`, `.diagram-box`,\n  `.diagram-pill`, `.diagram-muted`, and `[data-rough]`; they map to the plan's\n  Tailwind theme variables through `--wf-ink`, `--wf-muted`, `--wf-line`,\n  `--wf-paper`, `--wf-card`, `--wf-accent`, `--wf-accent-soft`, `--wf-warn`, and\n  `--wf-ok`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not\n  set `font-family` and do not hard-code hex, rgb, or hsl colors in diagram HTML\n  or CSS. Leave room for the sketch font: keep labels short, give nodes generous\n  width, and place boundary/annotation labels in unused space instead of over\n  nodes; labels must not overlap nodes, connectors, or each other. For small\n  text/SVG changes to an existing HTML diagram, use `patch-diagram-html` with a\n  unique `find`/`replace` snippet instead of resending the whole `data.html`\n  string. Use legacy `nodes` / `edges` only for small previews or truly\n  sequential flows. In architecture/code plans, prefer a repeated section rhythm:\n  recommendation title, confidence and category badges, code-path evidence, a\n  local before/after or current/target spatial diagram, then concise\n  Problem/Solution/Why text.\n- `tabs` for multiple states, directions, or comparisons. A tab that reveals\n  only prose usually means the plan is under-specified \u2014 include a relevant\n  visual unless the tab is intentionally document-only.\n- `table`, `checklist`, `callout` for scannable structure.\n\n**Open questions live at the bottom as a form when answers would change the\nplan.** Surface answerable unresolved decisions in a final `question-form`\nblock titled \"Open Questions\" so the renderer presents it as a distinct section.\nThat bottom form is the ONLY place that enumerates the open questions: never add\na second \"Open Questions\" heading, list, or recap of the same questions earlier\nin the document. A one-line pointer in the overview prose (\"a few decisions are\nstill open \u2014 see Open Questions below\") is fine, but do not reproduce the\nquestion list or a parallel questions/decisions section above it.\nUse `single` or `multi` for clear choices, `freeform` for constraints,\n`recommended: true` for the default you would pick, and option `wireframe` /\n`diagram` previews only when the options are not already visible in the top\ncanvas. `single` and `multi` questions always render a write-in field so a\nreviewer can answer with a custom option \u2014 never add an explicit \"Other\" option\nyourself; set `allowOther: false` only when a free-text answer makes no sense.\nKeep non-answerable assumptions or risks as concise `callout` blocks in\nthe relevant section. Never bury a questions/decisions wall inside the plan\nnarrative, and never ask the same question twice.\n\nFor complex plans, do not end without an open-question audit. If architecture,\nscope, UX, data shape, rollout, provider mapping, or ownership still depends on\na choice, either commit to a recommendation with rationale or add it to the\nbottom form with a recommended default. A complex plan with no open questions is\nfine only when every meaningful decision has been explicitly made.\n\n**Verification must exercise the real workflow.** The final verification section\nshould go beyond typecheck/unit tests when the plan changes UI, local files,\nsync, providers, browser behavior, or multi-app flows. Include at least one\nend-to-end smoke that matches the user journey, such as a fresh repo/folder,\nreal manifest or data fixture, browser interaction, save/sync action, and an\non-disk or database assertion. Name the command or manual browser path when it\nis known.\n\n**`custom-html` is a bounded escape hatch only** \u2014 a single complete fragment\ninside a block, never `html`/`head`/`body`/`script` tags, never a generic\nplaceholder, density demo, or proof that custom HTML works. Prefer the native\nblocks for normal plans. For architecture/code reviews, use `diagram`\n`data.html` / `data.css` for rich local HTML/SVG diagrams instead of\n`custom-html`. For UI/product work, `custom-html` is never the primary home for a\nrequested mockup, UI state, or visual comparison. If UI fidelity requires\nHTML/CSS, image capture, or real React/CSS, the product fix is canvas support\nfor that artifact type, not moving the mockup into the document.\nWhen `custom-html` is genuinely needed, author it against the sandbox-provided\ntheme tokens (`--wf-paper`, `--wf-card`, `--wf-ink`, `--wf-muted`,\n`--wf-line`, `--wf-radius`, and the matching `--plan-*` aliases). Do not hardcode\nhex/rgb/hsl light palettes such as white cards with dark ink; the same fragment\nmust read in dark mode without a plan-specific patch.\n\n**Before handoff, open the plan and check it.** Fix overlap, excessive\nwhitespace, clipped fragments, misleading inactive controls, poor contrast, and\nunreadable diagrams before asking for approval. Check the top canvas in the\ncurrent Plan theme, especially dark mode: white mockup panels, low-contrast\nmuted text, or invisible controls are defects. If a frame only works in one\ntheme, rewrite the HTML with `--wf-*` tokens and semantic helper classes before\nsurfacing the plan.\n\n<!-- SHARED-CORE:document-quality END -->\n";
 export declare const EXEMPLAR_REFERENCE_MD = "# Good vs. bad exemplar \u2014 single source of truth\n\nThis file is the canonical worked example of a great plan (and the anti-patterns\nto avoid). Read it alongside the document-quality and canvas references before\nauthoring a plan; it is the bar these plans must clear.\n\n<!-- SHARED-CORE:exemplar START -->\n\n**GOOD.** A UI-first plan for a todo app: a canvas with a `desktop` artboard whose\n`data.html` is a real flex layout \u2014 a sidebar of links (`Inbox 12`, `Today 4`,\n`Done`), a main column with an `<h1>Today</h1>`, accent `.wf-pill`s for the\nfilters, a muted section label `OVERDUE`, and `.wf-card` task rows carrying real\ntitles, due dates, and a primary `button.primary` \u2014 styled only through bare\nelements, helper classes, and `--wf-*` tokens, so the renderer applies the\ncorrect desktop footprint, theme, and one subtle whole-frame wobble. Plain-text\ndesigner notes sit spaced off the frame, pointing only at the controls that need\nexplanation. Below it, a Claude/Codex-grade document: objective and\ndone-criteria, a few `code` blocks (grouped in a vertical `tabs` block when\nmore than one) showing the real shape of the load-bearing files, a `callout`\nwith `tone=\"decision\"` stating the chosen approach with a `columns` block\nweighing the two real options behind it,\nand a validation step \u2014 none of it repeating the canvas. If the task also\nchanges a multi-step completion flow, the same top area includes a Prototype tab\nwhose screens use the same labels and states as the canvas artboards, with\n`data-goto` controls for the sequence. This is the bar.\n\n**GOOD.** A broad product-architecture plan opens with a plain recommendation\nand one concrete app state before the abstraction. The first canvas artboard is\npure product UI that matches the current app shell; nearby notes explain the\nuser-visible delta. A separate diagram below shows the mechanics, such as file\nor data flow. The document then separates the reusable core from app/provider\nadapters and examples, covers contracts, folder or schema shape, sync\nboundaries, roadmap, non-goals, a bottom Open Questions form for unresolved\ndecisions, and a verification section with at least one realistic end-to-end\nsmoke. A reviewer who was not in the chat gets the idea from the top snapshot\nbefore reading the technical plan.\n\n**GOOD.** A `/visual-plan` for a backend architecture review: no top canvas.\nThe document opens with context and a legend, then repeats recommendation cards:\ntitle, confidence/category badges, a monospace grid of real file paths, one\ninline two-dimensional before/after or layered architecture diagram, and terse\nProblem/Solution/Why bullets using the codebase's vocabulary. The diagram uses\nspace to show boundaries, layers, and ownership; it is not a default\nleft-to-right chain. The plan ends with a top recommendation and a bottom\nquestion-form only if the next architecture direction is genuinely open. This is\nbetter than a top canvas because each diagram is local to the claim it supports.\n\n**BAD.** A `data.html` with hard-coded hex colors, a `font-family`, or fixed\npixel width/height; gray placeholder bars \"insinuating\" text on a non-skeleton\nframe; a forced desktop + mobile pair for a popover; floating bordered\nannotation cards hugging the frames; a fresh hand-authored kit-tree `screen`\ninstead of `html`; a multi-step UI flow with only static frames and no prototype\ntab; a mockup escaped into a document `custom-html` block; and a marketing-style\ndocument with a hero heading and value props that just restates what the canvas\nalready shows. Also bad: an architecture-only plan forced into a top canvas of\nlabeled boxes with overlapping text, where the actual code evidence and\nrecommendations live elsewhere; a product wireframe that mixes a real screen\nwith repo names, file-contract arrows, architecture explanations, or a made-up\npermanent inspector; and a plan that describes itself as a revision of a prior\nconversation instead of a standalone proposal. Never produce this.\n\n<!-- SHARED-CORE:exemplar END -->\n";