@invisibleloop/pulse 0.20.1 → 0.20.3

package/scripts/css-purge.js

@@ -12,9 +12,9 @@
 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
+  // Extract from class="..." in rendered HTML (no template expressions to worry about)
+  for (const content of htmlContents) {
+    const re = /class=["']([^"'\n]+)["']/g
     let m
     while ((m = re.exec(content)) !== null) {
       for (const cls of m[1].trim().split(/\s+/)) {
@@ -23,6 +23,41 @@ export function extractUsedClasses(htmlContents, jsContents, safelist = []) {
     }
   }
 
+  // Extract from class= attributes in JS source. Template literal class attributes
+  // like class="foo${expr ? ' bar' : ''}" have their expressions interrupted by
+  // single quotes inside the ternary, so [^"'\n]+ stops mid-expression and misses
+  // the base class. Instead: scan for class= followed by a double-quoted string
+  // OR a backtick-delimited segment, extract everything up to the first ${ or the
+  // closing delimiter, and tokenise only the static prefix.
+  for (const js of jsContents) {
+    // Match class="...anything up to closing quote or ${..."
+    // Using a two-pass approach: find class= then manually scan to get the static part
+    let i = 0
+    while (i < js.length) {
+      const idx = js.indexOf('class=', i)
+      if (idx === -1) break
+      i = idx + 6 // past 'class='
+
+      // Skip optional whitespace (shouldn't be any but be safe)
+      while (i < js.length && (js[i] === ' ' || js[i] === '\t')) i++
+
+      const quote = js[i]
+      if (quote !== '"' && quote !== "'" && quote !== '`') continue
+      i++ // past opening quote
+
+      // Collect characters until we hit the closing quote, a ${, or end of string
+      let staticPart = ''
+      while (i < js.length && js[i] !== quote && !(js[i] === '$' && js[i + 1] === '{')) {
+        staticPart += js[i++]
+      }
+
+      // Tokenise the static prefix
+      for (const cls of staticPart.trim().split(/\s+/)) {
+        if (cls && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(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) {
@@ -50,6 +85,33 @@ export function extractUsedClasses(htmlContents, jsContents, safelist = []) {
     }
   }
 
+  // Pulse re-renders via innerHTML — classes added after mutations appear as
+  // template literal expressions inside class= attributes, not classList calls.
+  // Pattern: class="${state.x ? 'foo' : 'bar'}" or class="base ${state.x ? 'active' : ''}"
+  // The hyphen-only scan above misses single-word classes like 'active', 'open',
+  // 'visible', 'selected', 'hidden' that are common state-driven class names.
+  // Extract every quoted string that appears inside a class= template expression.
+  for (const js of jsContents) {
+    // Match: class=`...` or class="${...}" template attribute values
+    const attrRe = /class(?:Name)?=`([^`]*)`/g
+    let m
+    while ((m = attrRe.exec(js)) !== null) {
+      const attrContent = m[1]
+      // Collect static class tokens (outside ${...} expressions)
+      for (const cls of attrContent.replace(/\$\{[^}]*\}/g, ' ').trim().split(/\s+/)) {
+        if (cls && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(cls)) used.add(cls)
+      }
+      // Collect quoted strings inside ${...} expressions — these are the
+      // conditional class names: ${state.open ? 'open' : ''} → 'open'
+      for (const [, inner] of attrContent.matchAll(/\$\{([^}]*)\}/g)) {
+        for (const [, cls] of inner.matchAll(/['"]([a-zA-Z][a-zA-Z0-9_-]*)['"]|`([a-zA-Z][a-zA-Z0-9_-]*)`/g)) {
+          const name = cls
+          if (name && /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) used.add(name)
+        }
+      }
+    }
+  }
+
   // 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

package/scripts/css-purge.test.js

@@ -119,6 +119,22 @@ test('multiple classList arguments in one call are all collected', () => {
   for (const cls of ['one', 'two-x', 'three']) assert.ok(used.has(cls), cls)
 })
 
+// Regression: class name immediately followed by ${ (no space before the expression)
+// was not extracted — "saved-palette${...}" yielded "saved-palette${expanded" as a
+// single token, so the rule was silently purged in prod while dev (no purging) looked fine.
+test('class name immediately before ${ is extracted correctly', () => {
+  const js = [
+    // No space before ${ — the broken pattern
+    `const v = \`<div class="saved-palette\${expanded ? ' saved-palette--expanded' : ''}"></div>\``,
+    // Multiple static classes, last one butts into ${
+    `const v = \`<button class="btn btn--primary\${loading ? ' btn--loading' : ''}"></button>\``,
+  ]
+  const used = extractUsedClasses([], js)
+  for (const cls of ['saved-palette', 'btn', 'btn--primary']) {
+    assert.ok(used.has(cls), `Expected "${cls}" to be extracted but it was missing`)
+  }
+})
+
 test('runtime-toggled compound rule survives the purge', () => {
   const css = `.docs-sidebar { transform: translateX(-100%); }\n.docs-sidebar.open { transform: translateX(0); }\n.unused { color: red; }`
   const used = extractUsedClasses(

package/scripts/strip-server.test.js

@@ -8,7 +8,7 @@
 // ---------------------------------------------------------------------------
 
 const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render', 'sitemap']
-const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
+const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md', '@invisibleloop/pulse']
 
 function stripServerOnlyKeys(source) {
   for (const key of SERVER_ONLY_KEYS) source = removeObjectKey(source, key)
@@ -415,6 +415,16 @@ test('store definition: server fetchers stripped, state and mutations survive',
   `export default {\n  state: { basket: [] },\n  mutations: {\n    add: (store, item) => ({ basket: [...store.basket, item] }),\n  },\n}`
 )
 
+test('package-root import (pushStore) is stripped — the root export is the server itself',
+  `import { pushStore } from '@invisibleloop/pulse'\nexport default {\n  route: '/staff',\n  view: () => '',\n}`,
+  `export default {\n  route: '/staff',\n  view: () => '',\n}`
+)
+
+test('subpath imports (/ui) are NOT stripped by the root entry',
+  `import { button } from '@invisibleloop/pulse/ui'\nexport default {\n  route: '/x',\n  view: () => button({ label: 'x' }),\n}`,
+  `import { button } from '@invisibleloop/pulse/ui'\nexport default {\n  route: '/x',\n  view: () => button({ label: 'x' }),\n}`
+)
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)

package/src/agent/commands/pulse-start.md

@@ -1,9 +1,11 @@
-Start the Pulse production server for this project.
+Start the Pulse production server for this project — **locally, on the production port (dev port + 1, normally 3001)** so it can run alongside the dev server on 3000.
 
-First ensure a build exists (`public/dist/`). Then run:
+First ensure a build exists (`public/dist/` — run `pulse build` if not). Then:
 
 ```bash
-pulse start
+pulse start --port 3001
 ```
 
-The production server uses the port from `pulse.config.js` (defaults to 3000).
+If `pulse.config.js` sets a custom `port`, use that value + 1 instead.
+
+> **Why the flag:** plain `pulse start` binds the configured port (3000) because in real deployment it is the only server and platforms inject `PORT`. Locally that collides with the dev server and breaks the convention used by `pulse_build`, Lighthouse, and the performance trace — production is always dev port + 1. Never use `--port` in actual deployment.

package/src/agent/commands/pulse-stop.md

@@ -1,4 +1,4 @@
-Stop the Pulse dev server for this project.
+Stop the Pulse servers for this project — both the dev server (port 3000) and the local production server (port 3001, started by `pulse_build` or `/pulse-start`).
 
 ```bash
 pulse stop

package/src/agent/commands/verify.md

@@ -1,12 +1,18 @@
 # Verify
 
-Run the full verification loop on the current page or the page specified in $ARGUMENTS.
+Run the verification loop on the current page or the page specified in $ARGUMENTS.
+
+**Modes:**
+- `/verify` — full loop including Lighthouse (desktop + mobile), perf trace, and mobile layout check. Use when the user approves the design or signals they're ready to ship.
+- `/verify --quick` — skips Lighthouse and perf trace; just validate → screenshot → console → review → stamp. Use during iterative building: design rounds, debugging visual issues, mid-build checkpoints. Fast enough to run between every change.
+
+If `--quick` appears anywhere in $ARGUMENTS, run in quick mode (steps 6, 7, 8, and 9 are skipped). The route/file path is whatever remains in $ARGUMENTS after removing `--quick`.
 
 ## Steps
 
 ### 1. Identify the target
 
-If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context.
+If $ARGUMENTS is provided, use it (minus `--quick` if present) as the file path or route. Otherwise, identify the most recently edited spec file from context.
 
 ### 2. Design approval (new builds only)
 
@@ -30,7 +36,7 @@ Use `pulse_fetch_page` to confirm the server is responding for the route. If it
 
 Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chrome-devtools__take_screenshot` to capture the result. Describe what you see — layout, content, any obvious rendering issues.
 
-### 6. Lighthouse — desktop
+### 6. Lighthouse — desktop *(skip in quick mode)*
 
 **Pre-flight (required before every Lighthouse run):**
 1. Call `pulse_build` to produce a production build and start the production server on port 3001.
@@ -40,7 +46,7 @@ Then run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "desktop" }`
 
 **Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is measured and reported but is not a hard requirement (it varies with machine load). Report the actual scores. If Accessibility, Best Practices, or SEO is below 100, identify the failing audit(s), fix the issue, and restart from step 3.
 
-### 7. Lighthouse — mobile
+### 7. Lighthouse — mobile *(skip in quick mode)*
 
 The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "mobile" }`.
 
@@ -48,7 +54,7 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 **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
+### 8. Mobile layout check *(skip in quick mode)*
 
 Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and layout issues before they become Lighthouse failures.
 
@@ -70,7 +76,7 @@ Fix any issues, then reset to desktop before continuing:
 mcp__chrome-devtools__emulate  viewport: "1440x900x1"
 ```
 
-### 9. Performance
+### 9. Performance *(skip in quick mode)*
 
 **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.).
 
@@ -102,11 +108,11 @@ Call `pulse_stamp`. This writes `.pulse-verified` via the MCP server, which is m
 
 Summarise:
 - Validation: pass or fail (with errors if any)
-- Visual: desktop screenshot and mobile layout check — any issues found and fixed
-- Lighthouse desktop: scores for Accessibility, Best Practices, SEO
-- Lighthouse mobile: scores for Accessibility, Best Practices, SEO
-- Performance: LCP and CLS values, any flagged insights
+- Visual: desktop screenshot — any issues found and fixed
 - Console: any errors
 - Review: pass or issues found and fixed
+- **Full mode only:** Lighthouse desktop/mobile scores, mobile layout check, LCP and CLS values
+
+In quick mode, end with: "Quick check passed — run `/verify` when you're ready for the full Lighthouse audit."
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+In full mode, only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.

package/src/agent/coverage-check.js

@@ -4,92 +4,59 @@
  *
  * Called by the Stop hook in .claude/settings.json to enforce test coverage.
  * Runs `npm run test:coverage` and blocks the agent if any src/pages/ file
- * has uncovered lines — except async action run() and server fetcher functions
- * which cannot be tested without mocking real APIs.
+ * has uncovered lines — except code that cannot be unit-tested without mocking
+ * real APIs:
+ *
+ *   - server fetchers (`server:` blocks) and store fetchers
+ *   - action `run:` functions
+ *   - `guard:`, `submit:`, and `sitemap:` handlers
+ *   - `meta:` blocks (async meta functions hit real data sources)
+ *
+ * Also honours c8-style ignore comments, which Node's built-in coverage
+ * (--experimental-test-coverage) does NOT support natively. In a block or line
+ * comment, write:
+ *
+ *   "c8 ignore next"      — exempts the following line
+ *   "c8 ignore next 3"    — exempts the following 3 lines
+ *   "c8 ignore start" ... "c8 ignore stop"  — exempts the range
+ *   ("coverage-ignore" works as a synonym for "c8 ignore")
  *
  * Outputs a Claude Code hook JSON decision to stdout.
  */
 
 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)) {
-    const p = `${d}/${f}`
-    if (fs.statSync(p).isDirectory()) { if (scan(p)) return true }
-    else if (f.endsWith('.test.js')) return true
-  }
-  return false
-})('src/pages')
-
-if (!hasTests) process.exit(0)
-
-let out = ''
-try {
-  out = execSync('npm run test:coverage 2>&1', { encoding: 'utf8', timeout: 60000 })
-} catch (e) {
-  out = e.stdout || e.message
-}
-
-// Parse the coverage report — look for lines with uncovered line numbers
-const lines = out.split('\n')
-let inReport = false
-const rawGaps = []
-
-for (const line of lines) {
-  if (line.includes('start of coverage report')) { inReport = true; continue }
-  if (!inReport) continue
-
-  // Match: #  filename.js | line% | branch% | func% | 30-36 50
-  const m = line.match(/^[#ℹ]\s+([\w./[\]-]+\.js)\s*\|\s*[\d.]+\s*\|\s*[\d.]+\s*\|\s*[\d.]+\s*\|\s*([^|\n]+)$/)
-  if (m) {
-    const uncov = m[2].trim()
-    if (uncov && uncov !== 'uncovered lines') {
-      rawGaps.push({ file: m[1].trim(), uncovered: uncov })
-    }
-  }
-}
+import { pathToFileURL } from 'url'
+
+// Property blocks that are exempt — all server-side-only code paths that call
+// real external APIs and cannot run in unit tests.
+const EXEMPT_BLOCK_STARTS = [
+  /^server\s*:/,
+  /^run\s*:/, /^run\s*\(/,
+  /^guard\s*:/,
+  /^submit\s*:/,
+  /^sitemap\s*:/,
+  /^meta\s*:/,
+]
 
 /**
- * Returns true if all uncovered line numbers in the given file fall inside
- * a `server:` property block or an action `run:` function — both of which
- * call real external APIs and are explicitly exempt from coverage requirements.
+ * Build the set of exempt (1-based) line numbers for a source string:
+ * lines inside exempt property blocks, plus c8-ignore-annotated lines.
+ *
+ * @param {string} src
+ * @returns {Set<number>}
  */
-function allLinesExempt(filePath, uncoveredSpec) {
-  let src
-  try { src = fs.readFileSync(filePath, 'utf8') } catch { return false }
+export function computeExemptLines(src) {
   const srcLines = src.split('\n')
-
-  // Expand "30-36 50" → [30, 31, 32, 33, 34, 35, 36, 50]
-  const lineNums = []
-  for (const part of uncoveredSpec.split(/\s+/)) {
-    const range = part.match(/^(\d+)-(\d+)$/)
-    if (range) {
-      for (let i = parseInt(range[1]); i <= parseInt(range[2]); i++) lineNums.push(i)
-    } else if (/^\d+$/.test(part)) {
-      lineNums.push(parseInt(part))
-    }
-  }
-
-  // Build a set of exempt line numbers: lines inside `server:` blocks or action `run:` functions.
-  // Strategy: scan the source tracking brace depth relative to the start of each exempt block.
   const exemptLines = new Set()
+
+  // 1. Exempt property blocks — scan tracking brace/paren depth from block start
   let i = 0
   while (i < srcLines.length) {
     const trimmed = srcLines[i].trimStart()
-    // Detect start of `server:` property or action `run:` function
-    const isExemptStart = /^server\s*:/.test(trimmed) || /^run\s*:/.test(trimmed) || /^run\s*\(/.test(trimmed)
-    if (isExemptStart) {
-      // Mark lines from here until the block closes (depth reaches 0 after opening)
+    if (EXEMPT_BLOCK_STARTS.some(re => re.test(trimmed))) {
       let depth = 0
       let started = false
-      const startLine = i
       while (i < srcLines.length) {
         exemptLines.add(i + 1) // 1-based
         for (const ch of srcLines[i]) {
@@ -103,30 +70,127 @@ function allLinesExempt(filePath, uncoveredSpec) {
     i++
   }
 
-  return lineNums.every(n => exemptLines.has(n))
+  // 2. c8-style ignore comments (Node's built-in coverage ignores these, so we
+  //    honour them here — the marker line itself is always exempt too)
+  const IGNORE = /(?:c8 ignore|coverage-ignore)(?:\s+(next|start|stop))?(?:\s+(\d+))?/
+  let rangeOpen = false
+  for (let n = 0; n < srcLines.length; n++) {
+    if (rangeOpen) exemptLines.add(n + 1)
+    const m = srcLines[n].match(IGNORE)
+    if (!m) continue
+    exemptLines.add(n + 1)
+    const keyword = m[1]
+    if (keyword === 'start') { rangeOpen = true; continue }
+    if (keyword === 'stop')  { rangeOpen = false; continue }
+    // 'next' (or bare marker) — exempt the following N lines (default 1)
+    const count = m[2] ? parseInt(m[2], 10) : 1
+    for (let k = 1; k <= count; k++) exemptLines.add(n + 1 + k)
+  }
+
+  return exemptLines
 }
 
-const gaps = []
-for (const { file, uncovered } of rawGaps) {
-  // Try to resolve relative to cwd (coverage reports use relative paths)
-  const candidates = [file, `src/pages/${file}`, file.replace(/^.*src\/pages\//, 'src/pages/')]
-  const resolved   = candidates.find(p => fs.existsSync(p))
+/**
+ * Returns true if all uncovered line numbers fall on exempt lines.
+ *
+ * @param {string} filePath
+ * @param {string} uncoveredSpec - e.g. "30-36 50"
+ * @returns {boolean}
+ */
+export function allLinesExempt(filePath, uncoveredSpec) {
+  let src
+  try { src = fs.readFileSync(filePath, 'utf8') } catch { return false }
+
+  // Expand "30-36 50" → [30, 31, 32, 33, 34, 35, 36, 50]
+  const lineNums = []
+  for (const part of uncoveredSpec.split(/\s+/)) {
+    const range = part.match(/^(\d+)-(\d+)$/)
+    if (range) {
+      for (let i = parseInt(range[1]); i <= parseInt(range[2]); i++) lineNums.push(i)
+    } else if (/^\d+$/.test(part)) {
+      lineNums.push(parseInt(part))
+    }
+  }
+
+  const exemptLines = computeExemptLines(src)
+  return lineNums.every(n => exemptLines.has(n))
+}
 
-  if (resolved && allLinesExempt(resolved, uncovered)) continue  // auto-exempt
+// ---------------------------------------------------------------------------
+// Main — only when executed directly (the exports above are unit-tested)
+// ---------------------------------------------------------------------------
 
-  gaps.push(`  ${file} — uncovered lines: ${uncovered}`)
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main()
 }
 
-if (gaps.length) {
-  process.stdout.write(JSON.stringify({
-    decision: 'block',
-    reason: [
-      'COVERAGE GAPS detected. Add tests for these uncovered lines before finishing:',
-      ...gaps,
-      '',
-      'Run `npm run test:coverage` to see the full report.',
-      'Exempt from this rule: async action run() functions and server fetchers that call real APIs.',
-      'Everything else — view branches, mutations, onViewError, pure helper functions — must be covered.',
-    ].join('\n'),
-  }))
+function main() {
+  // Agent is ending its turn to wait for the user's answer (approval gate or a
+  // mid-flow pause) — 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)) {
+      const p = `${d}/${f}`
+      if (fs.statSync(p).isDirectory()) { if (scan(p)) return true }
+      else if (f.endsWith('.test.js')) return true
+    }
+    return false
+  })('src/pages')
+
+  if (!hasTests) process.exit(0)
+
+  let out = ''
+  try {
+    out = execSync('npm run test:coverage 2>&1', { encoding: 'utf8', timeout: 60000 })
+  } catch (e) {
+    out = e.stdout || e.message
+  }
+
+  // Parse the coverage report — look for lines with uncovered line numbers
+  const lines = out.split('\n')
+  let inReport = false
+  const rawGaps = []
+
+  for (const line of lines) {
+    if (line.includes('start of coverage report')) { inReport = true; continue }
+    if (!inReport) continue
+
+    // Match: #  filename.js | line% | branch% | func% | 30-36 50
+    const m = line.match(/^[#ℹ]\s+([\w./[\]-]+\.js)\s*\|\s*[\d.]+\s*\|\s*[\d.]+\s*\|\s*[\d.]+\s*\|\s*([^|\n]+)$/)
+    if (m) {
+      const uncov = m[2].trim()
+      if (uncov && uncov !== 'uncovered lines') {
+        rawGaps.push({ file: m[1].trim(), uncovered: uncov })
+      }
+    }
+  }
+
+  const gaps = []
+  for (const { file, uncovered } of rawGaps) {
+    // Try to resolve relative to cwd (coverage reports use relative paths)
+    const candidates = [file, `src/pages/${file}`, file.replace(/^.*src\/pages\//, 'src/pages/')]
+    const resolved   = candidates.find(p => fs.existsSync(p))
+
+    if (resolved && allLinesExempt(resolved, uncovered)) continue  // auto-exempt
+
+    gaps.push(`  ${file} — uncovered lines: ${uncovered}`)
+  }
+
+  if (gaps.length) {
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: [
+        'COVERAGE GAPS detected. Add tests for these uncovered lines before finishing:',
+        ...gaps,
+        '',
+        'Run `npm run test:coverage` to see the full report.',
+        'Auto-exempt: server fetchers, action run(), guard, submit, sitemap, and meta blocks — these call real APIs and need no tests.',
+        'For anything else that genuinely cannot be tested, annotate it: /* c8 ignore next */ (or next N, or start/stop for a range) — this hook honours those comments even though Node\'s built-in coverage does not.',
+        'Everything else — view branches, mutations, onViewError, pure helper functions — must be covered.',
+      ].join('\n'),
+    }))
+  }
 }

package/src/agent/guide-components.md

@@ -194,7 +194,7 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 | `list` | `items` (array of HTML strings), `ordered`, `gap` (xs/sm/md) |
 | `prose` | `content` (raw HTML — not escaped), `size` (sm/base/lg) — for CMS/markdown content you don't control |
 
-**Never write raw `<h1>`–`<h6>` or `<ul>`/`<ol>` without styling.** Use `heading()` and `list()` instead.
+**Never write raw `<h1>`–`<h6>` or `<ul>`/`<ol>` without styling.** Use `heading()` and `list()` instead. *(Mode A only — in a creative override, raw headings styled directly with utility classes or custom CSS are correct. The `heading()` component adds wrapper markup that can fight custom layouts.)*
 
 **Heading order across components.** `card`, `feature`, `section`, `pricing`, `cta`, and `modal` all accept a `level` prop. Use it to keep the document outline correct without changing visual style. For example, if a page has an h2 section title and each card inside it has a title, pass `level: 3` on the cards (the default) — but if the cards are the first heading on the page, pass `level: 2`. The CSS class stays the same (`ui-card-title` etc.) so appearance is unaffected.
 
@@ -284,7 +284,7 @@ This is by design: vibes are a paint job, not a structural transformation. Compo
 
 | Component | Key props |
 |-----------|-----------|
-| `nav` | `logo` (HTML slot), `logoHref`, `links` ([{label,href}]), `action` (HTML slot), `sticky`, `background` (any CSS value — overrides default surface colour), `color` (foreground colour — set when custom background doesn't contrast with default muted text) |
+| `nav` | `logo` (HTML slot), `logoHref`, `links` ([{label,href}]), `action` (HTML slot), `sticky`, `background` (any CSS value — overrides default surface colour), `color` (foreground colour — set when custom background doesn't contrast with default muted text) — ⚠ **renders a `<nav>` landmark internally. Never wrap it in another `<nav>` or `<header><nav>` — that creates a duplicate landmark Lighthouse flags as an accessibility failure. Wrapping in `<header>` alone is fine.** |
 | `hero` | `eyebrow`, `title`, `subtitle`, `actions` (HTML slot), `image` (HTML slot — activates image layout), `imageAlign` (right/left), `align` (center/left), `size` (md/sm), `layout` (split/asymmetric/overlap — when image provided: 'split'=50/50, 'asymmetric'=60/40 text-heavy, 'overlap'=image fills section with text overlay), `gradient` (true/false or preset: 'purple'\|'blue'\|'green'\|'rose'\|'orange'), `background` (any CSS value), `eyebrowColor` |
 | `phoneFrame` | `content` (HTML slot — rendered inside the phone screen), `animate` (boolean, default `false` — enables a gentle 3-D tilt on hover). Pure CSS phone mockup with dynamic island, side buttons, home indicator. Use as the `image` slot in `hero()` for app landing pages. Add `animate: true` whenever the phone is a prominent hero element. |
 | `feature` | `image` (HTML slot — rendered above icon), `icon` (HTML slot), `title`, `level` (1–6, default 3), `description` (or `body` as alias), `center` |

package/src/agent/identity.md

@@ -44,8 +44,8 @@ The component rules marked *(Mode A)* below are suspended under a declared creat
 - Hardcode hex colours in CSS. Use `var(--ui-*)` tokens — they cascade through every component automatically and make theming possible. The one place hex values belong is `public/theme.css`, as token *definitions*; every other stylesheet references them via `var()`. A lint hook enforces this.
 - Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet. *Exception:* structural image styles with no utility-class equivalent (`aspect-ratio`, `object-fit`) are permitted inline — these are layout facts, not theming, and the design gallery uses them this way.
 - Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions. *(Mode A — under a creative override, functional atoms should still come from components unless there is a specific design reason.)*
-- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead. *(Mode A)*
-- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead. *(Mode A)*
+- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead. *(Mode A — under a creative override, raw headings styled with utility classes or custom CSS are correct; `heading()` adds wrapper markup that fights custom layouts.)*
+- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead. *(Mode A — under a creative override, raw lists are permitted when the component markup would interfere with the layout.)*
 - Output CMS or database HTML without a `prose()` wrapper. Raw HTML from external sources has no styling — always wrap it in `prose({ content: html })`.
 - Use `data-event` on text inputs. Re-rendering on every keystroke destroys focus. Use uncontrolled inputs and read values from `FormData` in `action.onStart` or `action.run`.
 - Skip `onError` in an action. It is required. Always handle failure.

package/src/agent/workflow.md

@@ -9,9 +9,10 @@
 | New site, new branded page, or "build me X from scratch" | `pulse_intake` → `pulse_sketch` → `pulse_intent` → build |
 | Editing an existing page, adding a section, fixing a bug | Go straight to Step 1 — Understand |
 | "Add X to the existing Y" (one-liner) | Read the relevant file, make the change, run `/verify` |
+| Iterating on design before user approves | `/verify --quick` between rounds; full `/verify` once approved |
 | Stuck on which component to use | `pulse_intent("describe what I'm building")` |
 | Colours failing contrast / unsure about palette | `pulse_check_contrast` |
-| Something looks wrong in the browser | `pulse_restart_server`, then `/verify` |
+| Something looks wrong in the browser | `pulse_restart_server`, then `/verify --quick` |
 | Lighthouse < 100 | Fix the flagged audit, run `/verify` again — do not skip to commit |
 
 ---
@@ -165,6 +166,20 @@ If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop
 **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.
 
+**When to choose Mode B — use the component, unless:**
+- The layout requires **full-viewport height or edge-to-edge bleed** that the component doesn't support (e.g. `hero()` doesn't fill the viewport)
+- The design uses **custom gradient glows, parallax, or large-scale image fills** that the component would wrap in unwanted structure
+- The vibe is **brutalist, retro, neon, paper, or typographic-editorial** and the structural feel would be actively fought by the component's default padding/spacing/radius
+- The typography is **clamp-scaled display type** (e.g. `clamp(4rem, 10vw, 12rem)`) that breaks inside a component's internal box model
+- The layout is **asymmetric or zone-based** (e.g. 70/30 split, overlapping elements, staggered grid) that no single component supports
+- A **Figma/reference design was provided** that clearly departs from the component's output
+
+**When to use the component (not a valid reason for override):**
+- "The component doesn't have a perfect prop for this" — add a utility class or wrapper div instead
+- "I want a slightly different colour or size" — override with CSS tokens
+- "I'm not sure what the component looks like" — check the guide first
+- "It's easier to write raw HTML" — this is never a valid reason
+
 Rules for Mode B:
 - **Declare it in a comment at the top of the spec file:** `// component-free — creative override: <reason>`. The review tool detects creative override by reading this comment from the source — without it, `pulse_review` will flag every component pattern as a violation even though you chose Mode B deliberately. Announcing the mode in chat is not enough; the comment must be in the file.
 - Load `/pulse-ui.css` in `meta.styles` — the token system is still required
@@ -206,9 +221,11 @@ After the Write tool completes, call `pulse_create_page(name)` to register the p
 ✓ src/pages/my-page.js written and registered.
 ```
 
-### 3d — Suggest (optional but recommended)
+### 3d — Suggest (recommended mid-build checkpoint)
+
+After writing the first draft, call `pulse_suggest(content)` before running the hard validator. It catches obvious omissions collaboratively — a second opinion, not a gate. Then call `pulse_review(file, { quick: true })` for a lightweight structural pass (main landmark, data-event on inputs, missing onError, hex in view). Neither is a substitute for the full review, but catching issues here is faster than discovering them at Lighthouse.
 
-After writing the first draft, call `pulse_suggest(content)` before running the hard validator. It catches obvious omissions collaboratively — a second opinion, not a gate.
+If the user is iterating on the design (multiple rounds of changes before giving a final go-ahead), use `/verify --quick` between rounds — it validates, screenshots, checks console, and runs a quick code review without the 90-second Lighthouse cost. Save the full `/verify` for after the user explicitly approves the design.
 
 **Rule: never output `✓` before the tool call that confirms the result.**
 
@@ -264,7 +281,7 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 
 ### Phase 5b — Full verification (pass gate)
 
-**Run `/verify` now.** Do not execute these steps manually.
+**Run `/verify` now** (full mode — not `--quick`). Do not execute these steps manually.
 
 `/verify` validates, screenshots, runs Lighthouse (desktop + mobile), runs the performance trace (LCP + CLS), checks console errors, runs `pulse_review`, and writes the `.pulse-verified` stamp. Running steps manually does not write the stamp.