vibespot 1.6.4 → 1.7.7

package/ui/docs/index.html

@@ -86,6 +86,10 @@
     <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="#checkpoints">Checkpoints</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#checkpoints-seams">The Three Seams</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#checkpoints-card">The Checkpoint Card</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#checkpoints-oneshot">One-Shot Escape Hatch</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>
@@ -954,12 +958,49 @@ testimonial carousel, and a minimal footer with social links.</code></pre>
   </ul>
 </div>
 
+<!-- ============================================================
+     Section: Checkpoints
+     ============================================================ -->
+<div class="doc-section" id="checkpoints">
+  <h2 id="checkpoints-heading">Checkpoints <a href="#checkpoints" class="doc-anchor">#</a></h2>
+  <p class="doc-subtitle">The default generation flow. Instead of running all four pipeline stages in one blocking shot, vibeSpot pauses at cheap seams and shows you a review card <em>before</em> spending tokens on the expensive parallel module build &mdash; so you steer the look and the skeleton while changes are still free.</p>
+
+  <p>The <a href="#agentic-pipeline">agentic pipeline</a> has a natural cost cliff: the design system (Stage 2a) and the module plan (Stage 2b) are a handful of cheap calls, but the module build (Stage 3) fans out one generation per module in parallel &mdash; the bulk of the spend and the wait. Checkpoints park the pipeline at the seams before that cliff. You see what the AI decided, adjust it, and only then pay for the build. Each gate is rendered from data the pipeline already produced, so showing the card costs nothing extra.</p>
+
+  <img class="doc-screenshot" style="max-width:360px" src="screenshots/checkpoint-card.png" alt="Design checkpoint card in the chat panel: a DESIGN CHECKPOINT badge, a rendered hero preview, the palette swatches and heading/body type specimen, the estimated build cost, and Approve / Steer / Skip / Cancel buttons">
+
+  <h3 id="checkpoints-seams">The Three Seams</h3>
+  <p>For a from-scratch page, checkpoints fire in order: <strong>brand intake &rarr; design &rarr; structure &rarr; build</strong>. Modifications to an existing page, email generation, and plan-approved runs build straight through without gating.</p>
+  <ol class="doc-steps">
+    <li><strong>Brand intake.</strong> When you ask for a new page and the theme has no style system yet, vibeSpot asks first instead of guessing: <strong>bring your brand</strong> (paste colors, drop in CSS/code, point at an existing theme or a live URL, describe your voice) or <strong>let it choose</strong>. What you provide seeds the <code>:root</code> design tokens that feed the design checkpoint. Skipped when the theme already has a style system.</li>
+    <li><strong>Design checkpoint.</strong> After the design-system stage, the pipeline parks and shows a <strong>design card</strong>: palette swatches, a heading/body type specimen, and one representative hero rendered straight from the design tokens. No extra model call &mdash; it's a deterministic preview of the tokens the build will use.</li>
+    <li><strong>Structure checkpoint.</strong> After the module planner, the pipeline parks again and shows the planned modules as an <strong>editable outline</strong>. Reorder rows (&#9650;/&#9660;), cut them (&#10005;), rename inline, or add a section &mdash; all client-side, no model call. The build honors exactly the outline you keep: a reorder or rename preserves that module's planned brief; an added row gets a sensible default brief.</li>
+  </ol>
+
+  <h3 id="checkpoints-card">The Checkpoint Card</h3>
+  <p>Every checkpoint card offers the same four actions, plus a cost estimate:</p>
+  <ul>
+    <li><strong>Approve</strong> &mdash; accept what's shown and continue to the next seam (or the build, at the last gate).</li>
+    <li><strong>Steer</strong> &mdash; type a note and vibeSpot re-runs <em>only</em> that stage with your guidance, then re-previews. Cheap to iterate, because you're redoing one stage, not the whole page.</li>
+    <li><strong>Skip</strong> &mdash; build now and suppress any remaining gates for this run. Skipping at the design gate suppresses the structure gate too.</li>
+    <li><strong>Cancel</strong> &mdash; drop the run. Nothing is written.</li>
+  </ul>
+  <p>Each card also shows the <strong>estimated cost of the build it gates</strong>, computed from spend-so-far via the per-page <a href="#observability">cost tracker</a> &mdash; so you know what Approve will cost before you click it. (CLI engines report no usage, so the estimate is omitted for them.)</p>
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">&#128268; Crash-safe by design</div>
+    <p>A parked checkpoint isn't a paused, open promise &mdash; the pipeline <em>returns</em> at the gate and your resolution re-enters it via a resume token. If the server restarts while a gate is open, the run is simply dropped and you re-send your prompt, rather than leaving a hung generation behind.</p>
+  </div>
+
+  <h3 id="checkpoints-oneshot">One-Shot Escape Hatch</h3>
+  <p>Checkpoints are <strong>on by default</strong> for from-scratch page generation. When you already know what you want and don't need to review, the <strong>one-shot</strong> button next to send runs the whole pipeline in one go &mdash; the previous one-call behaviour, no gates. It's a per-message choice: tap one-shot for this prompt, or hit send to go through the checkpoints.</p>
+</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 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. It is the heaviest variant of the <a href="#checkpoints">checkpoint</a> flow &mdash; a full written plan you approve, rather than a single review card.</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>
 
@@ -1010,6 +1051,11 @@ testimonial carousel, and a minimal footer with social links.</code></pre>
   </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--info">
+    <div class="doc-callout__label">&#128279; One primitive under the hood</div>
+    <p>Plan approval now runs on the same park-and-re-enter machinery as the design and structure <a href="#checkpoints">checkpoints</a>. <strong>Approve plan</strong> and <strong>Discard &amp; start over</strong> resolve through the shared <code>checkpoint_resolve</code> path (approve &rarr; build, cancel &rarr; discard), so plan mode, the design gate, and the structure gate are three faces of one gating model rather than separate code paths. A plan-approved run builds straight through &mdash; it doesn't re-gate at the design or structure seams, because the plan already covered that deliberation.</p>
+  </div>
+
   <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>
@@ -1208,7 +1254,7 @@ testimonial carousel, and a minimal footer with social links.</code></pre>
     <li><strong>Span</strong> &mdash; one pipeline stage: intent analysis, design system, module planning, and module development.</li>
     <li><strong>Generation</strong> &mdash; one model call. The N parallel module calls (plus any retries) nest under the single module-development span.</li>
   </ul>
-  <p>A full page reads as <code>trace &rarr; stage spans &rarr; generations</code>, with token cost summing up the tree.</p>
+  <p>A full page reads as <code>trace &rarr; stage spans &rarr; generations &rarr; output</code>, with token cost summing up the tree. The trace carries a compact <em>output</em> summary (the modules it produced), so the Traces list shows a result preview at a glance, and each generation links to the managed <em>prompt</em> version that produced it &mdash; so you can break cost, latency, and quality down per prompt version in Langfuse.</p>
 
   <h4 id="langfuse-instance">Get a Langfuse instance</h4>
   <p>You need somewhere to send the traces. Pick one: Langfuse's hosted cloud (fastest to start) or your own self-hosted install (your data stays on your infrastructure). Either way you end up with a <strong>public key</strong>, a <strong>secret key</strong>, and a <strong>host URL</strong> &mdash; the three things vibeSpot needs in the next step.</p>
@@ -1500,7 +1546,7 @@ docker cp vibespot:/home/vibespot/vibespot-themes ./backup-themes</code></pre>
   </ul>
   <div class="doc-callout doc-callout--tip">
     <div class="doc-callout__label">&#9888;&#65039; Single instance &amp; auth</div>
-    <p>vibeSpot keeps active sessions in memory &mdash; run a single instance (no horizontal scaling without sticky sessions). It runs as a non-root user and has <strong>no built-in authentication</strong>. For internet-facing deployments, put an authenticating proxy (OAuth2 Proxy, Authelia, Cloudflare Access) in front. Persistence is filesystem-only on the named volumes &mdash; there is no database to run.</p>
+    <p>vibeSpot keeps active sessions in memory &mdash; run a single instance (no horizontal scaling without sticky sessions). It runs as a non-root user and has <strong>no built-in authentication</strong>. For internet-facing deployments, enable the bundled <strong>Azure Entra SSO gate</strong> (the <code>docker-compose.auth.yml</code> overlay) or put your own authenticating proxy (Authelia, Cloudflare Access) in front. Persistence is filesystem-only on the named volumes &mdash; there is no database to run.</p>
   </div>
 </div>
 

package/ui/index.html

@@ -542,7 +542,10 @@
                         <button class="chat__input-icon" id="btn-starter-templates" type="button" title="Templates" aria-label="Templates">
                           <svg class="icon icon--sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18"/><path d="M9 21V9"/></svg>
                         </button>
-                        <button class="chat__send" id="chat-send" type="button" title="Send (Enter)" aria-label="Send message">
+                        <button class="chat__send chat__send--oneshot" id="chat-send-oneshot" type="button" title="One-shot — skip the design checkpoint and build the whole page in one go" aria-label="One-shot (skip checkpoints)">
+                          <svg class="icon icon--sm" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M13 2L4.5 12.5h6L9 22l8.5-10.5h-6L13 2z"/></svg>
+                        </button>
+                        <button class="chat__send" id="chat-send" type="button" title="Send (Enter) — pauses at the design checkpoint" aria-label="Send message">
                           <svg class="icon icon--md" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M3 12L21 4L13 22L11 14L3 12Z"/></svg>
                         </button>
                       </div>

package/ui/plan.js

@@ -561,8 +561,9 @@
     }
     // Collapse plan sidebar so user watches modules generate.
     hidePlanView();
-    // Server flips planMode off + runs the agentic pipeline.
-    ws.send(JSON.stringify({ type: "plan_approve" }));
+    // Resolve the parked "plan" checkpoint — plan mode is unified onto the
+    // checkpoint primitive (VIB-1880). Server flips planMode off + builds.
+    ws.send(JSON.stringify({ type: "checkpoint_resolve", kind: "plan", action: "approve" }));
     // Local state will be refreshed by the next init or modules_updated event.
     planModeActive = false;
     window.planModeActive = false;
@@ -573,7 +574,9 @@
   function discardPlan() {
     if (!confirm("Discard the current plan and exit plan mode?")) return;
     if (typeof ws !== "undefined" && ws && ws.readyState === 1) {
-      ws.send(JSON.stringify({ type: "plan_discard" }));
+      // Cancel the parked "plan" checkpoint (VIB-1880); falls back to plan_discard
+      // semantics server-side. HTTP fallback below for a dropped socket.
+      ws.send(JSON.stringify({ type: "checkpoint_resolve", kind: "plan", action: "cancel" }));
     } else {
       // Fallback to HTTP
       fetch("/api/plan/discard", { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" });

package/ui/styles.css

@@ -8216,3 +8216,250 @@ body { display: flex; }
     display: none;
   }
 }
+
+/* ---------------------------------------------------------------------------
+   Checkpoint gate card (VIB-1877) — design preview before the module build.
+   --------------------------------------------------------------------------- */
+.checkpoint {
+  border: 1px solid var(--border-hover);
+  border-radius: var(--radius);
+  background: var(--bg-elevated);
+  padding: var(--space-4);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  max-width: 520px;
+}
+.checkpoint__head {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  flex-wrap: wrap;
+}
+.checkpoint__badge {
+  font-size: var(--text-xs);
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--accent);
+  background: var(--accent-dim);
+  border-radius: var(--radius-pill);
+  padding: 3px 9px;
+}
+.checkpoint__headline {
+  font-family: var(--font-display);
+  font-size: var(--text-md);
+  color: var(--text);
+}
+.checkpoint__hero {
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  border: 1px solid var(--border);
+  background: #000;
+}
+.checkpoint__hero-frame {
+  display: block;
+  width: 100%;
+  height: 230px;
+  border: 0;
+}
+.checkpoint__tokens {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-4);
+  align-items: flex-start;
+}
+.checkpoint__palette {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  flex: 1 1 220px;
+}
+.checkpoint__swatch {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: var(--text-sm);
+  color: var(--text-dim);
+}
+.checkpoint__swatch-chip {
+  width: 16px;
+  height: 16px;
+  border-radius: 4px;
+  border: 1px solid var(--border-hover);
+  display: inline-block;
+}
+.checkpoint__type {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.checkpoint__type-row {
+  font-size: var(--text-lg);
+  color: var(--text);
+  line-height: 1.2;
+}
+.checkpoint__type-row--body {
+  font-size: var(--text-base);
+  color: var(--text-dim);
+}
+.checkpoint__muted { color: var(--text-dim); font-size: var(--text-sm); }
+.checkpoint__meta { font-size: var(--text-sm); color: var(--text-dim); }
+.checkpoint__cost { color: var(--text-dim); }
+.checkpoint__steer-input {
+  width: 100%;
+  resize: vertical;
+  background: var(--bg-input);
+  border: 1px solid var(--border-hover);
+  border-radius: var(--radius-sm);
+  color: var(--text);
+  font-family: var(--font);
+  font-size: var(--text-base);
+  padding: var(--space-2);
+}
+.checkpoint__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+.checkpoint__btn { font-size: var(--text-base); }
+.checkpoint__btn:disabled { opacity: 0.5; cursor: default; }
+
+/* Structure checkpoint (VIB-1879) — editable module outline. */
+.checkpoint__narrative {
+  font-size: var(--text-sm);
+  color: var(--text-dim);
+  line-height: 1.5;
+}
+.checkpoint__outline {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+.checkpoint__row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 6px 8px;
+}
+.checkpoint__row-move {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.checkpoint__row-btn {
+  border: 0;
+  background: transparent;
+  color: var(--text-dim);
+  cursor: pointer;
+  line-height: 1;
+  font-size: 9px;
+  padding: 1px 2px;
+  border-radius: 3px;
+}
+.checkpoint__row-btn:hover { color: var(--text); background: var(--bg-elevated); }
+.checkpoint__row-main {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.checkpoint__row-name {
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-sm);
+  color: var(--text);
+  font-family: var(--font-mono, monospace);
+  font-size: var(--text-base);
+  padding: 2px 4px;
+  width: 100%;
+}
+.checkpoint__row-name:hover { border-color: var(--border-hover); }
+.checkpoint__row-name:focus {
+  outline: none;
+  border-color: var(--accent);
+  background: var(--bg);
+}
+.checkpoint__row-desc {
+  font-size: var(--text-xs);
+  color: var(--text-dim);
+  padding: 0 4px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.checkpoint__row-remove {
+  border: 0;
+  background: transparent;
+  color: var(--text-dim);
+  cursor: pointer;
+  font-size: var(--text-base);
+  padding: 2px 6px;
+  border-radius: var(--radius-sm);
+  flex: 0 0 auto;
+}
+.checkpoint__row-remove:hover { color: var(--danger, #e5484d); background: var(--bg-elevated); }
+.checkpoint__add {
+  align-self: flex-start;
+  font-size: var(--text-sm);
+}
+
+/* One-shot send button — slightly dimmer than the primary send. */
+.chat__send--oneshot {
+  opacity: 0.7;
+}
+.chat__send--oneshot:hover:not(:disabled) {
+  opacity: 1;
+}
+
+/* Brand-intake gate (VIB-1878) — front-of-flow ask-back card. */
+.brand-intake__choices {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  margin: var(--space-3) 0;
+}
+.brand-intake__choice {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 2px;
+  text-align: left;
+  padding: var(--space-3);
+  height: auto;
+}
+.brand-intake__choice-title { font-weight: 600; }
+.brand-intake__choice-hint { font-size: var(--text-sm); opacity: 0.75; }
+.brand-intake__form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  margin: var(--space-3) 0;
+}
+.brand-intake__field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.brand-intake__label { font-size: var(--text-sm); font-weight: 600; }
+.brand-intake__input {
+  width: 100%;
+  font-family: inherit;
+  font-size: var(--text-base);
+  padding: var(--space-2);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--surface);
+  color: var(--text);
+  resize: vertical;
+}
+.brand-intake__form-actions {
+  display: flex;
+  gap: var(--space-2);
+  margin-top: var(--space-1);
+}
+.brand-intake__top-actions { margin-top: var(--space-2); }