vibespot 1.0.9 → 1.1.0

package/README.md

@@ -25,18 +25,20 @@ npx vibespot
 
 Opens a browser with:
 - **Chat on the left** — describe your landing page in natural language
-- **Live preview on the right** — see your page render in real-time
+- **Live preview on the right** — see your page render in real-time, plus a **Plan tab** and a **Code tab**
 - **Agentic pipeline** — multi-stage AI generation with real-time progress
+- **Plan mode** *(new in v1.1)* — toggle on to deliberate before generating: the AI asks elicitation questions, builds a markdown plan in a dedicated pane, and only generates after you approve
 - **Project sidebar** — create, open, resume, or delete projects
 - **Module management** — reorder via drag-and-drop, edit fields, delete modules from module list or module library
 - **Starter templates** — SaaS, Portfolio, Restaurant, Event
-- **GitHub import** — convert existing React projects
+- **From Figma** *(Beta)* — paste a Figma URL to extract design tokens, text, and assets, then generate a full page that translates the design verbatim
+- **From React** *(Beta)* — convert existing React/Lovable projects from a Git URL
 - **Field editor** — tweak text, colors, images directly
 - **File uploads** — attach images and documents via drag-and-drop or paperclip button
 - **Upload to HubSpot** — per-file progress, auto-fix, celebration popup with direct portal link
 - **Version history** — per-template git commits with rollback
 - **Light/dark mode** — toggle or auto-detect system preference
-- **Tabbed settings** — AI engines, HubSpot accounts, GitHub, vibeSpot config
+- **Tabbed settings** — AI engines (with extended-thinking toggle), HubSpot accounts, Figma, GitHub, vibeSpot config
 - **ZIP download** — export your theme as a ZIP file
 
 ### Agentic Pipeline
@@ -50,6 +52,50 @@ When you send a message, vibeSpot runs a 4-stage pipeline:
 
 Completed modules appear in the live preview immediately as each finishes, with themed skeleton placeholders for modules still generating.
 
+### Plan Mode
+
+Plan mode is a deliberation phase that runs *before* any code is generated. Toggle it from the prominent **Plan Mode** pill above the chat input. While active:
+
+- The AI asks elicitation questions to surface gaps in your brief: who's the audience, what's the primary CTA, what sections should the page have, what's the brand voice.
+- Each response builds up a markdown plan, persisted to `{theme}/.vibespot/plan.md` and rendered in a dedicated **Plan** tab in the right pane.
+- The AI may emit clickable answer chips for common questions (e.g. "What's your primary goal? [Lead capture] [Sign-ups] [Demo bookings]") to keep the conversation fast.
+- You can **edit the plan inline** (pencil icon → textarea → Save) — refinements without typing chat messages.
+- Generation is **hard-gated**: the agentic pipeline is refused while plan mode is on. The only way to generate is the explicit **Approve plan** button, which prepends the plan to the user message as a design brief and runs the pipeline against the approved spec.
+- **Discard & start over** clears the plan and exits plan mode.
+
+Plan mode is ideal when:
+- You're starting from a vague brief and want the AI to help you scope the page.
+- Multiple stakeholders need to review the plan before code is generated.
+- You're generating a high-stakes page and want to control content/structure decisions explicitly.
+
+When plan mode is off, vibeSpot generates immediately — the existing fast path. Mode state persists across sessions.
+
+### Figma Import (Beta)
+
+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 — the AI is only used to translate each section to HubL, not to make creative decisions.
+
+**Setup:**
+1. Open **Settings → Figma** and paste a Figma Personal Access Token (generate one in your Figma account settings).
+2. Click **From Figma** on the setup screen and paste a Figma file URL or a specific frame URL.
+
+**What the importer extracts:**
+- **Design tokens** — colors (with usage counts), typography styles (family, size, weight per role), spacing scale, effects (shadows, border radii). These map mechanically to `:root` CSS variables — no AI guessing.
+- **Section structure** — top-level frames become modules, in their original Figma order.
+- **Per-section content** — exact headlines, body copy, and CTAs are extracted with role and font-size annotations, fed to the AI as field defaults.
+- **Image assets** — downloaded from Figma's image API as PNGs (2× resolution).
+
+**Two image modes (toggle on the import screen):**
+- **Import images as assets** *(default)* — images land in `{theme}/assets/` and are referenced via `get_asset_url()`. The page looks identical to Figma out of the box.
+- **Image fields with placeholders** — modules use HubSpot image fields with placehold.co defaults. Content editors swap in their own images via the HubSpot editor.
+
+**The conversion pipeline (streamlined):**
+1. **Generate shared CSS** — deterministic mapping of design tokens to CSS variables and utility classes. No AI.
+2. **Map sections to module specs** — each section's exact text and layout becomes a module specification.
+3. **AI translation** — for each module, the AI converts the Figma section into HubL. Parallel, concurrency-limited. The system prompt forbids inventing content; everything comes from Figma.
+4. **Quality check** — the same auto-fix layer used by the agentic pipeline.
+
+The result is a HubSpot theme where every color, word, and pixel of spacing matches the original design — fully editable in HubSpot's drag-and-drop editor.
+
 ### Classic Wizard Mode
 
 ```bash
@@ -122,17 +168,28 @@ Most users only need `npx vibespot` — the web UI handles everything.
 
 ## Configuration
 
-Settings are managed in the **Settings** panel (tabbed: AI, HubSpot, GitHub, vibeSpot) and saved in `~/.vibespot/config.json`:
+Settings are managed in the **Settings** panel (tabbed: AI, HubSpot, Figma, GitHub, vibeSpot) and saved in `~/.vibespot/config.json`:
 
 - `aiEngine` — Your preferred AI engine (`anthropic-api`, `claude-oauth`, `openai-api`, `gemini-api`, `claude-code`, `gemini-cli`, `codex-cli`)
 - `anthropicApiKey`, `openaiApiKey`, `geminiApiKey` — API keys (stored locally, never sent except to the provider)
 - `hubspotAccounts` — Connected HubSpot accounts (PAK-based auth)
 - `hubspotUploadMode` — `api` (default, direct API) or `cli` (legacy, requires HubSpot CLI)
 - `agenticConcurrency` — Max parallel module generation calls (default: 20)
+- `figmaToken` — Figma Personal Access Token for design import
 - `enabledCLITools` — Which CLI tools to detect on settings load
 
-## What's New (v1.0)
+## What's New
+
+### v1.1.0
+- **Plan mode** — deliberation phase before generation. Prominent toggle above chat input; AI asks elicitation questions, builds a markdown plan in a dedicated tab, only generates after Approve. Plan persists to `.vibespot/plan.md` across sessions.
+- **Streamlined Figma import** — replaces the old agentic-pipeline path with a translation pipeline that preserves Figma's exact design tokens, copy, and section order. Image assets copy into the theme automatically.
+- **Anthropic SDK upgrade** (0.39 → 0.91) — unlocks extended thinking, improved prompt caching, and tool/schema-level cache control.
+- **AI Capabilities settings panel** — toggle Extended Thinking (Anthropic API engines, with Low/Medium/High budget) and Web Search (Anthropic API + Claude Code CLI). Prompt Caching shows as auto-active; Citations is the remaining "coming soon" item. Claude Code engines see honest "Auto (CLI-managed)" badges where the CLI handles the feature internally.
+- **Cache control on tool definitions** — Module Developer's identical tool schema is now cached, saving schema-encoding tokens on every parallel call after the first.
+- **Claude Code stream-json output** — both single-call mode and the agentic CLI path now use `--output-format stream-json --include-partial-messages --verbose`. Tool calls (`Read`, `Edit`, `Bash`, `WebSearch`, `WebFetch`, `Grep`, `Glob`) flow into the pipeline status pane as concrete activity ("Searching: '…'", "Reading hero/module.html") instead of generic rotating placeholders.
 
+### v1.0.x
+- **Figma design import** (v1.0.10) — paste a Figma URL to extract design tokens, text, section structure, and image assets, then generate a full HubSpot page via the agentic pipeline
 - **Template & module deletion** (v1.0.4) — delete templates from disk, option to delete exclusive modules, delete module button in module library preview
 - **Brand assets redesign** (v1.0.2) — hover-expand cards with per-asset Upload/Extract, Extract All, brand voice extractor, cross-template product context sharing via rendered preview HTML
 - **Agentic pipeline** (v1.0.0) — 4-stage AI generation: Intent Analyzer → Page Architect (Design System + Module Planner) → Module Developer (parallel) → Quality Check (auto-fix)