@agent-native/core 0.84.6 → 0.84.8

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2043
-- template files: 4906
+- template files: 4908

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.84.8
+
+### Patch Changes
+
+- b5cc580: Show a visible warning when an agent run completes tools but stops before sending any final assistant text.
+
+## 0.84.7
+
+### Patch Changes
+
+- ab1e410: Stop repeated agent-chat action-preparation loops with a clear terminal warning, and let Design agents present compact variant directions without streaming large HTML payloads.
+
 ## 0.84.6
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.6",
+  "version": "0.84.8",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -93,6 +93,12 @@ const MAX_EMPTY_TRANSIENT_CONTINUATIONS = 3;
 // round re-sending any large pasted payload) before bailing. Catching the
 // repeat ends it in a few rounds with a clear, actionable message instead.
 const MAX_REPEATED_TRANSIENT_CONTINUATIONS = 3;
+// How many consecutive continuations that only reach the SAME "preparing
+// action" activity card we tolerate before giving up. This catches runs that
+// keep timing out while assembling a large tool payload: they are not empty,
+// and the narration may vary enough to bypass the text-repeat guard, but the
+// real tool never starts.
+const MAX_REPEATED_ACTION_PREPARATION_CONTINUATIONS = 3;
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_DELAY_MS = 8_000;
 const MAX_HISTORY_ATTACHMENT_CHARS = 60_000;
@@ -782,6 +788,22 @@ function lastActivityTool(
   return undefined;
 }
 
+function lastUnresolvedToolActivity(
+  content: ContentPart[],
+): string | undefined {
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i];
+    if (
+      part.type === "tool-call" &&
+      part.activity === true &&
+      part.result === undefined
+    ) {
+      return part.toolName;
+    }
+  }
+  return undefined;
+}
+
 function snapshotContent(content: ContentPart[]): ContentPart[] {
   return content.map((part) =>
     part.type === "text" ? { ...part } : { ...part, args: { ...part.args } },
@@ -889,7 +911,7 @@ function incrementalActionGuidance(tool: string): string | undefined {
     case "update-design":
       return "persist a minimal first version (fewer files) with `generate-design`, then refine individual files with `edit-design` search/replace instead of resending everything";
     case "present-design-variants":
-      return "save compact but complete variant screens with `present-design-variants` first, keeping each HTML direction focused enough to finish, then refine the chosen direction with `generate-design` or `edit-design`";
+      return "call `present-design-variants` with concise labels, descriptions, accent colors, and feature bullets; omit large `content` HTML when needed so the action can render compact representative screens, then refine the chosen direction with `generate-design` or `edit-design`";
     case "create-visual-plan":
     case "create-ui-plan":
     case "create-plan-design":
@@ -1390,6 +1412,9 @@ export function createAgentChatAdapter(
       let repeatedInFlightToolCount = 0;
       let recoveryGaveUpOnInFlightTool = false;
       const MAX_REPEATED_INFLIGHT_TOOL_STALLS = 3;
+      let lastPreparingToolName: string | undefined;
+      let repeatedActionPreparationCount = 0;
+      let recoveryGaveUpOnActionPreparation = false;
       const continuationHistoryFragments: string[] = [];
       const structuredContinuationFragments: AgentChatStructuredMessage[] = [];
       let visibleContinuationPrefix: ContentPart[] = [];
@@ -1420,6 +1445,10 @@ export function createAgentChatAdapter(
           lastInFlightToolName
             ? `last_inflight_tool: ${lastInFlightToolName}`
             : "",
+          `repeated_action_preparation_stalls: ${repeatedActionPreparationCount}`,
+          lastPreparingToolName
+            ? `last_preparing_tool: ${lastPreparingToolName}`
+            : "",
           `total_transient_continuations: ${totalTransientContinuationAttempts}`,
           attemptedRunIds.length > 0
             ? `attempted_runs: ${attemptedRunIds.join(", ")}`
@@ -1436,6 +1465,12 @@ export function createAgentChatAdapter(
         if (recoveryGaveUpOnRepetition) {
           return "The agent got stuck repeating the same response without finishing, so I stopped the automatic retries. This often happens when it tries to re-type a large pasted file into one action — starting a new chat, or asking for a smaller first step, usually gets it unstuck.";
         }
+        if (recoveryGaveUpOnActionPreparation) {
+          const tool = lastPreparingToolName
+            ? ` the ${humanizeActionName(lastPreparingToolName)} action`
+            : " the same action";
+          return `The agent got stuck preparing${tool} input and never started the tool, so I stopped the automatic retries. Try a smaller first step or a more compact version of the request.`;
+        }
         if (
           content.length === 0 &&
           (reason === "run_timeout" ||
@@ -1512,6 +1547,8 @@ export function createAgentChatAdapter(
             repeatedTransientContinuationAttempts,
             repeatedInFlightToolCount,
             lastInFlightToolName,
+            repeatedActionPreparationCount,
+            lastPreparingToolName,
             totalTransientContinuationAttempts,
             ...extra,
           },
@@ -1529,6 +1566,8 @@ export function createAgentChatAdapter(
               repeatedTransientContinuationAttempts,
               repeatedInFlightToolCount,
               lastInFlightToolName,
+              repeatedActionPreparationCount,
+              lastPreparingToolName,
               totalTransientContinuationAttempts,
             },
           },
@@ -1832,8 +1871,13 @@ export function createAgentChatAdapter(
           // for the stalled/empty caps.
           const madeProgress = madeContentProgress || hasInFlightTool;
           const madeDurableToolProgress = visibleContent.some(
-            (part) => part.type === "tool-call" && part.result !== undefined,
+            (part) =>
+              part.type === "tool-call" &&
+              part.activity !== true &&
+              part.result !== undefined,
           );
+          const currentPreparingToolName =
+            lastUnresolvedToolActivity(visibleContent);
           // In-flight tool stall guard. When the same write tool is stuck
           // in-flight because the connection keeps dropping (stream_ended),
           // hasInFlightTool=true keeps madeProgress=true and completely
@@ -1877,6 +1921,27 @@ export function createAgentChatAdapter(
             repeatedInFlightToolCount = 0;
           }
 
+          const isRepeatedActionPreparationCandidate =
+            signal.reason !== "loop_limit" &&
+            currentPreparingToolName !== undefined &&
+            !hasInFlightTool &&
+            !madeDurableToolProgress;
+          if (isRepeatedActionPreparationCandidate) {
+            if (currentPreparingToolName === lastPreparingToolName) {
+              repeatedActionPreparationCount += 1;
+            } else {
+              repeatedActionPreparationCount = 0;
+              lastPreparingToolName = currentPreparingToolName;
+            }
+          } else if (
+            !currentPreparingToolName ||
+            hasInFlightTool ||
+            madeDurableToolProgress
+          ) {
+            repeatedActionPreparationCount = 0;
+            lastPreparingToolName = undefined;
+          }
+
           // Degenerate repetition guard. When the model gets stuck re-streaming
           // the SAME narration every continuation without ever starting or
           // finishing a tool, each round is "new" text — so madeProgress stays
@@ -1925,6 +1990,13 @@ export function createAgentChatAdapter(
               recoveryGaveUpOnInFlightTool = true;
               return { ok: false, resetVisibleContent: false };
             }
+            if (
+              repeatedActionPreparationCount >
+              MAX_REPEATED_ACTION_PREPARATION_CONTINUATIONS
+            ) {
+              recoveryGaveUpOnActionPreparation = true;
+              return { ok: false, resetVisibleContent: false };
+            }
             // Bail fast on a non-advancing repetition loop, well before the
             // stalled/empty/total budgets would (each round otherwise re-sends
             // the whole pasted payload). Tracked separately so it never trips

package/corpus/core/src/client/sse-event-processor.ts

@@ -381,6 +381,33 @@ function interruptedToolMessage(pending: {
   return `The agent stopped before starting ${actionLabel}. No tool result was returned, so the requested changes were not made.`;
 }
 
+function hasAssistantText(content: ContentPart[]): boolean {
+  return content.some(
+    (part) => part.type === "text" && part.text.trim().length > 0,
+  );
+}
+
+function completedToolNames(content: ContentPart[]): string[] {
+  const names = new Set<string>();
+  for (const part of content) {
+    if (
+      part.type === "tool-call" &&
+      part.activity !== true &&
+      part.result !== undefined &&
+      part.isError !== true
+    ) {
+      names.add(part.toolName);
+    }
+  }
+  return [...names];
+}
+
+function completedToolOnlyMessage(toolNames: string[]): string | null {
+  if (toolNames.length === 0) return null;
+  const label = formatToolNames(toolNames);
+  return `The agent completed ${label}, but stopped before sending a final message. Review the completed tool card above or ask the agent to continue.`;
+}
+
 /**
  * Process a single SSE event and update the content accumulator.
  * Returns: "continue" to keep going, "done" to stop, or a yield-ready result.
@@ -825,6 +852,31 @@ export function processEvent(
         } as ChatModelRunResult,
       };
     }
+    const toolOnlyMessage = hasAssistantText(content)
+      ? null
+      : completedToolOnlyMessage(completedToolNames(content));
+    if (toolOnlyMessage) {
+      content.push({
+        type: "text",
+        text: toolOnlyMessage,
+      });
+      return {
+        action: "done",
+        result: {
+          content: [...content],
+          status: { type: "complete" as const, reason: "stop" as const },
+          metadata: {
+            custom: {
+              runWarning: {
+                message: toolOnlyMessage,
+                errorCode: "final_response_missing_after_tool",
+                recoverable: true,
+              },
+            },
+          },
+        } as ChatModelRunResult,
+      };
+    }
     return {
       action: "done",
       result: { content: [...content] } as ChatModelRunResult,

package/corpus/templates/design/AGENTS.md

@@ -133,9 +133,11 @@ patterns live in `.agents/skills/`.
   write-back remains a localhost/fusion follow-up capability.
 - For multi-variant work, use `present-design-variants` so every candidate is
   saved as a normal overview-board screen and the user gets one inline chat
-  button per screen name. Keep each variant compact: one representative screen
-  or directional snapshot, not a full app per variant. After the user picks,
-  delete the unchosen variant screens before continuing from the kept screen.
+  button per screen name. Keep each variant compact: prefer concise labels,
+  descriptions, accent colors, and feature bullets, and omit full HTML when it
+  would make the tool input too large. The action can render representative
+  screens from direction data. After the user picks, delete the unchosen
+  variant screens before continuing from the kept screen.
 - Use framework sharing actions for design and design-system visibility/grants.
 - `/visual-edit` is a public entry route and public `/design/:id` links may
   render read-only public designs without a session. Do not open anonymous write
@@ -218,10 +220,10 @@ patterns live in `.agents/skills/`.
   register that manifest with `connect-localhost`, call `add-localhost-screens`,
   and open the editor in overview mode.
 - For human-in-the-loop UI exploration, create a design shell, call
-  `present-design-variants` with 2-5 compact, complete HTML directions (three
-  by default), wait for the user to pick one in chat, delete the other
-  generated variant screens with `delete-file`, then use `get-design-snapshot`
-  and `generate-design` or `edit-design` for follow-up refinements.
+  `present-design-variants` with 2-5 concise directions (three by default),
+  wait for the user to pick one in chat, delete the other generated variant
+  screens with `delete-file`, then use `get-design-snapshot` and
+  `generate-design` or `edit-design` for follow-up refinements.
 - If inline chat choice buttons are unavailable, the user can tell you the
   preferred screen name. Do not show a separate variant picker or ask them to
   paste a copyable handoff summary.

package/corpus/templates/design/actions/present-design-variants.ts

@@ -48,11 +48,26 @@ const variantSchema = z.object({
     .string()
     .min(1)
     .describe("Short user-facing screen name, e.g. 'One-Line Focus'"),
+  description: z
+    .string()
+    .optional()
+    .describe(
+      "Short visual direction summary. Use this instead of a huge HTML payload when exploring variants quickly.",
+    ),
+  accentColor: z
+    .string()
+    .optional()
+    .describe("Optional CSS color used as this variant's primary accent."),
+  features: z
+    .array(z.string())
+    .max(8)
+    .optional()
+    .describe("Optional short feature/polish bullets to show in the variant."),
   content: z
     .string()
-    .min(1)
+    .optional()
     .describe(
-      "Complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. Inline the CSS needed for the preview; avoid relying on external CSS/script CDNs because app sandboxes may block them.",
+      "Optional complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. For faster exploration, omit this and provide label/description/features; Design will generate a compact representative screen.",
     ),
   width: z
     .number()
@@ -137,14 +152,17 @@ function boundedDimension(value: unknown, min: number, max: number) {
     : undefined;
 }
 
-function inferVariantSize(variant: z.infer<typeof variantSchema>) {
+function inferVariantSize(
+  variant: z.infer<typeof variantSchema>,
+  prompt?: string,
+) {
   const explicitWidth = boundedDimension(variant.width, 240, 1920);
   const explicitHeight = boundedDimension(variant.height, 240, 3000);
   if (explicitWidth && explicitHeight) {
     return { width: explicitWidth, height: explicitHeight };
   }
 
-  const content = variant.content;
+  const content = variant.content ?? "";
   const cssWidth =
     firstCssPixelValue(content, "width") ??
     firstCssPixelValue(content, "max-width") ??
@@ -167,7 +185,15 @@ function inferVariantSize(variant: z.infer<typeof variantSchema>) {
     };
   }
 
-  const lowercase = content.toLowerCase();
+  const lowercase = [
+    content,
+    variant.label,
+    variant.description ?? "",
+    ...(variant.features ?? []),
+    prompt ?? "",
+  ]
+    .join(" ")
+    .toLowerCase();
   if (
     /\b(?:mobile|phone|iphone|android)\b/.test(lowercase) ||
     /\b(?:max-w-sm|max-w-md|w-\[(?:360|375|390|393|414)px\])\b/.test(lowercase)
@@ -190,6 +216,163 @@ function inferVariantSize(variant: z.infer<typeof variantSchema>) {
   };
 }
 
+function escapeHtml(value: string) {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function colorForVariant(
+  variant: z.infer<typeof variantSchema>,
+  index: number,
+) {
+  const provided = variant.accentColor?.trim();
+  if (provided) return provided;
+  return ["#8b5cf6", "#06b6d4", "#10b981", "#f43f5e", "#f59e0b"][index % 5]!;
+}
+
+function fallbackVariantContent(
+  variant: z.infer<typeof variantSchema>,
+  index: number,
+  prompt?: string,
+  size: { width: number; height: number } = {
+    width: DESKTOP_WIDTH,
+    height: DESKTOP_HEIGHT,
+  },
+) {
+  const label = escapeHtml(variant.label.trim() || optionName(index));
+  const description = escapeHtml(
+    variant.description?.trim() ||
+      "A compact dark-mode product direction with a clear primary workflow, crisp hierarchy, and fast keyboard-first flow.",
+  );
+  const sourcePrompt = escapeHtml(
+    prompt?.trim() ||
+      "Generated app interface direction with a polished workflow and production-ready interaction model.",
+  );
+  const accent = escapeHtml(colorForVariant(variant, index));
+  const features =
+    variant.features && variant.features.length > 0
+      ? variant.features.slice(0, 6)
+      : [
+          "Primary workflow",
+          "Fast capture",
+          "Structured details",
+          "Status tracking",
+          "Inline editing",
+          "Shortcut hints",
+        ];
+  const safeFeatures = features.map((feature) => escapeHtml(feature));
+  const cardTitles = [
+    safeFeatures[0] ?? "Primary workflow",
+    safeFeatures[1] ?? "Structured details",
+    safeFeatures[2] ?? "Polished interactions",
+    safeFeatures[3] ?? "Status tracking",
+    safeFeatures[4] ?? "Review flow",
+  ];
+  const density =
+    index % 3 === 0 ? "spacious" : index % 3 === 1 ? "glass" : "dense";
+  const screenWidth = Math.round(size.width);
+  const screenHeight = Math.round(size.height);
+  const compact = screenWidth <= 560;
+  const tablet = screenWidth > 560 && screenWidth <= 900;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${label}</title>
+<style>
+:root { color-scheme: dark; --accent: ${accent}; --bg: #080a0f; --panel: rgba(18, 22, 33, 0.82); --line: rgba(255,255,255,.11); --muted: #94a3b8; }
+* { box-sizing: border-box; }
+body { margin: 0; width: ${screenWidth}px; min-height: ${screenHeight}px; overflow: hidden; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #f8fafc; background:
+  radial-gradient(circle at 18% 8%, color-mix(in srgb, var(--accent) 42%, transparent), transparent 30%),
+  linear-gradient(140deg, #05070b 0%, #111827 48%, #05070b 100%); }
+.shell { width: ${screenWidth}px; min-height: ${screenHeight}px; padding: ${compact ? "18" : "34"}px; display: grid; grid-template-columns: ${compact ? "1fr" : tablet ? "220px 1fr" : "258px 1fr 304px"}; gap: ${compact ? "14" : "22"}px; }
+.panel { border: 1px solid var(--line); background: var(--panel); border-radius: ${density === "dense" ? "14" : "22"}px; box-shadow: 0 24px 80px rgba(0,0,0,.35); backdrop-filter: blur(${density === "glass" ? "26" : "10"}px); }
+.sidebar { padding: 22px; display: flex; flex-direction: column; gap: 18px; }
+.brand { display:flex; align-items:center; justify-content:space-between; gap:12px; }
+.mark { width: 40px; height: 40px; border-radius: 14px; background: var(--accent); box-shadow: 0 0 32px color-mix(in srgb, var(--accent) 58%, transparent); display:grid; place-items:center; font-weight:800; color:#05070b; }
+h1 { margin: 0; font-size: 32px; line-height: 1.05; letter-spacing: 0; }
+h2 { margin: 0; font-size: 16px; letter-spacing: 0; }
+p { margin: 0; color: var(--muted); line-height: 1.5; }
+.nav, .tasks, .right { display: grid; gap: 12px; }
+.nav div, .task, .metric, .calendar { border: 1px solid var(--line); border-radius: 14px; background: rgba(255,255,255,.045); padding: 13px 14px; }
+.nav div:first-child { color: #fff; background: color-mix(in srgb, var(--accent) 18%, rgba(255,255,255,.06)); border-color: color-mix(in srgb, var(--accent) 48%, var(--line)); }
+.main { padding: 24px; display:flex; flex-direction:column; gap:18px; }
+.top { display:flex; align-items:flex-start; justify-content:space-between; gap:18px; }
+.badge { border:1px solid color-mix(in srgb, var(--accent) 45%, var(--line)); color:#fff; background: color-mix(in srgb, var(--accent) 20%, transparent); padding:8px 11px; border-radius:999px; font-size:12px; }
+.board { display:grid; grid-template-columns: ${compact ? "1fr" : "repeat(3, 1fr)"}; gap:14px; flex:1; min-height:0; }
+.column { border:1px solid var(--line); border-radius:18px; background:rgba(255,255,255,.035); padding:14px; display:flex; flex-direction:column; gap:12px; }
+.column header { display:flex; justify-content:space-between; align-items:center; color:#cbd5e1; font-size:13px; }
+.task { display:grid; gap:10px; padding:14px; }
+.task strong { font-size:14px; line-height:1.25; }
+.meta { display:flex; flex-wrap:wrap; gap:7px; }
+.chip { font-size:11px; color:#dbeafe; border:1px solid rgba(255,255,255,.12); background:rgba(255,255,255,.055); border-radius:999px; padding:5px 8px; }
+.priority { color:#fff; background: color-mix(in srgb, var(--accent) 22%, rgba(255,255,255,.06)); border-color: color-mix(in srgb, var(--accent) 46%, var(--line)); }
+.right { padding:22px; align-content:start; }
+.metric { display:grid; gap:8px; }
+.metric b { font-size:28px; }
+.calendar { display:grid; grid-template-columns: repeat(7, 1fr); gap:7px; }
+.calendar span { display:grid; place-items:center; height:32px; border-radius:10px; color:#cbd5e1; background:rgba(255,255,255,.04); font-size:12px; }
+.calendar .hot { color:#05070b; background:var(--accent); font-weight:800; }
+.features { display:flex; flex-wrap:wrap; gap:8px; }
+.shortcut { margin-top:auto; border-top:1px solid var(--line); padding-top:14px; display:flex; justify-content:space-between; gap:10px; color:#cbd5e1; font-size:12px; }
+${tablet ? ".right { display: none; }" : ""}
+${compact ? ".sidebar { padding: 16px; } .nav { grid-template-columns: repeat(2, minmax(0, 1fr)); } .nav div { padding: 10px; } .main { padding: 18px; } .top { display: grid; } .top .badge { width: fit-content; } h1 { font-size: 26px; } .right { display: none; } .column:nth-child(n+3) { display: none; }" : ""}
+</style>
+</head>
+<body>
+<main class="shell">
+  <aside class="panel sidebar">
+    <div class="brand"><div class="mark">${escapeHtml(String.fromCharCode(65 + index))}</div><span class="badge">${label}</span></div>
+    <div>
+      <h2>Direction</h2>
+      <p>${description}</p>
+    </div>
+    <div class="nav">
+      <div>Overview</div><div>Primary flow</div><div>Details</div><div>Timeline</div><div>Output</div>
+    </div>
+    <div class="features">${safeFeatures.map((feature) => `<span class="chip">${feature}</span>`).join("")}</div>
+    <div class="shortcut"><span>⌘K command</span><span>G then B</span></div>
+  </aside>
+  <section class="panel main">
+    <div class="top">
+      <div><h1>${label}</h1><p>${sourcePrompt}</p></div>
+      <span class="badge">${compact ? "Mobile" : tablet ? "Tablet" : "Desktop"} concept · live data</span>
+    </div>
+    <div class="board">
+      <section class="column"><header><span>Focus</span><b>4</b></header>
+        <article class="task"><strong>${cardTitles[0]}</strong><div class="meta"><span class="chip priority">Primary</span><span class="chip">Now</span><span class="chip">Fast path</span></div></article>
+        <article class="task"><strong>${cardTitles[1]}</strong><div class="meta"><span class="chip">Detail view</span><span class="chip">Shortcut E</span></div></article>
+      </section>
+      <section class="column"><header><span>Build</span><b>6</b></header>
+        <article class="task"><strong>${cardTitles[2]}</strong><div class="meta"><span class="chip priority">P2</span><span class="chip">Flow</span></div></article>
+        <article class="task"><strong>${cardTitles[3]}</strong><div class="meta"><span class="chip">Inline edit</span><span class="chip">Next</span></div></article>
+      </section>
+      <section class="column"><header><span>Ready</span><b>12</b></header>
+        <article class="task"><strong>${cardTitles[4]}</strong><div class="meta"><span class="chip">Complete</span><span class="chip">Motion ready</span></div></article>
+      </section>
+    </div>
+  </section>
+  <aside class="panel right">
+    <h2>Progress</h2>
+    <div class="metric"><p>Current flow</p><b>68%</b><p>Representative state for this direction</p></div>
+    <h2>Timeline</h2>
+    <div class="calendar">${Array.from({ length: 14 }, (_, day) => `<span class="${day === 4 || day === 9 ? "hot" : ""}">${day + 1}</span>`).join("")}</div>
+    <h2>Key moments</h2>
+    <div class="tasks">
+      <div class="task"><strong>${safeFeatures[0] ?? "Primary workflow"}</strong><div class="meta"><span class="chip priority">Hero</span><span class="chip">45m</span></div></div>
+      <div class="task"><strong>${safeFeatures[1] ?? "Polished interaction"}</strong><div class="meta"><span class="chip">Motion</span><span class="chip">⌘ Enter</span></div></div>
+    </div>
+  </aside>
+</main>
+</body>
+</html>`;
+}
+
 function placeVariantScreens(screens: VariantScreen[]) {
   const placements: CanvasFramePlacement[] = [];
   const columns = Math.min(MAX_COLUMNS, Math.max(1, screens.length));
@@ -228,7 +411,9 @@ export default defineAction({
     "exploration before follow-up refinement. After the user's choice, keep " +
     "the chosen screen, delete the other generated variant screens, and " +
     "continue from the kept screen. For complex apps, make each variant a " +
-    "compact but complete representative screen; expand the chosen direction " +
+    "compact representative screen; pass concise labels/descriptions/features " +
+    "and omit content when full HTML would be too large. Design will render " +
+    "compact screens from the direction data. Expand the chosen direction " +
     "after the user picks.",
   schema: z.object({
     designId: z.string().describe("Design project ID to show variants for"),
@@ -241,7 +426,7 @@ export default defineAction({
       .min(2)
       .max(5)
       .describe(
-        "2-5 concise, visually distinct generated design options to place as overview screens (3 is the sweet spot). Inline CSS so all options render in the app preview.",
+        "2-5 concise, visually distinct generated design options to place as overview screens (3 is the sweet spot). Prefer short label/description/features for each direction; include inline HTML content only when it is compact enough to finish.",
       ),
   }),
   mcpApp: {
@@ -280,18 +465,25 @@ export default defineAction({
       const preferredFilename = `variant-${slug}.html`;
       const filename = uniqueFilename(preferredFilename, usedFilenames);
       const fileId = nanoid();
-      const { width, height } = inferVariantSize(variant);
+      const providedContent = variant.content?.trim();
+      const initialSize = inferVariantSize(variant, prompt);
+      const content =
+        providedContent ||
+        fallbackVariantContent(variant, index, prompt, initialSize);
+      const { width, height } = providedContent
+        ? inferVariantSize({ ...variant, content })
+        : initialSize;
 
       await db.insert(schema.designFiles).values({
         id: fileId,
         designId,
         filename,
         fileType: "html",
-        content: variant.content,
+        content,
         createdAt: now,
         updatedAt: now,
       });
-      await seedFromText(fileId, variant.content);
+      await seedFromText(fileId, content);
 
       screens.push({
         id: fileId,

package/corpus/templates/design/actions/show-design-questions.ts

@@ -121,6 +121,12 @@ export default defineAction({
       submitLabel: submitLabel ?? "Continue",
       questions: normalizedQuestions,
     });
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "overview",
+      path: `/design/${encodeURIComponent(designId)}?view=overview`,
+    });
 
     return {
       designId,

package/corpus/templates/design/app/hooks/use-question-flow.ts

@@ -41,7 +41,7 @@ export function useQuestionFlow(
         formattedAnswers,
         "",
         designId
-          ? "Now continue the design. Honor any answer about variations: if the user asked to explore options, call present-design-variants with 2-5 compact, complete HTML directions - one representative screen per direction, not a full app per variant - wait for their chat pick, delete the unchosen variant screens, then continue from the kept screen; otherwise call generate-design with one complete, renderable index.html first. Do not ask another question unless a required decision is still genuinely missing."
+          ? "Now continue the design. Honor any answer about variations: if the user asked to explore options, call present-design-variants with 2-5 concise directions using label, description, accentColor, and feature bullets; omit large content HTML when needed because the action can render compact representative screens - wait for their chat pick, delete the unchosen variant screens, then continue from the kept screen; otherwise call generate-design with one complete, renderable index.html first. Do not ask another question unless a required decision is still genuinely missing."
           : "Now continue the design. Honor any answer about variations: use variants only if requested; otherwise generate one polished direction.",
       ]
         .filter(Boolean)
@@ -79,7 +79,7 @@ export function useQuestionFlow(
         formattedAnswers,
         "",
         designId
-          ? "Now continue the design. Honor any answer about variations: if the user asked to explore options, call present-design-variants with 2-5 compact, complete HTML directions - one representative screen per direction, not a full app per variant - wait for their chat pick, delete the unchosen variant screens, then continue from the kept screen; otherwise call generate-design with one complete, renderable index.html first. Do not ask another question unless a required decision is still genuinely missing."
+          ? "Now continue the design. Honor any answer about variations: if the user asked to explore options, call present-design-variants with 2-5 concise directions using label, description, accentColor, and feature bullets; omit large content HTML when needed because the action can render compact representative screens - wait for their chat pick, delete the unchosen variant screens, then continue from the kept screen; otherwise call generate-design with one complete, renderable index.html first. Do not ask another question unless a required decision is still genuinely missing."
           : "Now continue the design. Honor any answer about variations: use variants only if requested; otherwise generate one polished direction.",
       ]
         .filter(Boolean)