@invisibleloop/pulse 0.20.1 → 0.20.3

package/.claude/commands/pulse-start.md

@@ -0,0 +1,11 @@
+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/` — run `pulse build` if not). Then:
+
+```bash
+pulse start --port 3001
+```
+
+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/.claude/commands/pulse-stop.md

@@ -0,0 +1,5 @@
+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/.claude/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/docs/.claude/coverage-check.js

@@ -4,87 +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'
+import { pathToFileURL } from 'url'
 
-// 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 })
-    }
-  }
-}
+// 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]) {
@@ -98,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))
+    }
+  }
 
-  if (resolved && allLinesExempt(resolved, uncovered)) continue  // auto-exempt
+  const exemptLines = computeExemptLines(src)
+  return lineNums.every(n => exemptLines.has(n))
+}
 
-  gaps.push(`  ${file} — uncovered lines: ${uncovered}`)
+// ---------------------------------------------------------------------------
+// Main — only when executed directly (the exports above are unit-tested)
+// ---------------------------------------------------------------------------
+
+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/examples/.claude/coverage-check.js

@@ -4,87 +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'
+import { pathToFileURL } from 'url'
 
-// 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 })
-    }
-  }
-}
+// 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]) {
@@ -98,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))
+    }
+  }
 
-  if (resolved && allLinesExempt(resolved, uncovered)) continue  // auto-exempt
+  const exemptLines = computeExemptLines(src)
+  return lineNums.every(n => exemptLines.has(n))
+}
 
-  gaps.push(`  ${file} — uncovered lines: ${uncovered}`)
+// ---------------------------------------------------------------------------
+// Main — only when executed directly (the exports above are unit-tested)
+// ---------------------------------------------------------------------------
+
+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/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.1
+0.20.3

package/scripts/build.js

@@ -45,7 +45,7 @@ const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentTy
  * top-level variable declarations whose right-hand side calls the imported names.
  * All `node:*` built-ins are also stripped automatically via the import regex.
  */
-const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
+const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md', '@invisibleloop/pulse']
 
 /**
  * Strip all server-only property declarations from a spec source string.