vibespot 1.0.8 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibespot",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "AI-powered HubSpot CMS landing page builder — vibe coding & React converter",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
+    "@anthropic-ai/sdk": "^0.91.1",
     "@clack/prompts": "^0.9.1",
     "@codemirror/lang-css": "^6.3.1",
     "@codemirror/lang-html": "^6.4.11",
@@ -29,12 +29,12 @@
     "busboy": "^1.6.0",
     "chalk": "^5.4.1",
     "codemirror": "^6.0.2",
-    "commander": "^13.1.0",
-    "execa": "^9.5.2",
+    "commander": "^14.0.3",
+    "execa": "^9.6.1",
     "mammoth": "^1.11.0",
-    "marked": "^17.0.4",
+    "marked": "^18.0.2",
     "pdf-parse": "^2.4.5",
-    "ws": "^8.19.0"
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/ui/chat.js

@@ -113,6 +113,11 @@ function handleWsMessage(msg) {
       if (historyBtn) {
         historyBtn.style.display = msg.gitAvailable ? "" : "none";
       }
+
+      // Hydrate plan-mode state (toggle + Plan pane content)
+      if (window.planController) {
+        window.planController.setInitialState(msg);
+      }
       break;
 
     case "stream":
@@ -188,6 +193,49 @@ function handleWsMessage(msg) {
     case "brand_extraction_error":
       appendSystemMessage("Brand extraction failed: " + (msg.message || "Unknown error"));
       break;
+
+    case "figma_import_started":
+      startStreaming();
+      appendSystemMessage("Importing from Figma: " + (msg.fileName || "design") + "...");
+      break;
+
+    case "needs_setup":
+      // Clear stale UI if shown
+      messagesEl.innerHTML = "";
+      document.getElementById("module-items").innerHTML = "";
+      document.getElementById("module-count").textContent = "0";
+      break;
+
+    case "plan_updated":
+      if (window.planController) window.planController.onPlanUpdated(msg.plan || "");
+      break;
+
+    case "plan_choices":
+      if (window.planController) window.planController.renderChoices(msg.question, msg.options);
+      break;
+
+    case "plan_complete":
+      // Replace the streaming bubble's content with the cleaned message
+      // (vibespot-plan + vibespot-choices fenced blocks stripped). We
+      // also overwrite streamBuffer so finishStreaming's final render
+      // doesn't re-introduce trailing <br> tags from the stripped block.
+      if (typeof msg.cleanedContent === "string") {
+        streamBuffer = msg.cleanedContent.trim();
+      }
+      if (streamingMsgEl) {
+        if (streamBuffer) {
+          streamingMsgEl.innerHTML = renderMarkdown(streamBuffer);
+        } else {
+          streamingMsgEl.innerHTML = '<em class="message__placeholder">Updated the plan in the Plan pane.</em>';
+        }
+      }
+      finishStreaming();
+      clearStreamStatus();
+      break;
+
+    case "plan_discarded":
+      if (window.planController) window.planController.onPlanDiscarded();
+      break;
   }
 }
 
@@ -542,17 +590,26 @@ const DOC_TYPES = new Set([
   "text/markdown", "text/plain",
 ]);
 const SUPPORTED_TYPES = new Set([...IMAGE_TYPES, ...DOC_TYPES]);
+// Browsers often report .md files as application/octet-stream or empty string
+const EXT_MIME_MAP = { ".md": "text/markdown", ".txt": "text/plain", ".markdown": "text/markdown" };
 
 function addPendingFile(file) {
-  if (!SUPPORTED_TYPES.has(file.type)) {
-    showToast(`Unsupported file type: ${file.name}`);
-    return;
+  let f = file;
+  if (!SUPPORTED_TYPES.has(f.type)) {
+    const ext = f.name.slice(f.name.lastIndexOf(".")).toLowerCase();
+    const mapped = EXT_MIME_MAP[ext];
+    if (mapped) {
+      f = new File([f], f.name, { type: mapped });
+    } else {
+      showToast(`Unsupported file type: ${f.name}`);
+      return;
+    }
   }
-  if (file.size > MAX_FILE_SIZE) {
-    showToast(`File too large (>10MB): ${file.name}`);
+  if (f.size > MAX_FILE_SIZE) {
+    showToast(`File too large (>10MB): ${f.name}`);
     return;
   }
-  pendingFiles.push(file);
+  pendingFiles.push(f);
   renderFileChips();
 }
 
@@ -955,6 +1012,9 @@ function renderMarkdown(text) {
   text = text.replace(/```[\s\S]*?```/g, "");
   // Also strip unclosed code fences (truncated responses)
   text = text.replace(/```[\s\S]*$/g, "");
+  // Collapse runs of blank lines left behind by stripped fences (otherwise
+  // they become trailing <br> tags and produce visible empty space).
+  text = text.replace(/\n{3,}/g, "\n\n").trim();
 
   // Escape HTML to prevent XSS from AI/user content
   text = escapeHtml(text);
@@ -1657,7 +1717,10 @@ document.getElementById("responsive-toggle").addEventListener("click", (e) => {
 
   const chrome = document.getElementById("browser-chrome");
   const width = btn.dataset.width;
-  chrome.style.maxWidth = width === "100%" ? "none" : width;
+  const isFullWidth = width === "100%";
+  chrome.style.maxWidth = isFullWidth ? "none" : width;
+  chrome.style.flex = isFullWidth ? "1" : "none";
+  chrome.style.width = isFullWidth ? "" : width;
 
   // Update browser URL bar with theme name
   const urlEl = document.getElementById("browser-url");

package/ui/docs/index.html

@@ -76,6 +76,17 @@
     <a class="doc-nav__link doc-nav__link--sub" href="#intent-types">Intents</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#prompt-tips">Prompt Tips</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#brand-assets">Brand Assets</a>
+    <a class="doc-nav__link" href="#plan-mode">Plan Mode</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#plan-mode-when">When to Use</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#plan-mode-flow">The Flow</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#plan-mode-pane">Plan Pane &amp; Editing</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#plan-mode-approval">Approval &amp; Discard</a>
+    <a class="doc-nav__link" href="#figma-import">Figma Import (Beta)</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#figma-token">Figma Token Setup</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#figma-extraction">What Gets Extracted</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#figma-image-modes">Image Modes</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#figma-pipeline">Translation Pipeline</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#figma-tips">Tips &amp; Limits</a>
     <a class="doc-nav__link" href="#editing">Editing &amp; Customization</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#field-editor">Field Editor</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#design-system">Design System</a>
@@ -557,18 +568,20 @@ vibespot</code></pre>
           <div class="mock-setup__action"><div class="mock-setup__action-icon">+</div><div class="mock-setup__action-label">New Theme</div><div class="mock-setup__action-desc">Start from scratch</div></div>
           <div class="mock-setup__action"><div class="mock-setup__action-icon">&#9654;</div><div class="mock-setup__action-label">Continue</div><div class="mock-setup__action-desc">Resume saved project</div></div>
           <div class="mock-setup__action"><div class="mock-setup__action-icon">&#8595;</div><div class="mock-setup__action-label">From HubSpot</div><div class="mock-setup__action-desc">Fetch existing theme</div></div>
-          <div class="mock-setup__action"><div class="mock-setup__action-icon">&#8635;</div><div class="mock-setup__action-label">Convert React</div><div class="mock-setup__action-desc">Import React project<br><span style="font-size:9px;color:var(--doc-yellow)">Experimental</span></div></div>
+          <div class="mock-setup__action"><div class="mock-setup__action-icon">&#9670;</div><div class="mock-setup__action-label">From Figma</div><div class="mock-setup__action-desc">Translate a design<br><span style="font-size:9px;color:var(--doc-yellow)">Beta</span></div></div>
+          <div class="mock-setup__action"><div class="mock-setup__action-icon">&#8635;</div><div class="mock-setup__action-label">From React</div><div class="mock-setup__action-desc">Import React project<br><span style="font-size:9px;color:var(--doc-yellow)">Beta</span></div></div>
         </div>
       </div>
     </div>
   </div>
 
-  <p>The setup screen presents four options:</p>
+  <p>The setup screen presents five options:</p>
   <ul>
     <li><strong>New Theme</strong> &mdash; Creates a fresh HubSpot theme directory at <code>~/vibespot-themes/your-theme-name</code>. Initializes the standard folder structure (<code>modules/</code>, <code>templates/</code>, <code>css/</code>, <code>js/</code>) and a git repository for version tracking.</li>
     <li><strong>Continue (Resume)</strong> &mdash; Reopens an existing project from the sidebar list. Your chat history, modules, and all templates are preserved exactly where you left off.</li>
     <li><strong>From HubSpot (Fetch)</strong> &mdash; Downloads an existing theme from your HubSpot portal. vibeSpot scans the fetched modules and imports them into a session so you can modify them with AI or by hand.</li>
-    <li><strong>Convert React (Experimental)</strong> &mdash; Clones a React or Lovable project from a Git URL and converts its components into native HubSpot modules. The conversion uses the built-in conversion guide to map React patterns to HubL equivalents.</li>
+    <li><strong>From Figma (Beta)</strong> &mdash; Paste a Figma URL and vibeSpot extracts design tokens, section structure, copy, and image assets, then translates each section into a HubSpot module. See the dedicated <a href="#figma-import">Figma Import</a> section for the full walkthrough.</li>
+    <li><strong>From React (Beta)</strong> &mdash; Clones a React or Lovable project from a Git URL and converts its components into native HubSpot modules. The conversion uses the built-in conversion guide to map React patterns to HubL equivalents.</li>
   </ul>
 
   <h3 id="first-page">Your First Page</h3>
@@ -714,6 +727,133 @@ vibespot</code></pre>
   </ul>
 </div>
 
+<!-- ============================================================
+     Section: Plan Mode
+     ============================================================ -->
+<div class="doc-section" id="plan-mode">
+  <h2 id="plan-mode-heading">Plan Mode <a href="#plan-mode" class="doc-anchor">#</a></h2>
+  <p class="doc-subtitle">A deliberation phase that runs <em>before</em> any code is generated. Plan mode turns vague briefs into well-scoped plans through guided dialogue, then runs the agentic pipeline against the approved plan as a high-fidelity design brief.</p>
+
+  <p>Without plan mode, vibeSpot generates immediately on every chat message &mdash; fast, but unforgiving on vague prompts. The AI guesses at audience, content, and structure, and you find out what it guessed only after a full generation cycle. Plan mode flips the order: the AI asks targeted questions first, surfaces what's missing, and only generates after you've reviewed and approved a written plan. The plan is markdown, persisted to <code>{theme}/.vibespot/plan.md</code>, and reviewable in a dedicated tab in the right pane.</p>
+
+  <h3 id="plan-mode-when">When to Use Plan Mode</h3>
+  <p>Plan mode is opt-in via a prominent <strong>Plan Mode</strong> pill above the chat input. The toggle persists across sessions in <code>~/.vibespot/config.json</code> as <code>planMode</code>.</p>
+  <p>Use plan mode when:</p>
+  <ul>
+    <li><strong>You're starting from a vague brief.</strong> "Build a landing page for our new SaaS product" benefits hugely from elicitation before code is written.</li>
+    <li><strong>Multiple stakeholders need to review.</strong> The plan is a markdown document that can be reviewed, edited, and shared before it becomes a generated theme.</li>
+    <li><strong>You're doing exploratory design work.</strong> Iterating on the plan is much cheaper than iterating on generated modules.</li>
+    <li><strong>You want explicit control.</strong> The plan documents every section, content choice, and CTA decision before the AI commits to code.</li>
+  </ul>
+  <p>Skip plan mode when:</p>
+  <ul>
+    <li>You're making small changes to an existing page (use the regular chat &mdash; the agentic pipeline handles modifications well).</li>
+    <li>You already have a detailed brief; type it directly and let the agentic pipeline run.</li>
+    <li>You're using a Figma design as the source of truth (use <a href="#figma-import">Figma Import</a> instead).</li>
+  </ul>
+
+  <h3 id="plan-mode-flow">The Flow</h3>
+  <p>Plan mode follows three implicit phases. The AI tracks which phase to be in based on conversation history.</p>
+  <ol class="doc-steps">
+    <li><strong>Understand.</strong> Your first message in plan mode triggers an "ask first" response. The AI poses two to four high-leverage gap-filling questions: who is this for, what's the primary CTA, what content sections do you envision, what's the brand tone. The plan in the right pane is mostly TBD markers and an "Open questions" list.</li>
+    <li><strong>Research &amp; Draft.</strong> Once you've answered the most important questions, the AI proposes a concrete plan: page goal, audience, primary CTA, a numbered module list with brief descriptions, brand and tone notes. It references existing modules and brand assets in the theme so you don't have to re-state them. It may ask one or two narrow follow-ups to fill remaining gaps.</li>
+    <li><strong>Refine.</strong> Subsequent messages tweak the plan. "Move the FAQ above the pricing." "Change the primary CTA to 'Book a demo'." The AI confirms what changed in chat and updates the plan in the pane. It only asks clarifying questions when your edit creates a new ambiguity.</li>
+  </ol>
+
+  <h3 id="plan-mode-pane">The Plan Pane &amp; Inline Editing</h3>
+  <p>The <strong>Plan</strong> tab in the right pane (between Preview and Code) is the source of truth for the current plan. While plan mode is on, this tab auto-selects when you send a message so the latest plan is always visible.</p>
+  <p>Two modes inside the pane:</p>
+  <ul>
+    <li><strong>Read mode</strong> (default) &mdash; the markdown plan is rendered with proper headings, lists, tables, and emphasis. A persistent footer holds <strong>Approve plan</strong> and <strong>Discard &amp; start over</strong> buttons.</li>
+    <li><strong>Edit mode</strong> (pencil icon) &mdash; the rendered view becomes a textarea containing the raw markdown. Edit any section directly: rename headers, swap copy, reorder modules. <strong>Save</strong> persists your edits to <code>plan.md</code> and the next AI turn picks them up as context. <strong>Cancel</strong> reverts.</li>
+  </ul>
+  <p>Inline editing is the fastest path for small fixes (typo, copy tweak, section rename). Use chat for substantive changes that need the AI to revisit assumptions.</p>
+
+  <h4>Choice chips</h4>
+  <p>When the AI asks a question with discrete answers (e.g. "What's the primary goal?"), it can emit clickable answer chips below its message: <code>[Lead capture] [Sign-ups] [Demo bookings] [Brand awareness]</code>. Clicking a chip sends that value as the next user message. You can always type a free-text answer instead &mdash; the chips are a shortcut, not a constraint.</p>
+
+  <h3 id="plan-mode-approval">Approval &amp; Discard</h3>
+  <p>vibeSpot enforces a <strong>hard write-gate</strong> while plan mode is active: the agentic pipeline is refused, even if the AI mistakenly tries to emit a module-generation block. Generation is reachable only via two explicit actions:</p>
+  <ul>
+    <li><strong>Approve plan</strong> &mdash; The plan markdown is prepended to a synthesized "Implement the approved plan." message and the agentic pipeline runs against it. The Plan tab automatically switches to Preview so you watch modules generate in place. Plan mode flips off after approval; turn it back on for the next plan.</li>
+    <li><strong>Discard &amp; start over</strong> &mdash; Clears <code>plan.md</code>, exits plan mode, returns the chat to normal generation. Used when you want to scrap the current direction entirely.</li>
+  </ul>
+  <p>The plan persists across vibeSpot restarts. Open the same theme weeks later, toggle plan mode on, and your in-progress plan is right where you left it.</p>
+
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">&#10024; Plan mode + brand assets</div>
+    <p>If your theme has a styleguide, brand voice, or product context loaded, the plan-mode AI uses them automatically. The plan will reference the right colors and tone without you re-stating them. After approval, the agentic pipeline gets the plan <em>and</em> the brand assets &mdash; double the alignment.</p>
+  </div>
+
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">&#128270; Web search during planning</div>
+    <p>Plan mode auto-engages Web Search when you've toggled it on in <a href="#settings-ai">Settings &rarr; AI &rarr; AI Capabilities</a>. The AI can look up competitor pages, industry references, or example landing pages while drafting your plan. Works on Anthropic API/OAuth and Claude Code engines.</p>
+  </div>
+</div>
+
+<!-- ============================================================
+     Section: Figma Import
+     ============================================================ -->
+<div class="doc-section" id="figma-import">
+  <h2 id="figma-import-heading">Figma Import (Beta) <a href="#figma-import" class="doc-anchor">#</a></h2>
+  <p class="doc-subtitle">Translate a Figma design into a HubSpot CMS theme without re-implementing it. The pipeline preserves the design's exact colors, typography, copy, and section order &mdash; the AI is used only to translate each section to HubL, not to make creative decisions.</p>
+
+  <p>Most AI tools that "import from Figma" treat the design as a vague reference and let the model regenerate everything. vibeSpot does the opposite: design tokens are extracted mechanically and mapped directly to CSS variables; section structure becomes module structure 1:1; per-section text is fed to the AI as field defaults. The AI's only job is to convert each section's layout into HubL syntax.</p>
+
+  <h3 id="figma-token">Figma Token Setup</h3>
+  <ol class="doc-steps">
+    <li>Open Figma and go to <strong>Account Settings &rarr; Personal access tokens &rarr; Generate new token</strong>. Give it a descriptive name like "vibeSpot import." Scopes needed: <strong>File content (read-only)</strong>.</li>
+    <li>Copy the token (it's shown only once).</li>
+    <li>In vibeSpot, open <strong>Settings &rarr; Figma</strong> and paste the token. Click <strong>Test</strong> to verify it works. The token is stored locally in <code>~/.vibespot/config.json</code> as <code>figmaToken</code> and is never sent anywhere except the Figma API.</li>
+  </ol>
+  <p>You can also test the connection per-import: the import dialog accepts a one-off token if you don't want to save one globally.</p>
+
+  <h3 id="figma-extraction">What Gets Extracted</h3>
+  <p>Click <strong>From Figma</strong> on the setup screen, paste a Figma file URL (or a specific frame URL, which scopes the import to that frame and its descendants), and click <strong>Extract</strong>. Progress streams via Server-Sent Events as the pipeline pulls data from Figma's REST API.</p>
+  <p>The extractor produces:</p>
+  <ul>
+    <li><strong>Design tokens</strong> &mdash; Colors with usage counts (most-used fill becomes <code>--theme-color-bg</code>, top non-bg fill becomes <code>--theme-color-primary</code>, etc.); typography styles grouped by role (heading vs body, with exact px sizes); spacing values (sorted unique scale: xs, sm, md, lg, xl, section); effects (box shadows and border radii ready as <code>cssValue</code>).</li>
+    <li><strong>Section structure</strong> &mdash; Top-level frames in the file or selected frame become modules, in their original Figma order. Each section keeps its name (kebab-cased to a module name), dimensions, layout direction (horizontal/vertical/grid), item spacing, and padding.</li>
+    <li><strong>Per-section content</strong> &mdash; Every text node is captured with its role (headline, subhead, body, CTA, eyebrow, etc.), font size, font weight, and verbatim text. This becomes the field defaults in the generated module.</li>
+    <li><strong>Children structure</strong> &mdash; A summary of each section's children (e.g., "3 cards each containing: image, headline, body, button") so the AI knows the layout shape without trying to over-engineer it.</li>
+    <li><strong>Image assets</strong> &mdash; Every embedded image is downloaded from Figma's image-export API at 2&times; resolution as PNG. Filenames are sanitized; the full set is shown to you for confirmation before generation.</li>
+  </ul>
+  <p>After extraction, you see a summary screen: section count, color count, font families, and asset count. Name the theme (this becomes the kebab-case directory name and CSS-variable prefix), choose your image mode, and click <strong>Generate Page</strong>.</p>
+
+  <h3 id="figma-image-modes">Image Modes</h3>
+  <p>A toggle on the import screen controls how images are handled in the generated modules. Both modes copy the extracted PNGs to the theme's <code>assets/</code> directory.</p>
+  <ul>
+    <li><strong>Import images as assets</strong> <em>(default)</em> &mdash; Modules reference images via <code>get_asset_url(&quot;{theme}/assets/{filename}&quot;)</code>. The page renders pixel-identically to Figma out of the box. Best when the Figma assets are the final assets you want on the live page.</li>
+    <li><strong>Image fields with placeholders</strong> &mdash; Modules expose HubSpot image fields with <code>placehold.co</code> URLs as defaults. The Figma assets are still in <code>assets/</code>, but the modules don't reference them; instead, content editors swap in their own images via HubSpot's editor. Best when Figma images are mockups (stock photography, lorem ipsum imagery) and the real images will be different.</li>
+  </ul>
+
+  <h3 id="figma-pipeline">The Translation Pipeline</h3>
+  <p>Figma import runs a streamlined pipeline (separate from the agentic pipeline used by chat-driven generation) optimized for fidelity:</p>
+  <ol class="doc-steps">
+    <li><strong>Generate shared CSS</strong> &mdash; Deterministic mapping of design tokens to <code>:root</code> CSS variables and utility classes (<code>{theme}-container</code>, <code>{theme}-section</code>, <code>{theme}-grid</code>, <code>{theme}-btn</code>, etc.). Lightness analysis on the dominant color auto-selects light vs dark mode defaults. Standard responsive breakpoints (mobile and tablet) are emitted automatically. <strong>No AI involved</strong> &mdash; the design tokens are the spec.</li>
+    <li><strong>Map sections to module specs</strong> &mdash; Each Figma section becomes one module spec: name (kebab-cased), description (inferred from name + content), content brief (text grouped by role with exact strings), and layout notes (layout mode, gap, padding, background color, children summary).</li>
+    <li><strong>Translate each module</strong> &mdash; For each spec, the AI is invoked once with a system prompt that explicitly forbids invention: "TRANSLATE this design to HubL. Use these exact texts as field defaults. Match colors, spacing, and layout from the design tokens." Modules are generated in parallel (concurrency limited via the same <code>agenticConcurrency</code> setting; default 20). Structured output via the Module Developer JSON schema ensures reliable parsing.</li>
+    <li><strong>Validate &amp; auto-fix</strong> &mdash; The same quality-check stage as the agentic pipeline: balances HubL tags, normalizes reserved field names (<code>name</code> &rarr; <code>item_name</code>), upgrades deprecated field types, strips CDN imports.</li>
+  </ol>
+  <p>Progress streams to the chat panel as standard pipeline events: a "Mapped N modules" decision, then per-module "Generating&hellip;" / "Module complete" entries. After the run, the live preview shows the page with the Figma colors, copy, and section order intact.</p>
+
+  <h3 id="figma-tips">Tips &amp; Limits</h3>
+  <ul>
+    <li><strong>Use top-level frames as sections.</strong> The importer treats top-level frames in your Figma file (or in the selected frame) as the section boundary. If your design has everything in one giant frame, only that one frame becomes a module. Break your design into logical sections (Hero, Features, Pricing, Footer, etc.) as separate top-level frames for best results.</li>
+    <li><strong>Name your frames meaningfully.</strong> Frame names become module names. A frame called <code>Section 1</code> turns into a module called <code>section-1</code>; rename it to <code>Hero</code> so you get <code>hero</code>.</li>
+    <li><strong>Auto-layout produces better results.</strong> Frames with auto-layout export their layout direction, gap, and padding cleanly. Free-form positioning is supported but the AI has to infer layout from coordinates, which is less reliable.</li>
+    <li><strong>Figma rate limits apply.</strong> The image-export endpoint has limits; very asset-heavy files (50+ images) may take a minute or two to extract. Errors with status <code>429</code> indicate rate-limiting &mdash; wait and retry.</li>
+    <li><strong>Permissions matter.</strong> The token must have access to the file. <code>403</code> errors mean the file isn't shared with the token's owner or doesn't have view permission.</li>
+    <li><strong>Effects support is limited.</strong> Box shadows and border radii are extracted; gradients, blur effects, blend modes, and complex masks are ignored (HubL preview wouldn't render them faithfully anyway).</li>
+    <li><strong>Re-importing replaces modules.</strong> Importing a Figma URL into an existing theme clears the active template's modules first &mdash; the import is treated as a full page replacement, not an additive merge.</li>
+  </ul>
+
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">&#10024; Workflow tip</div>
+    <p>For the highest-fidelity output: use auto-layout in Figma, name your frames as kebab-friendly section names ("Hero", "Trust Bar", "Final CTA"), and extract real copy + final imagery into the design before importing. The result is a HubSpot theme that's ready to deploy with no manual cleanup &mdash; content editors get a fully-fielded theme they just need to plug content into.</p>
+  </div>
+</div>
+
 <!-- ============================================================
      Section 6: Editing & Customization
      ============================================================ -->
@@ -973,11 +1113,24 @@ vibespot</code></pre>
     <li><strong>Engine selector</strong> &mdash; Seven buttons, one for each supported engine. The active engine is highlighted in orange. Unavailable engines are grayed out &mdash; API engines require a key, CLI engines must first be toggled on in the CLI Tools section below.</li>
     <li><strong>Model dropdown</strong> &mdash; A dynamic model catalog populated from the selected engine's available models. You can also type a custom model identifier for newly released models.</li>
     <li><strong>Agentic pipeline toggle</strong> &mdash; An iOS-style toggle switch that enables or disables the 4-stage pipeline. When off, vibeSpot falls back to single-call mode. A sub-label shows the current status (Active, Disabled, or Not configured). On first use, vibeSpot prompts you to choose.</li>
+    <li><strong>AI Capabilities section</strong> &mdash; Surfaces SDK feature toggles per active engine:
+      <ul>
+        <li><em>Prompt Caching</em> &mdash; auto-active on Anthropic API, "Auto (CLI-managed)" on Claude Code, "Anthropic only" elsewhere. No knob; informational.</li>
+        <li><em>Extended Thinking</em> &mdash; toggle on Anthropic API/OAuth with a Low / Medium / High budget select (~4k / 16k / 32k thinking tokens). Page Architect's two substages opt in when enabled. On Claude Code the badge reads "Auto (CLI-managed)" because the CLI handles thinking internally and doesn't expose a budget knob.</li>
+        <li><em>Web Search</em> &mdash; real toggle. On Anthropic API/OAuth it appends the <code>web_search_20250305</code> server-side tool to non-structured-output calls (chat, plan-mode deliberation). On Claude Code it passes <code>--allowedTools=WebSearch</code> so the agent's tool allowlist permits it. Plan mode opts in automatically &mdash; research is highest-value during deliberation.</li>
+        <li><em>Citations</em> &mdash; "Coming soon".</li>
+      </ul>
+    </li>
     <li><strong>API keys section</strong> &mdash; Input fields for Anthropic, OpenAI, and Google AI API keys. Keys are displayed masked (only last 4 characters visible) after saving.</li>
     <li><strong>Claude OAuth</strong> &mdash; A section to paste the OAuth token generated by <code>claude setup-token</code>. Shows the token status (valid/expired).</li>
     <li><strong>CLI tools</strong> &mdash; Toggle switches for Claude Code, Gemini CLI, and Codex CLI. CLI tools must be toggled <strong>on</strong> before they appear as selectable engines in the Engine section above. This lazy-detection approach means disabled tools add zero startup overhead. Once toggled on, vibeSpot checks if the CLI is installed and authenticated. If not installed, an install button appears. If installed but not authenticated, an auth button appears.</li>
   </ul>
 
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">Claude Code uses <code>stream-json</code></div>
+    <p>vibeSpot invokes Claude Code with <code>--output-format stream-json --include-partial-messages --verbose</code>, parsing the line-delimited JSON event stream rather than raw text. This preserves the live token-typing UX <em>and</em> lets vibeSpot show concrete agent activity in the status pane &mdash; "Reading hero/module.html", "Searching: 'pricing best practices'", "Editing styleguide.md" &mdash; instead of generic "thinking&hellip;" placeholders. Tool calls (<code>Read</code>, <code>Edit</code>, <code>Bash</code>, <code>WebSearch</code>, <code>WebFetch</code>, <code>Grep</code>, <code>Glob</code>) are extracted from the event stream and rendered as live status lines.</p>
+  </div>
+
   <h3 id="settings-hubspot">HubSpot Tab</h3>
   <ul>
     <li><strong>Upload mode toggle</strong> &mdash; Switch between API (recommended) and CLI (legacy) upload modes.</li>
@@ -987,7 +1140,7 @@ vibespot</code></pre>
   </ul>
 
   <h3 id="settings-github">GitHub Tab</h3>
-  <p>The GitHub tab configures authentication for source imports (used by the "Convert React" flow).</p>
+  <p>The GitHub tab configures authentication for source imports (used by the "From React" flow).</p>
   <ul>
     <li><strong>GitHub CLI authentication</strong> &mdash; Uses <code>gh auth</code> to authenticate with GitHub. Required for cloning private repositories during React-to-HubSpot conversion.</li>
   </ul>

package/ui/index.html

@@ -96,10 +96,15 @@
               <span class="setup__action-icon">&#8595;</span>
               <span>From HubSpot</span>
             </button>
+            <button class="setup__action-btn" data-action="figma">
+              <span class="setup__action-icon">&#9670;</span>
+              <span>From Figma</span>
+              <span class="setup__action-badge">Beta</span>
+            </button>
             <button class="setup__action-btn" data-action="convert">
               <span class="setup__action-icon">&#8634;</span>
-              <span>Convert React</span>
-              <span class="setup__action-badge">Experimental</span>
+              <span>From React</span>
+              <span class="setup__action-badge">Beta</span>
             </button>
           </div>
 
@@ -132,6 +137,36 @@
             </div>
           </div>
 
+          <div class="setup__panel hidden" id="panel-figma">
+            <div id="figma-token-prompt" class="hidden">
+              <p class="setup__hint">A Figma Personal Access Token is required. <a href="#" id="figma-open-settings">Add one in Settings</a> or enter it below:</p>
+              <div class="setup__row">
+                <input type="password" class="setup__input setup__input--wide" id="figma-inline-token" placeholder="figd_..." />
+                <button class="btn btn--primary" id="figma-save-token">Save</button>
+              </div>
+            </div>
+            <div id="figma-url-section">
+              <div class="setup__row">
+                <input type="text" class="setup__input setup__input--wide" id="figma-url" placeholder="https://www.figma.com/design/..." />
+                <button class="btn btn--primary" id="figma-extract-btn">Extract</button>
+              </div>
+              <p class="setup__hint">Paste a Figma design URL to extract structure, text, and assets</p>
+              <div class="figma-progress hidden" id="figma-progress"></div>
+            </div>
+            <div id="figma-summary" class="hidden"></div>
+            <div id="figma-generate" class="hidden">
+              <div class="setup__row">
+                <input type="text" class="setup__input setup__input--wide" id="figma-theme-name" placeholder="my-landing-page" />
+                <button class="btn btn--primary" id="figma-generate-btn">Generate Page</button>
+              </div>
+              <label class="figma-toggle" id="figma-image-toggle">
+                <input type="checkbox" id="figma-use-assets" checked />
+                <span class="figma-toggle__label">Import images as assets</span>
+                <span class="figma-toggle__hint" id="figma-image-hint">Images uploaded to HubSpot, no manual replacement needed</span>
+              </label>
+            </div>
+          </div>
+
           <div class="setup__panel hidden" id="panel-convert">
             <div class="setup__row">
               <input type="text" class="setup__input setup__input--wide" id="import-url" placeholder="https://github.com/user/repo or Lovable URL" />
@@ -423,6 +458,15 @@
             </div>
           </div>
           <div class="chat__input-area">
+            <div class="chat__mode-bar">
+              <button class="plan-toggle" id="plan-mode-toggle" title="Plan mode — deliberate before generating" aria-pressed="false">
+                <span class="plan-toggle__indicator">
+                  <svg class="plan-toggle__icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="9" y1="13" x2="15" y2="13"/><line x1="9" y1="17" x2="15" y2="17"/></svg>
+                </span>
+                <span class="plan-toggle__label">Plan mode</span>
+                <span class="plan-toggle__state">Off</span>
+              </button>
+            </div>
             <div class="chat__file-chips" id="file-chips"></div>
             <div class="chat__input-wrapper">
               <textarea class="chat__input" id="chat-input" placeholder="Describe your landing page..." rows="1"></textarea>
@@ -430,7 +474,7 @@
                 <button class="chat__input-icon" id="btn-attach-file" title="Attach files (images, PDFs, docs)">
                   <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M21.44 11.05l-9.19 9.19a6 6 0 01-8.49-8.49l9.19-9.19a4 4 0 015.66 5.66l-9.2 9.19a2 2 0 01-2.83-2.83l8.49-8.48"/></svg>
                 </button>
-                <input type="file" id="file-input" multiple accept="image/png,image/jpeg,image/svg+xml,image/webp,image/gif,application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,text/markdown,text/plain" style="display:none">
+                <input type="file" id="file-input" multiple accept="image/png,image/jpeg,image/svg+xml,image/webp,image/gif,application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,text/markdown,text/plain,.md,.markdown,.txt" style="display:none">
                 <button class="chat__input-icon" id="btn-starter-templates" title="Templates">
                   <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18"/><path d="M9 21V9"/></svg>
                 </button>
@@ -454,6 +498,7 @@
       <main class="panel panel--right" id="panel-right">
         <div class="view-toggle" id="view-toggle">
           <button class="view-toggle__btn active" data-view="preview">Preview</button>
+          <button class="view-toggle__btn" data-view="plan" id="view-toggle-plan">Plan</button>
           <button class="view-toggle__btn" data-view="code">Code</button>
         </div>
 
@@ -471,6 +516,35 @@
           </div>
         </div>
 
+        <!-- Plan pane (deliberation phase) -->
+        <div class="plan-pane hidden" id="plan-pane">
+          <div class="plan-pane__scroll">
+            <div class="plan-pane__header">
+              <h2 class="plan-pane__title">Plan</h2>
+              <div class="plan-pane__header-actions">
+                <button class="plan-pane__icon-btn" id="plan-edit-toggle" title="Edit plan">
+                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M11 4H4a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 013 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+                  <span>Edit</span>
+                </button>
+              </div>
+            </div>
+            <div class="plan-pane__content" id="plan-content">
+              <div class="plan-pane__empty">
+                <p>No plan yet.</p>
+                <p class="plan-pane__empty-hint">Toggle plan mode in the chat (icon next to send) and describe what you want to build. The assistant will ask clarifying questions and draft a plan here.</p>
+              </div>
+            </div>
+            <textarea class="plan-pane__editor hidden" id="plan-editor" spellcheck="false"></textarea>
+          </div>
+          <div class="plan-pane__footer">
+            <button class="btn btn--secondary plan-pane__discard" id="plan-discard-btn">Discard &amp; start over</button>
+            <div class="plan-pane__footer-spacer"></div>
+            <button class="btn btn--secondary hidden" id="plan-edit-cancel">Cancel</button>
+            <button class="btn btn--primary hidden" id="plan-edit-save">Save</button>
+            <button class="btn btn--primary plan-pane__approve" id="plan-approve-btn">Approve plan</button>
+          </div>
+        </div>
+
         <div class="code-view hidden" id="code-view">
           <div class="code-view__sidebar">
             <div class="code-view__sidebar-header">Files</div>
@@ -529,6 +603,7 @@
       <div class="settings__tabs" id="settings-tabs">
         <button class="settings__tab active" data-tab="ai">AI</button>
         <button class="settings__tab" data-tab="hubspot">HubSpot</button>
+        <button class="settings__tab" data-tab="figma">Figma</button>
         <button class="settings__tab" data-tab="github">GitHub</button>
         <button class="settings__tab" data-tab="vibespot">vibeSpot</button>
       </div>
@@ -552,6 +627,7 @@
   <script src="/settings.js"></script>
   <script src="/upload-panel.js"></script>
   <script src="/chat.js"></script>
+  <script src="/plan.js"></script>
   <script src="/preview.js"></script>
   <script src="/field-editor.js"></script>
   <script src="/code-editor.js"></script>