@invisibleloop/pulse 0.14.1 → 0.14.2

package/examples/public/pulse-ui.js

@@ -0,0 +1,257 @@
+/**
+ * pulse-ui.js — Vanilla JS for interactive Pulse UI components
+ *
+ * Handles:
+ *   - Slider     (.ui-slider — live fill + value output)
+ *   - File Upload (.ui-upload — drag-and-drop, click-to-open)
+ *   - Modal      (data-modal-open, <dialog>, backdrop close)
+ *   - Nav        (.ui-nav — mobile burger menu)
+ *   - Carousel   (.ui-carousel — prev/next/dots)
+ *
+ * No dependencies. No build step required.
+ * CSP-safe: no inline handlers — all behaviour via event delegation.
+ * Include once per page: <script src="/pulse-ui.js"></script>
+ */
+
+// ─── Slider ──────────────────────────────────────────────────────────────────
+// Update --slider-fill on .ui-field wrapper + optional live value output.
+
+document.addEventListener('input', (e) => {
+  const el = e.target
+  if (!el.classList.contains('ui-slider')) return
+  const field = el.closest('.ui-field')
+  if (!field) return
+  const pct = ((el.value - el.min) / (el.max - el.min) * 100).toFixed(2) + '%'
+  field.style.setProperty('--slider-fill', pct)
+  const out = field.querySelector('.ui-slider-output')
+  if (out) out.textContent = el.value
+})
+
+// ─── File Upload ─────────────────────────────────────────────────────────────
+// Prevent browser navigating to dropped file anywhere on the page.
+// Handle drag visual feedback + file assignment on drop.
+// Handle click-to-open and keyboard activation.
+
+document.addEventListener('dragover', (e) => {
+  e.preventDefault()
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload:not(.ui-upload--disabled)')
+  if (zone) zone.classList.add('ui-upload--active')
+})
+
+document.addEventListener('dragleave', (e) => {
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload')
+  if (zone && !zone.contains(e.relatedTarget)) {
+    zone.classList.remove('ui-upload--active')
+  }
+})
+
+document.addEventListener('drop', (e) => {
+  e.preventDefault()
+  if (!(e.target instanceof Element)) return
+  const zone = e.target.closest('.ui-upload:not(.ui-upload--disabled)')
+  if (!zone) return
+  zone.classList.remove('ui-upload--active')
+  const input = zone.querySelector('.ui-upload-input')
+  if (!input || !e.dataTransfer.files.length) return
+  const dt = new DataTransfer()
+  Array.from(e.dataTransfer.files).forEach(f => dt.items.add(f))
+  input.files = dt.files
+  input.dispatchEvent(new Event('change', { bubbles: true }))
+})
+
+// File Upload: show selected filename in zone after file chosen
+document.addEventListener('change', (e) => {
+  const input = e.target
+  if (!input.classList.contains('ui-upload-input')) return
+  const zone = input.closest('.ui-upload')
+  if (!zone) return
+  const textEl = zone.querySelector('.ui-upload-text')
+  if (!textEl) return
+  if (input.files && input.files.length > 0) {
+    const names = Array.from(input.files).map(f => f.name).join(', ')
+    textEl.textContent = names
+    zone.classList.add('ui-upload--selected')
+  } else {
+    textEl.innerHTML = 'Drag &amp; drop or <span class="ui-upload-browse">browse</span>'
+    zone.classList.remove('ui-upload--selected')
+  }
+})
+
+// ─── Modal ──────────────────────────────────────────────────────────────────
+
+document.addEventListener('click', (e) => {
+  // File upload: click zone → open file picker
+  // Skip synthetic clicks emitted by input.click() itself to avoid loops
+  if (!e.target.classList.contains('ui-upload-input')) {
+    const zone = e.target.closest('.ui-upload')
+    if (zone) {
+      const input = zone.querySelector('.ui-upload-input')
+      if (input && !input.disabled) { input.click(); return }
+    }
+  }
+
+  // Dialog open: data-dialog-open="dialogId" (first-class) or data-modal-open="dialogId" (compat)
+  const trigger = e.target.closest('[data-dialog-open],[data-modal-open]')
+  if (trigger) {
+    const id     = trigger.dataset.dialogOpen ?? trigger.dataset.modalOpen
+    const dialog = document.getElementById(id)
+    if (dialog && typeof dialog.showModal === 'function') {
+      dialog.showModal()
+    }
+    return
+  }
+
+  // Dialog close: data-dialog-close (closes nearest ancestor <dialog>)
+  const closeTarget = e.target.closest('[data-dialog-close]')
+  if (closeTarget) {
+    const dialog = closeTarget.closest('dialog')
+    if (dialog) dialog.close()
+    return
+  }
+
+  // Backdrop close — click lands on <dialog> element itself
+  if (e.target.tagName === 'DIALOG') {
+    e.target.close()
+  }
+})
+
+// File upload: Enter / Space on focused zone → open picker
+document.addEventListener('keydown', (e) => {
+  if (e.key !== 'Enter' && e.key !== ' ') return
+  const zone = e.target.closest('.ui-upload')
+  if (!zone) return
+  const input = zone.querySelector('.ui-upload-input')
+  if (input && !input.disabled) { e.preventDefault(); input.click() }
+})
+
+// ─── Nav (mobile burger) ────────────────────────────────────────────────────
+
+function initNav(el) {
+  if (el.dataset.pulseNavInit) return
+  el.dataset.pulseNavInit = '1'
+
+  const burger = el.querySelector('.ui-nav-burger')
+  const mobile = el.querySelector('.ui-nav-mobile')
+
+  // Mobile burger
+  if (burger && mobile) {
+    const open   = () => { el.classList.add('ui-nav--open');    burger.setAttribute('aria-expanded', 'true') }
+    const close  = () => { el.classList.remove('ui-nav--open'); burger.setAttribute('aria-expanded', 'false') }
+    const toggle = () => el.classList.contains('ui-nav--open') ? close() : open()
+
+    burger.addEventListener('click', toggle)
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') close() })
+    document.addEventListener('click',   (e) => { if (!el.contains(e.target)) close() })
+    mobile.querySelectorAll('.ui-nav-link').forEach(a => a.addEventListener('click', close))
+  }
+
+  // Mega nav dropdowns
+  el.querySelectorAll('.ui-nav-mega-wrap').forEach(wrap => {
+    const trigger = wrap.querySelector('.ui-nav-mega-trigger')
+    const panel   = wrap.querySelector('.ui-nav-mega-panel')
+    if (!trigger || !panel) return
+
+    const openMega  = () => { panel.hidden = false; wrap.classList.add('ui-nav-mega-wrap--open');    trigger.setAttribute('aria-expanded', 'true') }
+    const closeMega = () => { panel.hidden = true;  wrap.classList.remove('ui-nav-mega-wrap--open'); trigger.setAttribute('aria-expanded', 'false') }
+    const toggleMega = () => panel.hidden ? openMega() : closeMega()
+
+    trigger.addEventListener('click', (e) => { e.stopPropagation(); toggleMega() })
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeMega() })
+    document.addEventListener('click',   (e) => { if (!wrap.contains(e.target)) closeMega() })
+    panel.querySelectorAll('.ui-nav-mega-item').forEach(a => a.addEventListener('click', closeMega))
+  })
+}
+
+function runNavs() { document.querySelectorAll('.ui-nav').forEach(initNav) }
+document.readyState === 'loading'
+  ? document.addEventListener('DOMContentLoaded', runNavs)
+  : runNavs()
+document.addEventListener('pulse:navigate', runNavs)
+
+// ─── Carousel ───────────────────────────────────────────────────────────────
+
+function initCarousel(el) {
+  if (el.dataset.pulseCarouselInit) return
+  el.dataset.pulseCarouselInit = '1'
+
+  const track  = el.querySelector('.ui-carousel-track')
+  const prev   = el.querySelector('.ui-carousel-prev')
+  const next   = el.querySelector('.ui-carousel-next')
+  const dots   = Array.from(el.querySelectorAll('.ui-carousel-dot'))
+  const slides = Array.from(el.querySelectorAll('.ui-carousel-slide'))
+
+  if (!track || slides.length === 0) return
+
+  let current = 0
+
+  const updateArrows = () => {
+    if (prev) prev.hidden = current === 0
+    if (next) next.hidden = current === slides.length - 1
+  }
+
+  const goTo = (i) => {
+    current = Math.max(0, Math.min(i, slides.length - 1))
+    track.scrollTo({ left: slides[current].offsetLeft, behavior: 'smooth' })
+    dots.forEach((d, j) => {
+      const active = j === current
+      d.classList.toggle('active', active)
+      d.setAttribute('aria-selected', String(active))
+      d.setAttribute('tabindex', active ? '0' : '-1')
+    })
+    updateArrows()
+  }
+
+  prev?.addEventListener('click', () => goTo(current - 1))
+  next?.addEventListener('click', () => goTo(current + 1))
+  dots.forEach((d, i) => d.addEventListener('click', () => goTo(i)))
+
+  // Keyboard navigation — roving tabindex for tablist
+  el.addEventListener('keydown', (e) => {
+    if (!e.target.classList.contains('ui-carousel-dot')) return
+    let next = null
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+      e.preventDefault()
+      next = current > 0 ? current - 1 : slides.length - 1
+    } else if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault()
+      next = current < slides.length - 1 ? current + 1 : 0
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      next = 0
+    } else if (e.key === 'End') {
+      e.preventDefault()
+      next = slides.length - 1
+    }
+    if (next !== null) {
+      goTo(next)
+      dots[next]?.focus()
+    }
+  })
+
+  // Sync dot state and arrows when user swipes / scrolls
+  track.addEventListener('scroll', () => {
+    const trackLeft = track.getBoundingClientRect().left
+    const idx = slides.findIndex((s) => Math.abs(s.getBoundingClientRect().left - trackLeft) < 10)
+    if (idx !== -1 && idx !== current) {
+      current = idx
+      dots.forEach((d, j) => {
+        const active = j === current
+        d.classList.toggle('active', active)
+        d.setAttribute('aria-selected', String(active))
+        d.setAttribute('tabindex', active ? '0' : '-1')
+      })
+      updateArrows()
+    }
+  }, { passive: true })
+}
+
+// Initialise all carousels on the page
+const run = () => document.querySelectorAll('.ui-carousel').forEach(initCarousel)
+document.readyState === 'loading'
+  ? document.addEventListener('DOMContentLoaded', run)
+  : run()
+
+// Re-initialise after Pulse client-side navigation swaps the DOM
+document.addEventListener('pulse:navigate', run)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.14.1
+0.14.2

package/public/pulse-ui.css

@@ -150,6 +150,20 @@ html, body {
   color:      var(--ui-text);
 }
 
+/* ghost-light — use on dark section backgrounds (e.g. navy hero, section--dark).
+   Renders with light/white text and a subtle light border so it remains legible
+   regardless of whether the surrounding theme is light or dark.               */
+.ui-btn--ghost-light {
+  background:   transparent;
+  color:        rgba(255, 255, 255, 0.9);
+  border:       1px solid rgba(255, 255, 255, 0.35);
+}
+.ui-btn--ghost-light:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.65);
+  color:        #ffffff;
+}
+
 .ui-btn--danger {
   background: var(--ui-red-dim);
   color:      var(--ui-red);
@@ -682,6 +696,36 @@ html, body {
 .ui-section--alt   { background: var(--ui-surface,   var(--surface,   #111116)); }
 .ui-section--dark  { background: var(--ui-surface-2, var(--surface-2, #18181f)); }
 
+/* In light theme, --ui-surface-2 resolves to a light grey — not "dark".
+   Override so section--dark always renders a genuinely dark background that
+   contrasts with the page, regardless of the active theme.                  */
+[data-theme="light"] .ui-section--dark,
+.ui-theme-light .ui-section--dark {
+  background:  var(--ui-dark-bg,  #1a1a2e);
+  color:       var(--ui-dark-text, #e2e2ea);
+}
+/* Ensure text children inherit the light colour in the dark section */
+[data-theme="light"] .ui-section--dark .ui-section-title,
+[data-theme="light"] .ui-section--dark .ui-section-eyebrow,
+[data-theme="light"] .ui-section--dark .ui-section-subtitle,
+.ui-theme-light .ui-section--dark .ui-section-title,
+.ui-theme-light .ui-section--dark .ui-section-eyebrow,
+.ui-theme-light .ui-section--dark .ui-section-subtitle {
+  color: inherit;
+}
+/* Ghost button inside a dark section on a light-theme page */
+[data-theme="light"] .ui-section--dark .ui-btn--ghost,
+.ui-theme-light .ui-section--dark .ui-btn--ghost {
+  color:        var(--ui-dark-text, #e2e2ea);
+  border-color: rgba(226, 226, 234, 0.35);
+}
+[data-theme="light"] .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]),
+.ui-theme-light .ui-section--dark .ui-btn--ghost:hover:not(.ui-btn--disabled):not([disabled]) {
+  background:   rgba(226, 226, 234, 0.1);
+  border-color: rgba(226, 226, 234, 0.65);
+  color:        var(--ui-dark-text, #e2e2ea);
+}
+
 /* diagonal — tapered bottom edge; follow with a section that starts flush */
 .ui-section--diagonal {
   background: var(--ui-surface, var(--surface, #111116));

package/src/agent/checklist.md

@@ -36,13 +36,15 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - Navigation → `nav({ logo, links, actions })`
   - Footers → `footer({ logo, links, columns, legal, ... })`
 
-- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression. This is a deliberate design decision, not a shortcut. When taking this path:
-  - State it explicitly in the build brief: *"Building component-free — raw HTML throughout for creative control."*
+- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
+  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
   - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
   - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
   - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
 
-- When reviewing a spec built under creative override, do not flag raw section HTML as a violation — check the Lighthouse results instead.
+- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
+
+- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
 
 - **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
 

package/src/agent/guide-components.md

@@ -148,7 +148,7 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 
 | Component | Key props |
 |-----------|-----------|
-| `button` | `label`, `variant` (primary/secondary/ghost/danger), `size` (sm/md/lg), `href`, `type`, `disabled`, `fullWidth`, `icon`, `iconAfter`, `attrs` |
+| `button` | `label`, `variant` (primary/secondary/ghost/**ghost-light**/danger), `size` (sm/md/lg), `href`, `type`, `disabled`, `fullWidth`, `icon`, `iconAfter`, `attrs` — **use `ghost-light` when the button sits on a dark background** (hero, `section--dark`, navy wrapper); `ghost` uses `--ui-muted` text which fails contrast on dark backgrounds in light theme |
 | `input` | `name`, `label`, `type`, `placeholder`, `value`, `error`, `hint`, `required`, `disabled`, `attrs` |
 | `search` | `name`, `label`, `labelHidden`, `placeholder`, `value`, `event` (e.g. `'input:setSearch'`), `debounce` (ms, default 200), `clearEvent` (shown when value non-empty), `disabled`, `attrs` — search input with icon + clear button. **Use this instead of `input({ type: 'search' })`.** |
 | `select` | `name`, `label`, `options` (strings or `{value,label}`), `value`, `error`, `required`, `event` |
@@ -299,7 +299,7 @@ This is by design: vibes are a paint job, not a structural transformation. Compo
 | Component | Key props |
 |-----------|-----------|
 | `container` | `content`, `size` (sm/md/lg/xl) |
-| `section` | `content`, `variant` (default/alt/dark/diagonal/paper/spotlight), `padding` (sm/md/lg), `id`, `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `align` — `diagonal`: tapered bottom edge; `paper`: dot-grid texture; `spotlight`: radial gradient focus |
+| `section` | `content`, `variant` (default/alt/dark/diagonal/paper/spotlight), `padding` (sm/md/lg), `id`, `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `align` — `diagonal`: tapered bottom edge; `paper`: dot-grid texture; `spotlight`: radial gradient focus; **`dark`: in light theme renders navy `#1a1a2e` background (not light grey) with automatic light text and ghost-button overrides; customise via `--ui-dark-bg`/`--ui-dark-text`** |
 | `grid` | `content`, `cols` (1–4), `gap` (sm/md/lg) — responsive, collapses on mobile |
 | `stack` | `content`, `gap` (xs–xl), `align` — flex column |
 | `cluster` | `content`, `gap`, `justify`, `align` — flex row with wrap |

package/src/agent/guide-styles.md

@@ -89,6 +89,15 @@ meta: {
 
 **Colour tokens:** `--ui-bg`, `--ui-surface`, `--ui-surface-2`, `--ui-border`, `--ui-text`, `--ui-muted`, `--ui-accent`, `--ui-accent-hover`, `--ui-accent-dim`, `--ui-accent-text`, `--ui-green`, `--ui-red`, `--ui-yellow`, `--ui-blue`, `--ui-radius`, `--ui-radius-sm`, `--ui-font`, `--ui-font-display`, `--ui-mono`. Never hardcode hex values — override the tokens.
 
+> **⚠ `--ui-muted` contrast on warm/light palettes** — The default `--ui-muted` value (`#60607a` in light theme) achieves 4.5:1 on the default white `--ui-bg`. When you set a warm or coloured background (`--bg: #f5e6d3` etc.) the luminance difference shrinks and `--ui-muted` can drop below the WCAG AA threshold of 4.5:1. **Always override `--muted` when changing `--bg`**, and run `pulse_check_contrast` immediately after writing your `theme.css`. A common failure mode: stat labels, nav links, and feature descriptions all use `--ui-muted` and will fail contrast silently if this token is not rechecked against your actual background colour.
+
+> **⚠ `section--dark` in light theme** — `section({ variant: 'dark' })` uses `--ui-surface-2` as its background, which in the default light theme resolves to `#f0f0f8` — a light grey, not a dark background. The framework now auto-corrects this via a `[data-theme="light"] .ui-section--dark` override (navy `#1a1a2e`), and ghost buttons inside it get automatic light-text treatment. If you use a custom `--surface-2` override in your theme, set `--ui-dark-bg` and `--ui-dark-text` to pin the dark section to specific values:
+> ```css
+> [data-theme="light"] { --ui-dark-bg: #1a1a2e; --ui-dark-text: #e8e0d0; }
+> ```
+
+> **Ghost buttons on dark backgrounds** — use `variant: 'ghost-light'` instead of `variant: 'ghost'` whenever the button sits on a dark background (custom hero div, `section--dark`, navy sections). `ghost-light` renders white text with a subtle white border, maintaining 4.5:1 contrast regardless of the surrounding theme. `ghost` uses `--ui-muted` text which fails on dark backgrounds in light theme.
+
 **Display font token:** `--ui-font-display` is used for hero titles and section headings. By default it inherits `--ui-font`. Override it separately to get a display/heading face that differs from body text:
 ```css
 /* app.css */
@@ -219,6 +228,12 @@ createServer(specs, {
 
 > **picsum CDN note:** `picsum.photos` redirects image requests through `fastly.picsum.photos`. You must whitelist **both** domains — whitelisting only `https://picsum.photos` will still block the actual image bytes and the browser error will point to the `fastly.picsum.photos` URL, which is confusing to debug.
 
+> **⚠ Unsplash and third-party cookies — Lighthouse Best Practices failure:** `images.unsplash.com` sets tracking cookies (`azk`, `azk-ss`) on every image request. These are classified as third-party cookies and cause Lighthouse Best Practices to drop to ~77, failing the 100 pass bar. **For production builds, download images locally instead of referencing Unsplash URLs directly.** Use `curl` to save images to `public/images/`:
+> ```bash
+> curl -sL "https://images.unsplash.com/photo-ID?w=900&q=85" -o public/images/hero.jpg
+> ```
+> Then reference `/images/hero.jpg` in your spec. This also improves performance (no external DNS lookup) and avoids rate limiting. `picsum.photos` does **not** set tracking cookies and is safe to use via CDN for prototypes.
+
 Without this, external images will be blocked in production and Lighthouse will flag a Best Practices failure. Use the same pattern for other external resource types (`media-src` for video, `connect-src` for fetch/XHR to external APIs).
 
 For multiple weights or italic variants, separate them with a semicolon in the URL:

package/src/agent/guide-templates.md

@@ -89,9 +89,12 @@ Run `pulse_intake` before presenting the confirmation. It collects the product d
 6. "Any specific font, or system-ui?"
 7. "Light or dark theme preference?"
 8. "How should it feel visually? (e.g. warm and friendly, editorial and sharp, playful, minimal, bold — or describe in your own words)"
+9. "Do you have any design inspiration — a site you love, a screenshot, a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."
 
 Ask each question and wait for the answer before asking the next. Do not present a list of preset choices for any of these — the answers are arbitrary text.
 
+**Question 9 is not optional.** Always ask it. If the user provides an image in `public/intake/`, call `pulse_extract_inspiration` on it before calling `pulse_intake`. If they provide a URL, call `pulse_extract_inspiration` with the URL. If they say no or skip it, proceed without — but always ask.
+
 Once you have the answers, call `pulse_intake` with the collected details. It returns a product brief + early contrast warnings.
 
 **If `pulse_intake` is unavailable**, gather the answers via the questions above and use them directly when adapting the template — replace every placeholder with real content.

package/src/agent/identity.md

@@ -51,7 +51,8 @@ Every build task follows a fixed sequence of phases with explicit pass gates. Fe
 2. **Plan** — present your plan, wait for user confirmation (skip only for trivially small tasks)
 3. **Build** — write the spec and related files
 4. **Validate** — `pulse_validate` must be clean before continuing
-5. **Browser** — screenshot + Lighthouse desktop + Lighthouse mobile, all 100/100/100 before continuing
+5. **Design approval** *(new builds only)* — take a screenshot, show the user, **wait for their go-ahead on layout and direction** before running any slow checks. For edits/fixes, skip this.
+5. **Verify** — `pulse_design_review` → `pulse_layout_review` → Lighthouse desktop + mobile, all 100/100/100 before continuing
 6. **Tests** — write and run tests, all must pass before continuing
 7. **Review Agent** — invoke only after phases 4–6 all pass
 8. **Fix** — fix every review issue, re-run any affected gates

package/src/agent/skills/verify/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: verify
-description: "Run the full verification loop on the current page or the page specified in $ARGUMENTS. If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context. Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid."
+description: "Run the full verification loop on the current page or the page specified in $ARGUMENTS. If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context."
 ---
 
 # Verify
 
 Run the full verification loop on the current page or the page specified in $ARGUMENTS.
 
+**Output style:** be terse throughout. One sentence per step. Do not quote raw tool output — summarise findings only. Reserve detail for failures that need explaining.
+
 ## Steps
 
 ### 1. Identify the target
@@ -15,53 +17,87 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 
 ### 2. Validate the spec
 
-Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid.
+Run `pulse_validate` on the spec file. Report clean or list errors. Stop if there are errors — do not continue until the spec is valid.
 
 ### 3. Check the dev server
 
-Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
+Run `pulse_fetch_page` to confirm the server is responding. If it errors, run `pulse_restart_server` and retry once. Report HTTP status only — do not quote the HTML body.
+
+**If the response has no `X-Pulse` header**, the wrong server is running on that port — stop and tell the user before continuing.
 
 ### 4. Screenshot
 
-Use the chrome-devtools navigate_page tool to load the page route, then take_screenshot to capture the result. Describe what you see — layout, content, any obvious rendering issues.
+Navigate to the page route with `mcp__chrome-devtools__navigate_page`, then take a screenshot with `mcp__chrome-devtools__take_screenshot`. Describe what you see in 2–3 plain sentences — layout structure, visual tone, key sections. Do not list features or code details.
+
+### 4a. Design approval gate *(new builds only)*
+
+**If `pulse_intake` ran earlier in this session** (i.e. this is a new page or site, not an edit or bug fix):
+
+1. Show the screenshot to the user.
+2. Ask: *"Happy with the layout and direction, or any changes before I run Lighthouse?"*
+3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves.
+
+If the user requests changes: make edits, restart the server, take a new screenshot, describe what changed, ask again. Repeat until approved. No Lighthouse between design rounds.
+
+**For edits, bug fixes, or "add X to existing Y"** — skip this step and go straight to 4b.
+
+### 4b. Design review *(if `pulse_intake` ran)*
+
+Run `pulse_design_review`. Work through every signal it returns. Fix any Fail before continuing. Report pass/fail count only — do not quote the full output.
+
+### 4c. Layout review
+
+Run `pulse_layout_review` with the page URL. It checks 390/768/1280px viewports for overflow, broken images, and collapsed sections. Fix any failures before continuing. Report pass or list failures only.
+
+### 5. Production build
+
+Run `pulse_build` to start the production server on port 3001. Tell the user: "Building for production — ~30s…" before calling it.
+
+### 6. Lighthouse — desktop
+
+Navigate to `http://localhost:3001/<route>` with `mcp__chrome-devtools__navigate_page`, then run `mcp__chrome-devtools__lighthouse_audit` with `device: "desktop"`.
+
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Report scores as a single line, e.g. `Accessibility 100 · Best Practices 100 · SEO 100`. If any score is below 100, identify the failing audit(s), fix, and restart from step 2.
+
+### 7. Lighthouse — mobile
 
-### 5. Lighthouse — desktop
+Run `mcp__chrome-devtools__lighthouse_audit` with `device: "mobile"` against the same production URL. Same pass bar. Report scores as a single line. Fix failures and restart from step 2 if needed.
 
-Run lighthouse_audit on the route in desktop mode.
+**To inspect mobile layout** use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. Reset with `"1440x900x1"` afterward.
 
-**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
+### 8. Performance
 
-### 6. Lighthouse — mobile
+Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS as a single line, e.g. `LCP 73ms · CLS 0.00`. Flag any insight that identifies a fixable cause (render-blocking resources, large image delay). CLS must be 0.00.
 
-Run lighthouse_audit on the same route in mobile mode.
+### 9. Console errors
 
-**Same pass bar: all three categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+Run `mcp__chrome-devtools__list_console_messages` filtered to errors and warnings. Report count only if clean. List any errors found.
 
-### 7. Performance
+### 10. Code review
 
-Navigate to the page route, then run performance_start_trace with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+Run `pulse_review` with the absolute path to the spec file. Work through every item in the checklist it returns. Fix every issue before proceeding. Report pass or list what was fixed — do not quote the full review output.
 
-### 8. Console errors
+### 11. Close the browser
 
-Use list_console_messages — report any errors or unexpected warnings.
+Run `mcp__chrome-devtools__list_pages`, then `mcp__chrome-devtools__close_page` for every page ID returned. `pageId` must be a JSON number, not a string.
 
-### 9. Code review
+### 12. Write verification stamp
 
-Use `pulse_review` to switch into reviewer mode. Read the spec against the checklist in `.github/instructions/pulse-checklist.instructions.md`. Work through every item. Fix anything that fails before proceeding.
+```bash
+date +%s > .pulse-verified
+```
 
-### 10. Close the browser
+**This must be the last write before stopping.** Do not edit any spec file after writing the stamp.
 
-Use list_pages to get all open pages, then call close_page for every page ID returned.
+### 13. Report
 
-### 11. Report
+One short paragraph covering: validation, Lighthouse desktop/mobile scores, LCP, CLS, console, review. Flag anything that needed fixing. No raw tool output.
 
-Summarise:
-- Validation: pass or fail (with errors if any)
-- Visual: what was visible in the screenshot
-- Lighthouse desktop: scores for all three categories
-- Lighthouse mobile: scores for all three categories
-- Performance: LCP and CLS values, any flagged insights
-- Console: any errors
-- Review: pass or issues found and fixed
+**Pass bar — all must be met:**
+- Validation: clean
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same
+- CLS: 0.00
+- Console: no errors
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+If any gate fails, fix and run `/verify` again.