@invisibleloop/pulse 0.17.0 → 0.17.2

package/scripts/css-purge.js

@@ -0,0 +1,241 @@
+/**
+ * CSS purge + minify — used by scripts/build.js.
+ *
+ * Extracted into its own module so the parser can be unit-tested
+ * (build.js runs the build at import time and cannot be imported by tests).
+ */
+
+// ---------------------------------------------------------------------------
+// CSS class extractor
+// ---------------------------------------------------------------------------
+
+export function extractUsedClasses(htmlContents, jsContents, safelist = []) {
+  const used = new Set()
+
+  // Extract from class="..." in both rendered HTML and JS template literals
+  for (const content of [...htmlContents, ...jsContents]) {
+    const re = /class(?:Name)?=["']([^"'\n]+)["']/g
+    let m
+    while ((m = re.exec(content)) !== null) {
+      for (const cls of m[1].trim().split(/\s+/)) {
+        if (cls) used.add(cls)
+      }
+    }
+  }
+
+  // Scan JS source for quoted strings that look like CSS class names (contain hyphens)
+  // Catches conditionally-applied classes like 'ui-btn--disabled' in ternaries
+  for (const js of jsContents) {
+    const re = /['"`]((?:[a-zA-Z][a-zA-Z0-9]*-[a-zA-Z0-9-]*)(?:\s+[a-zA-Z][a-zA-Z0-9-]*)*)['"`]/g
+    let m
+    while ((m = re.exec(js)) !== null) {
+      for (const cls of m[1].trim().split(/\s+/)) {
+        if (cls && cls.includes('-')) used.add(cls)
+      }
+    }
+  }
+
+  // Apply safelist from pulse.config.js — css.safelist accepts strings or RegExp.
+  // String entries are added directly; RegExp entries are matched against all
+  // class names defined in the CSS (resolved later in purgeCss via selectorUsed
+  // because we don't have the CSS text here). To handle RegExp, we mark them as
+  // a sentinel that selectorUsed checks separately.
+  for (const entry of safelist) {
+    if (typeof entry === 'string') {
+      used.add(entry)
+    }
+    // RegExp entries are stored on the Set as a symbol property for selectorUsed to check
+  }
+  if (safelist.some(e => e instanceof RegExp)) {
+    used._safelistPatterns = safelist.filter(e => e instanceof RegExp)
+  }
+
+  return used
+}
+
+// ---------------------------------------------------------------------------
+// CSS purger — strips unused rules, preserves @media / :root / element rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CSS text into top-level blocks using a bracket-depth counter.
+ * Quote-aware: `;` and braces inside '...' or "..." strings are content, not
+ * structure — an @import URL like url('...?family=Inter:wght@400;600&display=swap')
+ * must not be split at the `;` inside the quotes.
+ * Returns [{ type, selector?, prelude?, inner?, raw }]
+ */
+export function parseCssBlocks(css) {
+  const blocks = []
+  let i = 0
+  const len = css.length
+
+  // Advance past a quoted string starting at css[i] (which is ' or ").
+  // Handles backslash escapes. Returns the index just past the closing quote.
+  const skipString = (idx) => {
+    const quote = css[idx]
+    idx++
+    while (idx < len && css[idx] !== quote) {
+      if (css[idx] === '\\') idx++
+      idx++
+    }
+    return idx + 1 // past closing quote (or len)
+  }
+
+  while (i < len) {
+    // Skip whitespace
+    while (i < len && /\s/.test(css[i])) i++
+    if (i >= len) break
+
+    // Skip block comments
+    if (css[i] === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2)
+      i = end === -1 ? len : end + 2
+      continue
+    }
+
+    const start = i
+    let depth = 0
+
+    while (i < len) {
+      // Skip inline comments
+      if (css[i] === '/' && css[i + 1] === '*') {
+        const end = css.indexOf('*/', i + 2)
+        i = end === -1 ? len : end + 2
+        continue
+      }
+      // Skip quoted strings — ; { } inside them are content, not structure
+      if (css[i] === '"' || css[i] === "'") { i = skipString(i); continue }
+      if (css[i] === '{') { depth++; i++; continue }
+      if (css[i] === '}') { depth--; i++; if (depth === 0) break; continue }
+      if (css[i] === ';' && depth === 0) { i++; break }
+      i++
+    }
+
+    const raw = css.slice(start, i).trim()
+    if (!raw) continue
+
+    if (raw.startsWith('@')) {
+      const braceIdx = raw.indexOf('{')
+      if (braceIdx === -1) {
+        blocks.push({ type: 'at-simple', raw })
+      } else {
+        const prelude = raw.slice(0, braceIdx).trim()
+        const inner   = raw.slice(braceIdx + 1, raw.lastIndexOf('}')).trim()
+        blocks.push({ type: 'at-block', prelude, inner, raw })
+      }
+    } else {
+      const braceIdx = raw.indexOf('{')
+      if (braceIdx !== -1) {
+        blocks.push({ type: 'rule', selector: raw.slice(0, braceIdx).trim(), raw })
+      }
+    }
+  }
+
+  return blocks
+}
+
+/**
+ * Return true if any selector in the rule should be kept.
+ *
+ * Matching strategy: check the *rightmost* class token in the selector (the
+ * subject of the rule). A rule like `.parent .child` should survive only when
+ * `.child` is used — keeping it whenever `.parent` is used would retain dead
+ * rules whose actual target class was never referenced.
+ *
+ * Pseudo-classes/elements and attribute selectors are stripped before checking
+ * so `.btn:hover` is treated as `.btn`, `.btn--active::before` as `.btn--active`.
+ *
+ * Element-only selectors (`a`, `*`, `:root`) and rules that contain no class
+ * tokens at all are always kept.
+ */
+export function selectorUsed(selector, usedClasses) {
+  const selectors = selector.split(',').map(s => s.trim())
+
+  for (const sel of selectors) {
+    // Strip pseudo-classes/elements and attribute selectors to find the base
+    const base = sel
+      .replace(/::?[a-z-]+(\([^)]*\))?/gi, '')
+      .replace(/\[[^\]]*\]/g, '')
+      .trim()
+
+    // Keep element-only selectors — no class tokens present
+    if (!base.includes('.')) return true
+
+    // Extract all class tokens and check the rightmost one (the rule subject).
+    // Using the rightmost class correctly handles descendant selectors:
+    //   .nav .link  → subject is .link
+    //   .btn--active → subject is .btn--active
+    const classes = [...base.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g)].map(m => m[1])
+    if (classes.length === 0) return true
+    const subject = classes[classes.length - 1]
+    if (usedClasses.has(subject)) return true
+
+    // Check RegExp safelist patterns if any were provided
+    const patterns = usedClasses._safelistPatterns
+    if (patterns && patterns.some(re => re.test(subject))) return true
+  }
+
+  return false
+}
+
+/**
+ * Minify a CSS string. String-aware: content inside '...' or "..." is left
+ * untouched so quoted URLs (e.g. Google Fonts @import with ; and : in the
+ * query string) survive intact.
+ */
+export function minifyCss(css) {
+  // Protect quoted strings from the whitespace/punctuation passes
+  const strings = []
+  const protectedCss = css.replace(/(['"])(?:\\.|(?!\1).)*\1/g, (m) => {
+    strings.push(m)
+    return `\x00S${strings.length - 1}\x00`
+  })
+
+  const minified = protectedCss
+    .replace(/\/\*[\s\S]*?\*\//g, '')   // strip comments
+    .replace(/\s+/g, ' ')               // collapse whitespace
+    // Remove spaces around safe punctuation — NOT + or - (would break calc() expressions)
+    .replace(/\s*([{}:;,>~])\s*/g, '$1')
+    .replace(/;}/g, '}')                // remove trailing semicolons
+    .trim()
+
+  return minified.replace(/\x00S(\d+)\x00/g, (_, i) => strings[+i])
+}
+
+/**
+ * Purge unused CSS rules from a CSS string.
+ * Recursively processes @media and @supports blocks.
+ */
+export function purgeCss(cssText, usedClasses) {
+  const blocks = parseCssBlocks(cssText)
+  const kept   = []
+
+  for (const block of blocks) {
+    if (block.type === 'at-simple') {
+      kept.push(block.raw)
+    } else if (block.type === 'at-block') {
+      const p = block.prelude.toLowerCase()
+      if (/^@(?:keyframes|font-face|charset)/.test(p)) {
+        kept.push(block.raw)
+      } else if (/^@(?:media|supports)/.test(p)) {
+        const innerPurged = purgeCss(block.inner, usedClasses)
+        if (innerPurged.trim()) kept.push(`${block.prelude} {\n${innerPurged}\n}`)
+      } else if (/^@layer/.test(p)) {
+        // Always preserve empty @layer declarations — they establish cascade order
+        // and removing them silently changes specificity even when no rules remain.
+        const innerPurged = purgeCss(block.inner, usedClasses)
+        if (innerPurged.trim()) {
+          kept.push(`${block.prelude} {\n${innerPurged}\n}`)
+        } else {
+          kept.push(`${block.prelude} {}`)
+        }
+      } else {
+        kept.push(block.raw) // unknown at-blocks — keep to be safe
+      }
+    } else if (block.type === 'rule') {
+      if (selectorUsed(block.selector, usedClasses)) kept.push(block.raw)
+    }
+  }
+
+  return kept.join('\n\n')
+}

package/scripts/css-purge.test.js

@@ -0,0 +1,94 @@
+/**
+ * CSS purge/minify tests — run with: node scripts/css-purge.test.js
+ *
+ * Regression focus: @import URLs containing `;` and `&` in their query string
+ * (Google Fonts) were truncated by the production build — the block parser
+ * split the statement at the `;` inside the quoted URL, silently breaking the
+ * theme in production while dev (which serves CSS unprocessed) looked fine.
+ */
+
+import { test } from 'node:test'
+import assert   from 'node:assert/strict'
+import { parseCssBlocks, purgeCss, minifyCss, extractUsedClasses, selectorUsed } from './css-purge.js'
+
+const FONT_IMPORT = `@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap');`
+
+// ---------------------------------------------------------------------------
+// The @import regression
+// ---------------------------------------------------------------------------
+
+test('parseCssBlocks: does not split @import at a ; inside a quoted URL', () => {
+  const css = `${FONT_IMPORT}\n:root { --accent: #e25; }`
+  const blocks = parseCssBlocks(css)
+  assert.equal(blocks.length, 2, `Expected 2 blocks, got ${blocks.length}: ${JSON.stringify(blocks.map(b => b.raw))}`)
+  assert.equal(blocks[0].type, 'at-simple')
+  assert.equal(blocks[0].raw, FONT_IMPORT)
+})
+
+test('parseCssBlocks: handles double-quoted URLs and escapes', () => {
+  const css = `@import url("https://example.com/a;b&c=d");\n.x { color: red; }`
+  const blocks = parseCssBlocks(css)
+  assert.equal(blocks[0].raw, `@import url("https://example.com/a;b&c=d");`)
+})
+
+test('purgeCss + minifyCss: Google Fonts @import survives the full pipeline intact', () => {
+  const css = `${FONT_IMPORT}\n:root { --font: 'Inter', sans-serif; }\n.unused { color: red; }`
+  const out = minifyCss(purgeCss(css, new Set([])))
+  assert.ok(
+    out.includes(`url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap')`),
+    `@import URL was mangled by the build pipeline. Output: ${out}`
+  )
+})
+
+test('minifyCss: quoted strings are untouched by punctuation collapsing', () => {
+  const css = `.x { content: "a ; b : c , d" ; }`
+  const out = minifyCss(css)
+  assert.ok(out.includes(`"a ; b : c , d"`), `Quoted string was altered: ${out}`)
+})
+
+// ---------------------------------------------------------------------------
+// Behaviour preserved through the extraction refactor
+// ---------------------------------------------------------------------------
+
+test('purgeCss: drops unused class rules, keeps used ones', () => {
+  const css = `.used { color: red; }\n.unused { color: blue; }`
+  const out = purgeCss(css, new Set(['used']))
+  assert.ok(out.includes('.used'))
+  assert.ok(!out.includes('.unused'))
+})
+
+test('purgeCss: element and :root rules are always kept', () => {
+  const css = `:root { --x: 1; }\nbody { margin: 0; }`
+  const out = purgeCss(css, new Set([]))
+  assert.ok(out.includes(':root'))
+  assert.ok(out.includes('body'))
+})
+
+test('purgeCss: recurses into @media and keeps @font-face', () => {
+  const css = `@media (min-width: 600px) { .used { color: red; } .unused { color: blue; } }\n@font-face { font-family: X; src: url('/x.woff2'); }`
+  const out = purgeCss(css, new Set(['used']))
+  assert.ok(out.includes('.used'))
+  assert.ok(!out.includes('.unused'))
+  assert.ok(out.includes('@font-face'))
+})
+
+test('selectorUsed: rightmost class is the subject', () => {
+  assert.equal(selectorUsed('.nav .link', new Set(['link'])), true)
+  assert.equal(selectorUsed('.nav .link', new Set(['nav'])), false)
+  assert.equal(selectorUsed('.btn:hover', new Set(['btn'])), true)
+})
+
+test('extractUsedClasses: finds class attributes and hyphenated JS strings', () => {
+  const used = extractUsedClasses(
+    ['<div class="hero card">'],
+    [`el.classList.add('ui-btn--active')`]
+  )
+  assert.ok(used.has('hero'))
+  assert.ok(used.has('card'))
+  assert.ok(used.has('ui-btn--active'))
+})
+
+test('minifyCss: calc() expressions keep their operator spacing', () => {
+  const out = minifyCss(`.x { width: calc(100% - 2rem); }`)
+  assert.ok(out.includes('calc(100% - 2rem)'), `calc broken: ${out}`)
+})

package/src/agent/checklist.md

@@ -20,6 +20,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
+
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first — or creative override
@@ -66,8 +68,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
 
 ### Correctness
 
@@ -106,6 +108,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
 - **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 

package/src/agent/commands/verify.md

@@ -15,8 +15,8 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose.
-3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved.
+2. **Call `pulse_await_approval` first**, then ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end — it is consumed when the user replies.
+3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 ### 3. Validate the spec
 
@@ -46,7 +46,7 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
-After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
+**Stay on the production server (port 3001)** — steps 8 and 9 use it too. Do not call `pulse_restart_server` yet.
 
 ### 8. Mobile layout check
 
@@ -54,7 +54,7 @@ Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and
 
 ```
 mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
-mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3001/"
 mcp__chrome-devtools__take_screenshot
 ```
 
@@ -72,7 +72,9 @@ mcp__chrome-devtools__emulate  viewport: "1440x900x1"
 
 ### 9. Performance
 
-Navigate to the page route, then run `mcp__chrome-devtools__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 the trace against the production server, not dev.** Navigate to `http://localhost:3001/<route>` first — if the production server is no longer running, run `pulse_build` again. Tracing the dev server (port 3000) reports misleading LCP/CLS. Then run `mcp__chrome-devtools__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.).
+
+After the trace, call `pulse_restart_server` to return to the dev server.
 
 ### 10. Console errors
 

package/src/agent/coverage-check.js

@@ -13,6 +13,11 @@
 import { execSync } from 'child_process'
 import fs from 'fs'
 
+// Agent is ending its turn to wait for the user's answer (design-approval gate) —
+// let the turn end. The marker is consumed on the user's next prompt, so the
+// gates return in full force afterwards.
+if (fs.existsSync('.pulse-awaiting-approval')) process.exit(0)
+
 // No test files → nothing to check
 const hasTests = fs.existsSync('src/pages') && (function scan(d) {
   for (const f of fs.readdirSync(d)) {

package/src/agent/guide-spec.md

@@ -1,5 +1,11 @@
 Pulse is a spec-first frontend framework. Pages are JS files that export a default spec object.
 
+## Mental model — one spec per page
+
+- **One spec = one route = one file** under `src/pages/`. Every page of a site is its own spec file — a site is a collection of specs, not one big spec.
+- **A dynamic route is still one spec.** `route: '/blog/:slug'` is a single file serving *every* blog post URL — the `:param` does the multiplying. Never create one spec per item (`post-1.js`, `post-2.js`, …), and never merge several distinct pages into one spec with conditionals on `ctx`.
+- **Specs share code, they don't repeat it.** Shared sections, layouts, nav, and footer live in `src/components/` and are imported by each spec that needs them (see `pulse://guide/routing` for the `layout()` pattern).
+
 ## Spec structure
 
 ```js
@@ -10,6 +16,10 @@ export default {
     title:       'Page Title',             // string or async (ctx) => string
     description: 'Meta description',       // string or async (ctx) => string
     styles:      ['/app.css'],             // string[] or (ctx) => string[]
+    theme:       'light',                  // 'light' | 'dark' — ⚠ DEFAULT IS DARK when unset.
+                                           // Decide at write time: a light design needs
+                                           // meta.theme: 'light' or the page renders dark.
+    vibe:        'minimal',                // optional — radius/weight/spacing preset
     ogTitle:     'Social title',           // optional — falls back to title
     ogImage:     'https://…/og.jpg',       // optional — 1200×630 recommended
     canonical:   'https://mysite.com/…',  // optional — string or (ctx) => string

package/src/agent/guide-styles.md

@@ -199,6 +199,8 @@ The default CSP does **not** restrict `img-src` — it inherits `default-src 'se
 
 **Do this at build time, before writing any image tags.** If you know you'll use external images, add the CSP entry to `pulse.config.js` first — discovering the block at Lighthouse time costs an extra round-trip.
 
+**Use `pulse_check_csp` to get the origin list right first time.** Many hosts redirect to a CDN origin (picsum.photos → fastly.picsum.photos), and allowing only the URL you wrote still blocks the actual bytes. Pass it the URLs you plan to use and it follows each redirect chain and returns ready-to-paste CSP config with every origin included.
+
 ```js
 // pulse.config.js
 export default {
@@ -213,7 +215,7 @@ Or via `createServer`:
 ```js
 createServer(specs, {
   csp: {
-    'img-src': ['https://images.unsplash.com', 'https://picsum.photos'],
+    'img-src': ['https://images.unsplash.com', 'https://picsum.photos', 'https://fastly.picsum.photos'],
   },
 })
 ```

package/src/agent/skills/build-page/SKILL.md

@@ -40,11 +40,11 @@ Write the spec file. Follow these rules:
 
 Use `pulse_validate` on the spec. Fix any errors before continuing.
 
-### 5. Register with the server
+### 5. Restart and reload
 
-Check the project's server entry file (e.g. `src/server.js` or `pulse.config.js`) and add the new spec if needed.
+Pages under `src/pages/` are auto-discovered — no server entry file to edit. Call `pulse_restart_server`, then `navigate_page` so the browser is not on a stale tab.
 
-### 6. Screenshot
+### 6. Screenshot + design approval
 
 Use the chrome-devtools navigate_page tool to load the page, then take_screenshot.
 
@@ -53,13 +53,15 @@ Check for:
 - Layout looks correct
 - No console errors via list_console_messages
 
+Then **call `pulse_await_approval`** and ask the user: *"Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?"* Always call the tool before asking, even when using a question tool like AskUserQuestion — in some hosts (including Claude Code) the question still ends the turn and fires the Stop hooks; the marker is harmless if the turn doesn't end. **Do not proceed until the user explicitly approves.** If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
+
 ### 7. Lighthouse
 
-Run lighthouse_audit (desktop, then mobile). All four scores — Accessibility, Best Practices, SEO, Performance — must be 100 before continuing.
+Run lighthouse_audit (desktop, then mobile) against the production server — call `pulse_build` first and navigate to the production URL. **Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is reported but not gated (it varies with machine load).
 
 ### 8. Run the checklist
 
-Go through `.github/instructions/pulse-checklist.instructions.md` and confirm every applicable point passes. Fix anything that fails.
+Go through `.claude/pulse-checklist.md` and confirm every applicable point passes. Fix anything that fails.
 
 ### 9. Write tests
 

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

@@ -34,8 +34,8 @@ Navigate to the page route with `mcp__chrome-devtools__navigate_page`, then take
 **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.
+2. **Call `pulse_await_approval` first, then ask:** *"Happy with the layout and direction, or any changes before I run Lighthouse?"* Always call the tool before asking, even when using a question tool like AskUserQuestion — in some hosts (including Claude Code) the question still ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end; it is consumed when the user replies.
+3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 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.
 
@@ -67,7 +67,7 @@ Run `mcp__chrome-devtools__lighthouse_audit` with `device: "mobile"` against the
 
 ### 8. Performance
 
-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.
+**Stay on the production server (port 3001) for the trace** — navigate to `http://localhost:3001/<route>` first; tracing the dev server (port 3000) reports misleading LCP/CLS. 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.
 
 ### 9. Console errors
 

package/src/agent/workflow.md

@@ -32,7 +32,7 @@ For any **new page, landing page, or branded site**, run the intake sequence fir
 
 - **Step 0 — Ask for inspiration first (mandatory):** Before calling any tool or presenting any plan, ask the user: *"Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."* Wait for the answer. Do not skip this question, even if the user's brief already seems detailed. Check `public/intake/` for any images already dropped there.
 - **`pulse_extract_inspiration`** — call this after step 0 if the user supplies a URL, site name, or image they like. Also call it for any images already present in `public/intake/`. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If the user explicitly says they have no reference, skip this step.
-- **`pulse_intake`** — captures the real content (name, pitch, features, palette, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions.
+- **`pulse_intake`** — captures the real content (name, pitch, features, palette, theme, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions. **Always ask light or dark** — Pulse renders dark when `meta.theme` is unset, so an unstated light design ships dark.
 - **`pulse_sketch`** — generates 3 structurally distinct layout directions (full-bleed, asymmetric split, typography-only, editorial, dense grid, story scroll, content-first). **Call this before writing any code.** Prevents defaulting to centred hero + three-column features every time.
 - **Skip `pulse_sketch` only** when the vibe is `corporate` or `minimal` AND the user hasn't expressed any structural preference. For `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes, `pulse_sketch` is mandatory — templates have default section orders that actively fight these vibes.
 - **`pulse_intent`** — maps the chosen direction to a spec scaffold and tells you which guides to read.
@@ -59,6 +59,8 @@ If the user's request is already very specific (a one-liner edit, a bug fix, "ad
 
 Call `pulse_list_structure` to see what already exists. Fetch only the guide sections relevant to your intent (the `pulse_intent` response tells you which ones).
 
+**Check `src/components/` for shared sections before building.** If a layout, nav, footer, CTA strip, or section you're about to write already exists there — or already exists inline in another spec — reuse or extract it now rather than writing a second copy. Catching duplication here is cheap; catching it at review (phase 7) means the expensive gates already ran against the duplicated version.
+
 Do not fetch every guide section for every task. Fetch what you need.
 
 ---
@@ -68,6 +70,7 @@ Do not fetch every guide section for every task. Fetch what you need.
 Decide the complexity tier (see below) and confirm with the user if the task is non-trivial. Output a concise plan:
 
 - Route, state shape, mutations/actions, server fetchers
+- **Theme: light or dark** — Pulse defaults to **dark** when `meta.theme` is unset. Decide now (ask the user if the brief doesn't say) — discovering a wrong theme at the screenshot costs a full edit → restart → re-approval cycle.
 - Which UI components you will use
 - Files you will create or modify
 
@@ -157,6 +160,8 @@ Or use the guide-components table. Never write these patterns from scratch in Mo
 
 If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop — use the component instead.
 
+**Reuse across specs (both modes):** one spec = one page; a site is many specs sharing code. Before writing a new section, check `src/components/` — and if a section you're writing already exists in another spec, extract it to `src/components/` *now* and import it from both, rather than pasting a copy. Same for CSS: a shared section's styles go in the shared `app.css` (listed in `meta.styles` by every spec that uses it), never duplicated into per-page stylesheets.
+
 **Mode B — Creative override (raw HTML throughout)**
 When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
 
@@ -175,6 +180,7 @@ Before writing any file, output a build brief:
 ```
 Building:   <page name> (<route>)
 Mode:       A — components first | B — creative override (raw HTML, reason: ...)
+Theme:      light | dark (+ vibe, if any) — default is DARK when meta.theme is unset
 State:      <fields and types, or "none">
 Mutations:  <list, or "none">
 Actions:    <list with brief description, or "none">
@@ -236,6 +242,12 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 3. **Ask the user directly:** *"Happy with the layout and direction, or any changes before I run tests and Lighthouse?"*
 4. **Wait for their response before doing anything else.** Do not run design_review, layout_review, or Lighthouse until you have a clear go-ahead.
 
+**How to wait without tripping the Stop hooks.** The project's Stop hooks (missing tests, coverage, verify stamp) block any turn that ends with unverified spec edits — they cannot tell "abandoning the work" from "pausing for the user's answer". So:
+
+- **Always call `pulse_await_approval` immediately before asking** — regardless of whether you ask via a question tool or in plain prose. In some hosts (including Claude Code) even AskUserQuestion ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end: it is simply consumed when the user replies.
+- Then ask the question (question tool with choices where available, plain prose otherwise) and end your turn.
+- **Never** respond to a `VERIFY REQUIRED` block by running `/verify` while your approval question is unanswered. The block does not override the approval gate — an unanswered question means the design is not approved, and Lighthouse on an unapproved design wastes ~90 seconds and pre-empts the user's changes.
+
 **If the user requests changes:**
 - Make the edits
 - Take a new screenshot
@@ -264,6 +276,16 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 2. `pulse_layout_review <url>` — 390/768/1280px overflow, broken images, collapsed sections
 3. `/verify` — Lighthouse desktop + mobile (100/100/100) + CLS 0.00 + `pulse_review`
 
+**Two different reviews — don't confuse them.** `pulse_design_review` is the *visual* review (7 signals) and runs **before** Lighthouse. `pulse_review` is the *code* review and runs **after** Lighthouse, always last. The canonical end-to-end order is:
+
+```
+pulse_validate → design approval → pulse_design_review → pulse_layout_review
+  → pulse_build → Lighthouse desktop + mobile → performance trace
+  → pulse_review → pulse_stamp
+```
+
+If a step's fixes touch the spec, re-run from `pulse_validate` — never re-run `pulse_review` on code that hasn't re-passed Lighthouse.
+
 **Do not report the page as done until `/verify` writes the `.pulse-verified` stamp.** Skipping Lighthouse means broken contrast, missing landmarks, and Best Practices failures ship to the user.
 
 Pass gates:

package/src/cli/scaffold.js

@@ -188,12 +188,26 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
           ]
         }
       ],
+      UserPromptSubmit: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              // Consume the awaiting-approval marker: it grants exactly one turn-end
+              // (the one that asks the user a blocking question). As soon as the user
+              // replies, the Stop gates are back in force for the next turn.
+              command: `node -e "try{require('fs').unlinkSync('.pulse-awaiting-approval')}catch{}"`,
+              statusMessage: 'Clearing approval pause...',
+            }
+          ]
+        }
+      ],
       Stop: [
         {
           hooks: [
             {
               type: 'command',
-              command: `node -e "const fs=require('fs');const{execSync}=require('child_process');let changed=new Set();let hasGit=false;try{execSync('git rev-parse --is-inside-work-tree',{stdio:'pipe'});hasGit=true;execSync('git status --porcelain',{encoding:'utf8'}).split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f)changed.add(f);});}catch{}if(!hasGit&&fs.existsSync('src/pages')){for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))changed.add('src/pages/'+f);}}const specs=[...changed].filter(f=>f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'));const missing=specs.filter(f=>{const t=f.replace(/\\.js$/,'.test.js');return!fs.existsSync(t)&&!changed.has(t);});if(missing.length){process.stdout.write(JSON.stringify({decision:'block',reason:'TESTS MISSING: '+missing.join(', ')+' — you must write tests before finishing. Use renderSync/render from @invisibleloop/pulse/testing to test view output, mutations, and any extracted logic functions. Run the tests with node to confirm they pass.'}));}"`,
+              command: `node -e "const fs=require('fs');if(fs.existsSync('.pulse-awaiting-approval'))process.exit(0);const{execSync}=require('child_process');let changed=new Set();let hasGit=false;try{execSync('git rev-parse --is-inside-work-tree',{stdio:'pipe'});hasGit=true;execSync('git status --porcelain',{encoding:'utf8'}).split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f)changed.add(f);});}catch{}if(!hasGit&&fs.existsSync('src/pages')){for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))changed.add('src/pages/'+f);}}const specs=[...changed].filter(f=>f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'));const missing=specs.filter(f=>{const t=f.replace(/\\.js$/,'.test.js');return!fs.existsSync(t)&&!changed.has(t);});if(missing.length){process.stdout.write(JSON.stringify({decision:'block',reason:'TESTS MISSING: '+missing.join(', ')+' — you must write tests before finishing. Use renderSync/render from @invisibleloop/pulse/testing to test view output, mutations, and any extracted logic functions. Run the tests with node to confirm they pass.\\n\\nEXCEPTION — waiting on the user: if you are ending this turn to wait for the user\\'s answer (e.g. the design-approval gate), call pulse_await_approval first, then ask and end your turn. Do not write tests or run /verify on an unapproved design.'}));}"`,
               statusMessage: 'Checking for missing tests...',
             },
             {
@@ -203,7 +217,7 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
             },
             {
               type: 'command',
-              command: `node -e "const fs=require('fs');const{execSync}=require('child_process');let specs=[];try{const out=execSync('git status --porcelain',{encoding:'utf8'});out.split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f&&f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'))specs.push(f);});}catch{if(fs.existsSync('src/pages'))for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))specs.push('src/pages/'+f);}}if(!specs.length)process.exit(0);const stamp='.pulse-verified';let stampMtime=0;try{stampMtime=fs.statSync(stamp).mtimeMs;}catch{}const stale=specs.filter(f=>{try{return fs.statSync(f).mtimeMs>stampMtime;}catch{return true;}});if(stale.length){process.stdout.write(JSON.stringify({decision:'block',reason:'VERIFY REQUIRED: These pages have not been verified since last edit:\\n'+stale.map(f=>'  '+f).join('\\n')+'\\n\\nRun /verify for each changed page. /verify runs Lighthouse (desktop + mobile), performance trace, console check, and code review — then writes the stamp that clears this check.'}));}"`,
+              command: `node -e "const fs=require('fs');if(fs.existsSync('.pulse-awaiting-approval'))process.exit(0);const{execSync}=require('child_process');let specs=[];try{const out=execSync('git status --porcelain',{encoding:'utf8'});out.split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f&&f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'))specs.push(f);});}catch{if(fs.existsSync('src/pages'))for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))specs.push('src/pages/'+f);}}if(!specs.length)process.exit(0);const stamp='.pulse-verified';let stampMtime=0;try{stampMtime=fs.statSync(stamp).mtimeMs;}catch{}const stale=specs.filter(f=>{try{return fs.statSync(f).mtimeMs>stampMtime;}catch{return true;}});if(stale.length){process.stdout.write(JSON.stringify({decision:'block',reason:'VERIFY REQUIRED: These pages have not been verified since last edit:\\n'+stale.map(f=>'  '+f).join('\\n')+'\\n\\nIMPORTANT — check first: are you ending this turn to wait for the user\\'s answer (e.g. the design-approval question)? If so, do NOT run /verify — the user has not approved the design yet. Call pulse_await_approval, re-ask your question, and end your turn; this gate will let you stop.\\n\\nOtherwise run /verify for each changed page. /verify runs Lighthouse (desktop + mobile), performance trace, console check, and code review — then writes the stamp that clears this check.'}));}"`,
               statusMessage: 'Checking verification stamp...',
             }
           ]
@@ -217,6 +231,8 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
     'node_modules',
     'public/dist',
     '.pulse-build',
+    '.pulse-verified',
+    '.pulse-awaiting-approval',
     '.DS_Store',
     '# Intake images — local design references, not committed',
     'public/intake/*.jpg',