@invisibleloop/pulse 0.17.1 → 0.17.2

package/.claude/commands/build-page.md

@@ -50,7 +50,7 @@ Check for:
 - Layout looks correct
 - No console errors via `mcp__chrome-devtools__list_console_messages`
 
-Then ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end. 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.
+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?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "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. 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.
 
 **Do not proceed to step 7 until the user explicitly confirms.** If they want changes, make them and return to step 6.
 

package/.claude/commands/verify.md

@@ -15,7 +15,7 @@ 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"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+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/.claude/pulse-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

package/CLAUDE.md

@@ -47,6 +47,8 @@ export const mySpec = {
     title:       'Page Title',
     description: 'Meta description',
     styles:      ['/pulse.css'],
+    theme:       'light',        // 'light' | 'dark' — ⚠ default is DARK when unset; decide at write time
+    vibe:        'minimal',      // optional preset: radius, weight, spacing
     ogTitle:     '...',
     ogImage:     '...',
   },
@@ -468,7 +470,7 @@ For any **new page, landing page, or branded site**, run this sequence first. Do
 3. pulse_intent(description)                  → archetype + scaffold + guide list
 ```
 
-**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, vibe, and anti-style if not mentioned.
+**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, **theme (light or dark — Pulse defaults to dark when unset)**, vibe, and anti-style if not mentioned.
 
 **`pulse_sketch` is mandatory** for `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes — those vibes fight the default centred-hero layout. Skip it only for `corporate` or `minimal` when no structural preference has been stated.
 

package/docs/.claude/pulse-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

package/docs/public/pulse-ui.css

@@ -4031,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/examples/.claude/pulse-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

package/examples/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));
@@ -3987,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -57,7 +57,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node src/mcp/mcp.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root docs --port 4000",
     "docs:start": "node docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.17.1
+0.17.2

package/public/pulse-ui.css

@@ -4031,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/scripts/build.js

@@ -20,6 +20,7 @@ import { createHash } from 'crypto'
 import { discoverPages } from '../src/cli/discover.js'
 import { renderToString } from '../src/runtime/ssr.js'
 import { c, header, table, ok, fail, info, warn, elapsed, icon } from '../src/cli/fmt.js'
+import { extractUsedClasses, purgeCss, minifyCss } from './css-purge.js'
 
 // ---------------------------------------------------------------------------
 // Server-only property stripping
@@ -783,207 +784,3 @@ async function purgeCssStep(pages, manifest, root, outDir) {
   fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
   return cssStats
 }
-
-// ---------------------------------------------------------------------------
-// CSS class extractor
-// ---------------------------------------------------------------------------
-
-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.
- * Returns [{ type, selector?, prelude?, inner?, raw }]
- */
-function parseCssBlocks(css) {
-  const blocks = []
-  let i = 0
-  const len = css.length
-
-  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
-      }
-      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.
- */
-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
-}
-
-/**
- * Purge unused CSS rules from a CSS string.
- * Recursively processes @media and @supports blocks.
- */
-function minifyCss(css) {
-  return css
-    .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()
-}
-
-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.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

package/src/agent/commands/verify.md

@@ -15,7 +15,7 @@ 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"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+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/guide-spec.md

@@ -16,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

@@ -53,7 +53,7 @@ Check for:
 - Layout looks correct
 - No console errors via list_console_messages
 
-Then ask the user: *"Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn 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.
+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
 

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

@@ -34,7 +34,7 @@ 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?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+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.
@@ -70,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
 
@@ -179,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">
@@ -242,8 +244,8 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 
 **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:
 
-- **Preferred:** ask the question with your host's question tool (e.g. AskUserQuestion in Claude Code). A question tool waits for the answer *without ending the turn*, so the Stop hooks never fire.
-- **Otherwise:** call `pulse_await_approval` immediately before asking in plain prose and ending your turn. It writes a one-turn marker the Stop hooks respect; the marker is consumed when the user replies.
+- **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:**
@@ -274,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/mcp/mcp.test.js

@@ -261,7 +261,61 @@ test('approval pause mechanism is wired end to end', () => {
 
   // 5. The workflow must teach the mechanism at the design-approval gate
   assert(workflow.includes('pulse_await_approval'),
-    'workflow.md Phase 5a must explain how to pause: host question tool preferred, pulse_await_approval otherwise')
+    'workflow.md Phase 5a must explain how to pause: always pulse_await_approval before asking')
+
+  // 6. No doc may claim a host question tool avoids ending the turn — field
+  //    testing showed AskUserQuestion in Claude Code still ends the turn and
+  //    fires the Stop hooks. The safe instruction is: always write the marker
+  //    first, regardless of how the question is asked.
+  const claimDocs = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /without ending the turn/i.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  if (/without ending the turn.*Stop hooks never fire/is.test(serverSrc)) claimDocs.push('src/mcp/server.js')
+  assert(claimDocs.length === 0,
+    `These docs claim a question tool avoids ending the turn (empirically false in Claude Code): ${claimDocs.join(', ')}. ` +
+    `Instruct: always call pulse_await_approval before asking, whichever way the question is asked.`)
+})
+
+test('pulse_check_contrast extracts variables from [data-theme="light"] blocks', () => {
+  // Regression: the light-theme block pattern was an ungrouped alternation
+  // (a|b) + '\\s*\\{([^}]+)\\}' — the body matcher bound only to the second
+  // alternative, so [data-theme="light"] blocks matched with no body capture
+  // and the checker silently reported nothing for the light theme.
+  // Recreate extractVars with the exact pattern strings from server.js source.
+  const patterns = [...serverSrc.matchAll(/extractVars\(source,\s*'((?:[^'\\]|\\.)*)'\)/g)].map(m =>
+    m[1].replace(/\\\\/g, '\\').replace(/\\'/g, "'")
+  )
+  assert(patterns.length === 2, `Expected 2 extractVars call patterns in server.js, found ${patterns.length}`)
+  const lightPattern = patterns.find(p => p.includes('data-theme'))
+  assert(lightPattern, 'No data-theme pattern found in extractVars calls')
+
+  const sampleCss = `:root { --accent: #112233; }\n[data-theme="light"] { --accent: #445566; --bg: #ffffff; }`
+  const blockRegex = new RegExp(lightPattern + '\\s*\\{([^}]+)\\}', 'gi')
+  const m = blockRegex.exec(sampleCss)
+  assert(m && m[1] && m[1].includes('--accent'),
+    `The light-theme block pattern in pulse_check_contrast fails to capture the block body. ` +
+    `Pattern: ${lightPattern} — alternations must be wrapped in (?:...).`)
+})
+
+test('dark theme default is declared at every spec-writing entry point', () => {
+  // Agents repeatedly assumed the default theme is light, built the page, then
+  // discovered dark at the screenshot — costing an edit → restart → re-approval
+  // cycle. The dark default must be stated wherever a spec is first written:
+  // the spec skeleton, the plan/build brief, and the checklist.
+  const guideSpec = fs.readFileSync(path.join(agentDir, 'guide-spec.md'), 'utf8')
+  const workflow  = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  const checklist = fs.readFileSync(path.join(agentDir, 'checklist.md'), 'utf8')
+  const claudeMd  = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8')
+
+  assert(/theme:/.test(guideSpec) && /DEFAULT IS DARK/i.test(guideSpec),
+    'guide-spec.md meta skeleton must include the theme field with the dark-default warning')
+  assert(/Theme:\s+light \| dark/.test(workflow),
+    'workflow.md build brief template must include a Theme line')
+  assert(/default theme is DARK/i.test(checklist),
+    'checklist.md Critical section must state the dark default')
+  assert(/theme:\s+'light'/.test(claudeMd) && /default is DARK/i.test(claudeMd),
+    'CLAUDE.md spec meta block must show theme with the dark-default warning')
 })
 
 test('identity.md declares the creative override (Design Freedom) carve-out', () => {

package/src/mcp/server.js

@@ -1210,11 +1210,11 @@ The stop hook compares each changed spec's mtime against this stamp. Any spec ne
 server.registerTool(
   'pulse_await_approval',
   {
-    description: `Pause the workflow to wait for the user's answer — call this immediately BEFORE ending your turn with a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
+    description: `Pause the workflow to wait for the user's answer — call this immediately BEFORE asking a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
 
-It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let this one turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn.
+It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let the turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn.
 
-**Prefer your host's question tool if it has one** (e.g. AskUserQuestion in Claude Code): a question tool waits for the answer *without ending the turn*, so the Stop hooks never fire and this marker is unnecessary. Use pulse_await_approval only when you must ask in plain prose and end the turn.
+**Always call this before the approval question, regardless of how you ask.** In some hosts (including Claude Code) even a dedicated question tool like AskUserQuestion ends the turn, which fires the Stop hooks. The marker is harmless if the turn does not end — it is simply consumed when the user replies. Calling it first works in every host; relying on the question tool to keep the turn open does not.
 
 Do NOT use this to skip verification — it buys exactly one turn-end, paired with a question the user must answer. Calling it without asking anything just delays the gates by one message.`,
     inputSchema: {},
@@ -2099,6 +2099,7 @@ Returns observations grouped by category: completeness, data flow, components, s
       if (!content.includes('title:'))       quickWins.push('`meta.title` is missing — every page needs a unique title.')
       if (!content.includes('description:')) quickWins.push('`meta.description` is missing — used for SEO and social previews.')
       if (!content.includes('styles:'))      quickWins.push('`meta.styles` not set — add `[\'/pulse-ui.css\']` if you are using any UI components.')
+      if (!content.includes('theme:'))       quickWins.push('`meta.theme` not set — Pulse renders DARK by default. If this design is light, add `theme: \'light\'` now rather than discovering a dark page at the screenshot.')
     }
 
     // --- Export ---
@@ -2432,7 +2433,7 @@ Accepts antiStyle ("what should this NOT look like?") and inspiration (a site or
       targetUser: z.string().optional().describe('Who this is for — shapes copy tone. E.g. "busy professionals", "indie developers", "home cooks"'),
       palette:    z.string().optional().describe('Brand colours as hex values, comma-separated. E.g. "#6366f1, #f8fafc, #1e1b4b". Used for early contrast check.'),
       font:       z.string().optional().describe('Brand font name, or omit for system-ui'),
-      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme preference'),
+      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme — ALWAYS ask the user for this; Pulse renders DARK when meta.theme is unset, so an unstated light design ships dark and costs a rework cycle. Pass the answer through to meta.theme in the spec.'),
       vibe:       z.enum(['warm', 'editorial', 'playful', 'minimal', 'bold', 'brutalist', 'retro', 'corporate', 'neon', 'paper']).optional().describe('Visual personality — see pulse://guide/design-references for full descriptions. warm (rounded, inviting), editorial (serif, sharp), playful (very rounded), minimal (clean), bold (impact headings), brutalist (zero radius, raw), retro (slab serif, nostalgic), corporate (conservative), neon (monospace, futuristic), paper (organic, serif, journal)'),
       styleNotes: z.string().optional().describe('Free-form style direction — e.g. "like a print poster", "market stall chalkboard feel", "clinical and professional"'),
       antiStyle:  z.string().optional().describe('"What should this NOT look like?" — negative aesthetic constraint. E.g. "not corporate SaaS", "not another Vercel dark card page", "not a startup landing page". Used to steer component and layout choices away from over-used patterns.'),
@@ -2997,6 +2998,78 @@ Returns tokens grouped by category.`,
   }
 )
 
+server.registerTool(
+  'pulse_check_csp',
+  {
+    description: `Resolve the redirect chains of external asset URLs (images, fonts, stylesheets) and return the complete set of origins your CSP must allow — as ready-to-paste config.
+
+Many asset hosts redirect to a CDN origin (picsum.photos → fastly.picsum.photos): allowing only the URL you wrote still blocks the actual bytes, and the browser error names the CDN origin, which is confusing to debug. This tool follows each redirect chain (up to 5 hops) and reports every origin involved.
+
+Call it with the external URLs you plan to use, before your first Lighthouse run. Suggested directive: img-src for images, font-src for font files, style-src for stylesheets.`,
+    inputSchema: {
+      urls:      z.array(z.string()).describe('External asset URLs to check, e.g. ["https://picsum.photos/id/10/1200/600"]'),
+      directive: z.string().optional().describe("CSP directive these assets belong to (default: 'img-src')"),
+    },
+  },
+  async ({ urls, directive = 'img-src' }) => {
+    const MAX_HOPS = 5
+    const origins  = new Set()
+    const lines    = []
+
+    for (const rawUrl of urls.slice(0, 10)) {
+      let url
+      try { url = new URL(rawUrl) } catch { lines.push(`✗ ${rawUrl} — not a valid URL`); continue }
+
+      const chain = [url.origin]
+      let blocked = null
+      try {
+        for (let hop = 0; hop < MAX_HOPS; hop++) {
+          const res = await fetch(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(5000) })
+          if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+            url = new URL(res.headers.get('location'), url)
+            chain.push(url.origin)
+            continue
+          }
+          if (res.status === 405) {
+            // Host rejects HEAD — confirm with a ranged GET so we still see redirects
+            const get = await fetch(url, { method: 'GET', redirect: 'manual', headers: { Range: 'bytes=0-0' }, signal: AbortSignal.timeout(5000) })
+            if (get.status >= 300 && get.status < 400 && get.headers.get('location')) {
+              url = new URL(get.headers.get('location'), url)
+              chain.push(url.origin)
+              continue
+            }
+          }
+          break
+        }
+      } catch (err) {
+        blocked = err?.name === 'TimeoutError' ? 'timed out' : (err?.message || 'request failed')
+      }
+
+      const uniqueChain = [...new Set(chain)]
+      for (const o of uniqueChain) origins.add(o)
+      lines.push(
+        blocked
+          ? `⚠ ${rawUrl} — ${blocked}; allowing origin from the URL only: ${uniqueChain.join(' → ')}`
+          : uniqueChain.length > 1
+            ? `↪ ${rawUrl} — redirects: ${uniqueChain.join(' → ')} (allow ALL of these)`
+            : `✓ ${rawUrl} — no redirect, origin: ${uniqueChain[0]}`
+      )
+    }
+
+    const config = [...origins].map(o => `'${o}'`).join(', ')
+    lines.push('')
+    lines.push('Ready to paste:')
+    lines.push('```js')
+    lines.push(`csp: {`)
+    lines.push(`  '${directive}': [${[...origins].map(o => `'${o}'`).join(', ')}],`)
+    lines.push(`}`)
+    lines.push('```')
+    if (config.includes('http://')) lines.push('⚠ An origin resolved to plain http: — use https URLs in production.')
+
+    return text(lines.join('\n'))
+  }
+)
+
 server.registerTool(
   'pulse_check_contrast',
   {
@@ -3036,8 +3109,12 @@ Run this immediately after writing a theme file — before production build and
       return vars
     }
 
+    // NOTE: alternations must be wrapped in a non-capturing group. An ungrouped
+    // pattern (a|b) followed by '\\s*\\{...' binds the body matcher to the second
+    // alternative only — [data-theme="light"] blocks then match the selector
+    // alone with no body capture, silently returning zero variables.
     const rootVars  = extractVars(source, ':root')
-    const lightVars = extractVars(source, '\\[data-theme=["\']light["\']\\]|[.]ui-theme-light')
+    const lightVars = extractVars(source, '(?:\\[data-theme=["\']light["\']\\]|[.]ui-theme-light)')
 
     // pulse-ui.css maps --NAME → --ui-NAME (e.g. --accent → --ui-accent).
     // Theme files written per the guide define bare --* tokens. Synthesize the

package/src/ui/drop-cap.js

@@ -24,6 +24,6 @@ export function dropCap({
   const classes = ['ui-drop-cap', cls].filter(Boolean).join(' ')
   
   return `<p class="${e(classes)}">
-  <span class="ui-drop-cap-letter" style="float:left;font-size:${lines * 1.2}em;line-height:${lines * 0.8};margin-right:0.1em" aria-hidden="true">${e(letter)}</span>${e(content)}
+  <span class="ui-drop-cap-letter" style="font-size:${+(lines * 1.2).toFixed(2)}em" aria-hidden="true">${e(letter)}</span>${e(content)}
 </p>`
 }

package/src/ui/gallery.js

@@ -11,6 +11,9 @@
  * @param {'sm'|'md'|'lg'} opts.gap - Gap between images (default: 'md')
  * @param {boolean} opts.rounded  - Rounded corners on images
  * @param {string}  opts.ratio    - CSS aspect-ratio for grid/strip cells e.g. '4/3', '1/1', '16/9'
+ * @param {boolean} opts.lazy     - loading="lazy" on images (default: true). Set false for
+ *                                  above-the-fold galleries or when full-page screenshots
+ *                                  during development need every image rendered eagerly.
  * @param {string}  opts.class
  */
 
@@ -26,6 +29,7 @@ export function gallery({
   gap     = 'md',
   rounded = false,
   ratio   = '4/3',
+  lazy    = true,
   class: cls = '',
 } = {}) {
   if (!LAYOUTS.has(layout)) layout = 'grid'
@@ -42,7 +46,7 @@ export function gallery({
   ].filter(Boolean).join(' ')
 
   const items = images.map(img => {
-    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img" loading="lazy" decoding="async">`
+    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img"${lazy ? ' loading="lazy"' : ''} decoding="async">`
     const cap    = img.caption ? `<figcaption class="ui-gallery-caption">${e(img.caption)}</figcaption>` : ''
     const inner  = img.href
       ? `<a href="${e(img.href)}" class="ui-gallery-link">${imgTag}</a>`

package/src/ui/ui.test.js

@@ -25,6 +25,8 @@ import { pricing }     from './pricing.js'
 import { accordion }   from './accordion.js'
 import { nav }         from './nav.js'
 import { appBadge }    from './app-badge.js'
+import { dropCap }     from './drop-cap.js'
+import { gallery }     from './gallery.js'
 import { container }   from './container.js'
 import { section }     from './section.js'
 import { grid }        from './grid.js'
@@ -1319,4 +1321,36 @@ test('uiImage: escapes src to prevent XSS', () => {
   assert.doesNotMatch(html, /<script>/)
 })
 
+test('dropCap: inline style carries only the dynamic font-size — alignment lives in CSS', () => {
+  // Regression: a relative inline line-height (lines * 0.8 → 2.4 for 3 lines)
+  // made the float box ~3x the glyph height, so serif caps floated below the
+  // opening line instead of top-aligning. line-height/float/margin now live in
+  // .ui-drop-cap-letter (pulse-ui.css) with a fixed ~cap-height value.
+  const html = dropCap({ letter: 'O', content: 'nce upon a time.' })
+  assert.match(html, /class="ui-drop-cap-letter"/)
+  assert.match(html, /style="font-size:3\.6em"/)
+  assert.doesNotMatch(html, /line-height/)
+  assert.doesNotMatch(html, /float:left/)
+})
+
+test('dropCap: lines option scales the font-size', () => {
+  const html = dropCap({ letter: 'O', content: 'nce.', lines: 5 })
+  assert.match(html, /style="font-size:6em"/)
+})
+
+test('gallery: images are lazy by default', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }] })
+  assert.match(html, /loading="lazy"/)
+})
+
+test('gallery: lazy:false renders eager images', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }], lazy: false })
+  assert.doesNotMatch(html, /loading="lazy"/)
+})
+
+test('dropCap: escapes letter and content', () => {
+  const html = dropCap({ letter: '<', content: '<script>alert(1)</script>' })
+  assert.doesNotMatch(html, /<script>/)
+})
+
 console.log('✓ All UI component tests passed')