@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/testing.js

@@ -1,199 +0,0 @@
-import { renderLayout, h1, lead, section, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/testing')
-
-export default {
-  route: '/testing',
-  meta: {
-    theme:       'light',
-    title: 'Testing — Pulse Docs',
-    description: 'Test Pulse view functions with renderSync and render — query the HTML output with CSS-like selectors, no DOM required.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/testing',
-    prev,
-    next,
-    content: `
-      ${h1('Testing')}
-      ${lead('Pulse ships a built-in testing helper at <code>@invisibleloop/pulse/testing</code>. Render a spec\'s view in tests and query the HTML output with CSS-like selectors — no DOM, no jsdom, no extra dependencies.')}
-
-      ${section('quick-start', 'Quick start')}
-      ${codeBlock(highlight(`import { renderSync, render } from '@invisibleloop/pulse/testing'
-import assert from 'node:assert/strict'
-import spec from './src/pages/counter.js'
-
-// Synchronous — calls view directly, mock state and server
-const result = renderSync(spec, { state: { count: 5 } })
-assert(result.has('button'))
-assert.equal(result.get('#count').text, '5')
-
-// Async — runs real spec.server fetchers (or pass server to mock them)
-const result = await render(productSpec, {
-  server: { product: { id: 1, name: 'Widget', price: 9.99 } }
-})
-assert.equal(result.get('h1').text, 'Widget')
-assert.equal(result.count('li'), 3)`, 'js'))}
-
-      ${section('render-sync', 'renderSync(spec, options?)')}
-      <p>Synchronous. Calls the view function directly — no server fetcher resolution. The fastest path for unit testing pure view functions.</p>
-      ${table(
-        ['Option', 'Type', 'Default', 'Description'],
-        [
-          ['<code>state</code>',  '<code>object</code>', '<code>{}</code>', 'State overrides merged with <code>spec.state</code>.'],
-          ['<code>server</code>', '<code>object</code>', '<code>{}</code>', 'Server state passed directly to the view. Fetchers are never called.'],
-        ]
-      )}
-      ${codeBlock(highlight(`import { renderSync } from '@invisibleloop/pulse/testing'
-
-const result = renderSync(formSpec, {
-  state:  { name: 'Alice', email: 'alice@example.com' },
-  server: { plans: [{ id: 'pro', label: 'Pro' }] },
-})`, 'js'))}
-
-      ${section('render-async', 'render(spec, options?)')}
-      <p>Async. Two modes — mock or integration:</p>
-      <ul>
-        <li><strong>Mock mode</strong> — pass <code>server</code> to use that data directly. Fetchers are not called. Fast and deterministic.</li>
-        <li><strong>Integration mode</strong> — omit <code>server</code> and real <code>spec.server</code> fetchers run. Pass <code>ctx</code> to set params, cookies, headers, etc.</li>
-      </ul>
-      ${table(
-        ['Option', 'Type', 'Default', 'Description'],
-        [
-          ['<code>state</code>',  '<code>object</code>', '<code>{}</code>',     'State overrides merged with <code>spec.state</code>.'],
-          ['<code>server</code>', '<code>object</code>', '<code>undefined</code>', 'Server state passed directly to the view. When set, fetchers are skipped entirely.'],
-          ['<code>ctx</code>',   '<code>object</code>', '<code>{}</code>',     'Request context passed to <code>spec.server</code> fetchers (integration mode only). Accepts <code>params</code>, <code>query</code>, <code>cookies</code>, <code>headers</code>, etc.'],
-        ]
-      )}
-      ${codeBlock(highlight(`import { render } from '@invisibleloop/pulse/testing'
-
-// Mock — skip fetchers
-const result = await render(productSpec, {
-  server: { product: { id: 42, name: 'Gadget' } }
-})
-
-// Integration — real fetchers, with ctx
-const result = await render(productSpec, {
-  ctx: { params: { id: '42' }, cookies: { session: 'abc' } }
-})`, 'js'))}
-
-      ${section('render-result', 'RenderResult')}
-      <p>Both functions return the same <code>RenderResult</code> object.</p>
-      ${table(
-        ['Property / method', 'Returns', 'Description'],
-        [
-          ['<code>.html</code>',                           '<code>string</code>',             'Raw HTML string from the view.'],
-          ['<code>.state</code>',                          '<code>object</code>',             'Client state used for rendering.'],
-          ['<code>.server</code>',                         '<code>object</code>',             'Server state used for rendering.'],
-          ['<code>.text()</code>',                         '<code>string</code>',             'All text content — tags stripped, entities decoded, whitespace collapsed.'],
-          ['<code>.has(selector)</code>',                  '<code>boolean</code>',            'True if any element matches selector.'],
-          ['<code>.find(selector)</code>',                 '<code>Element | null</code>',     'First matching element, or null.'],
-          ['<code>.get(selector)</code>',                  '<code>Element</code>',            'First matching element. Throws with a clear message if not found.'],
-          ['<code>.findAll(selector)</code>',              '<code>Element[]</code>',          'All matching elements.'],
-          ['<code>.count(selector)</code>',                '<code>number</code>',             'Number of matching elements.'],
-          ['<code>.attr(selector, name)</code>',           '<code>string | null</code>',      'Attribute value of the first matching element. Null if element or attribute absent.'],
-        ]
-      )}
-
-      ${section('element', 'Element')}
-      <p>Elements returned by <code>find()</code>, <code>get()</code>, and <code>findAll()</code> support the same query methods scoped to their own subtree.</p>
-      ${table(
-        ['Property / method', 'Returns', 'Description'],
-        [
-          ['<code>.tag</code>',            '<code>string</code>',         'Tag name (lowercase).'],
-          ['<code>.text</code>',           '<code>string</code>',         'All text content within the element, whitespace-collapsed.'],
-          ['<code>.attrs</code>',          '<code>object</code>',         'Parsed attribute map. Boolean attrs (e.g. <code>disabled</code>) have value <code>true</code>.'],
-          ['<code>.attr(name)</code>',     '<code>string | null</code>',  'Get one attribute. Returns <code>""</code> for boolean attrs, <code>null</code> if absent — mirrors <code>getAttribute()</code>.'],
-          ['<code>.find(selector)</code>', '<code>Element | null</code>',  'First matching descendant.'],
-          ['<code>.findAll(selector)</code>', '<code>Element[]</code>',   'All matching descendants.'],
-          ['<code>.has(selector)</code>',  '<code>boolean</code>',        'True if any descendant matches selector.'],
-        ]
-      )}
-
-      ${section('selectors', 'Supported selectors')}
-      <p>The selector engine supports the most common CSS patterns including descendant combinators (<code>div p</code>, <code>.parent li</code>). Descendant selectors match the rightmost token within the ancestor context — if no ancestors match, the result is empty (count 0).</p>
-      ${table(
-        ['Selector', 'Example', 'Matches'],
-        [
-          ['Tag',              '<code>button</code>',                  'Any <code>&lt;button&gt;</code>'],
-          ['Class',            '<code>.ui-btn</code>',                 'Elements with that class'],
-          ['ID',               '<code>#submit</code>',                 'Element with that id'],
-          ['Attribute present','<code>[disabled]</code>',              'Elements with a <code>disabled</code> attribute'],
-          ['Attribute value',  '<code>[type="submit"]</code>',         'Elements where <code>type</code> equals <code>submit</code>'],
-          ['Compound',         '<code>button.primary[disabled]</code>', 'All conditions on the same element'],
-          ['Descendant',       '<code>tbody tr</code>',                '<code>&lt;tr&gt;</code> elements inside <code>&lt;tbody&gt;</code>'],
-        ]
-      )}
-      ${codeBlock(highlight(`result.has('button')                         // any <button>
-result.has('.ui-btn--primary')               // BEM modifier class
-result.has('[data-action="submit"]')         // data attribute
-result.has('input[type="email"][required]')  // compound
-result.get('form').findAll('input')          // inputs inside form`, 'js'))}
-
-      ${section('patterns', 'Common patterns')}
-      ${codeBlock(highlight(`// Assert an element exists and check its text
-assert.equal(result.get('h1').text, 'Page Title')
-
-// Assert an element does NOT exist
-assert(!result.has('.error-message'))
-
-// Check an attribute value
-assert.equal(result.attr('input[name="email"]', 'type'), 'email')
-
-// Boolean attributes — attr() returns '' (not 'disabled')
-assert.equal(result.attr('[disabled]', 'disabled'), '')
-assert(result.get('[disabled]').attr('disabled') === '')
-
-// Count elements
-assert.equal(result.count('li'), 3)
-
-// Inspect all items
-const items = result.findAll('li')
-assert.equal(items[0].text, 'Alpha')
-assert.equal(items[1].text, 'Beta')
-
-// Scope a search to a subtree
-const form = result.get('form')
-assert(form.has('button[type="submit"]'))
-assert.equal(form.count('input'), 2)
-
-// Text content decodes entities
-// <p>&lt;b&gt;bold&lt;/b&gt;</p> → text === '<b>bold</b>'
-assert.equal(result.get('p').text, '<b>bold</b>')`, 'js'))}
-
-      ${section('test-file', 'Example test file')}
-      ${codeBlock(highlight(`/**
- * src/pages/counter.test.js
- * run: node src/pages/counter.test.js
- */
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { renderSync } from '@invisibleloop/pulse/testing'
-import spec from './counter.js'
-
-test('renders the current count', () => {
-  const result = renderSync(spec, { state: { count: 7 } })
-  assert.equal(result.get('#count').text, '7')
-})
-
-test('increment mutation returns count + 1', () => {
-  const next = spec.mutations.increment({ count: 0 })
-  assert.equal(next.count, 1)
-})
-
-test('decrement mutation returns count - 1', () => {
-  const next = spec.mutations.decrement({ count: 5 })
-  assert.equal(next.count, 4)
-})
-
-test('view renders increment and decrement buttons', () => {
-  const result = renderSync(spec)
-  assert(result.has('[data-event="increment"]'))
-  assert(result.has('[data-event="decrement"]'))
-})`, 'js'))}
-      ${callout('note', 'Use <code>renderSync</code> for mutations and pure view tests — it\'s synchronous and needs no <code>await</code>. Use <code>render</code> when your spec has <code>server</code> fetchers you want to exercise for integration coverage.')}
-    `,
-  }),
-}

package/docs/src/pages/validation.js

@@ -1,138 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/validation')
-
-export default {
-  route: '/validation',
-  meta: {
-    theme:       'light',
-    title: 'Validation — Pulse Docs',
-    description: 'Declarative validation rules in Pulse — syntax, formats, dot-path notation, and error handling.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/validation',
-    prev,
-    next,
-    content: `
-      ${h1('Validation')}
-      ${lead('Validation rules are declared in the spec, co-located with the state they guard. When an action sets <code>validate: true</code>, Pulse enforces every rule before the async work runs. Invalid data cannot reach <code>run()</code>.')}
-
-      ${section('declaring', 'Declaring validation rules')}
-      <p>The <code>validation</code> field maps dot-path state keys to rule objects:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/signup',
-  state: {
-    fields: { name: '', email: '', age: '', website: '' },
-  },
-  validation: {
-    'fields.name':    { required: true, minLength: 2, maxLength: 100 },
-    'fields.email':   { required: true, format: 'email' },
-    'fields.age':     { required: true, min: 18, max: 120 },
-    'fields.website': { format: 'url' },   // optional field, but must be valid URL if provided
-  },
-  // ...
-}`, 'js'))}
-
-      ${section('rules', 'Available rules')}
-      ${table(
-        ['Rule', 'Type', 'Description'],
-        [
-          ['<code>required</code>', '<code>boolean</code>', 'Field must be present and non-empty.'],
-          ['<code>minLength</code>', '<code>number</code>', 'String must be at least N characters.'],
-          ['<code>maxLength</code>', '<code>number</code>', 'String must be at most N characters.'],
-          ['<code>min</code>', '<code>number</code>', 'Numeric value must be ≥ N.'],
-          ['<code>max</code>', '<code>number</code>', 'Numeric value must be ≤ N.'],
-          ['<code>pattern</code>', '<code>RegExp | string</code>', 'Value must match the regular expression.'],
-          ['<code>format</code>', '<code>string</code>', 'Named format: <code>email</code>, <code>url</code>, or <code>numeric</code>.'],
-        ]
-      )}
-
-      ${section('formats', 'Named formats')}
-      ${table(
-        ['Format', 'What it checks'],
-        [
-          ['<code>email</code>', 'Basic email structure — must contain <code>@</code> and a domain.'],
-          ['<code>url</code>', 'Must start with <code>http://</code> or <code>https://</code>.'],
-          ['<code>numeric</code>', 'Must consist entirely of digit characters.'],
-        ]
-      )}
-
-      ${section('dot-paths', 'Dot-path notation')}
-      <p>Validation keys are dot-paths into the current <code>state</code>, allowing nested fields to be validated without any special syntax:</p>
-      ${codeBlock(highlight(`state: {
-  billing: {
-    address: { street: '', city: '', postcode: '' },
-    card:    { number: '', expiry: '' },
-  },
-}
-
-validation: {
-  'billing.address.street':   { required: true },
-  'billing.address.city':     { required: true },
-  'billing.address.postcode': { required: true, pattern: /^[A-Z]{1,2}\\d[A-Z\\d]? \\d[A-Z]{2}$/i },
-  'billing.card.number':      { required: true, format: 'numeric', minLength: 16, maxLength: 16 },
-  'billing.card.expiry':      { required: true },
-}`, 'js'))}
-
-      ${section('when-runs', 'When validation runs')}
-      <p>Validation only runs when an action declares <code>validate: true</code>. The order is enforced by the framework:</p>
-      <ol>
-        <li><code>onStart</code> captures <code>FormData</code> values into state</li>
-        <li>Validation reads those values from state using dot-paths</li>
-        <li>If any rules fail, <code>onError</code> is called immediately — <code>run</code> is skipped</li>
-      </ol>
-      ${callout('note', 'Validation reads from <strong>state</strong>, not from raw <code>FormData</code>. <code>onStart</code> must copy form values into state first — this is what makes them available to dot-path rules.')}
-
-      ${section('error-structure', 'Error structure')}
-      <p>When validation fails, the runtime throws an error object with a <code>validation</code> array:</p>
-      ${codeBlock(highlight(`{
-  message: 'Validation failed',
-  validation: [
-    { field: 'fields.email',   rule: 'format',   message: 'Must be a valid email address' },
-    { field: 'fields.name',    rule: 'required',  message: 'Required' },
-    { field: 'fields.age',     rule: 'min',       message: 'Must be at least 18' },
-  ]
-}`, 'js'))}
-      <p>In your action's <code>onError</code>, check for <code>err?.validation</code> to distinguish validation errors from other failures:</p>
-      ${codeBlock(highlight(`onError: (state, err) => ({
-  status: 'error',
-  errors: err?.validation ?? [{ message: err.message }],
-})`, 'js'))}
-
-      ${section('rendering', 'Rendering errors')}
-      <p>The errors array maps to UI in the view — a global error list, or inline errors using the <code>field</code> property to place them next to each input:</p>
-      ${codeBlock(highlight(`view: (state) => {
-  const errFor = (field) => {
-    const e = state.errors.find(e => e.field === field)
-    return e ? \`<p class="field-error">\${e.message}</p>\` : ''
-  }
-
-  return \`
-    <form data-action="submit">
-      <label>
-        Email
-        <input name="email" type="email" value="\${state.fields.email}">
-        \${errFor('fields.email')}
-      </label>
-      <label>
-        Name
-        <input name="name" type="text" value="\${state.fields.name}">
-        \${errFor('fields.name')}
-      </label>
-      <button>Submit</button>
-    </form>
-  \`
-}`, 'js'))}
-
-      ${section('optional-fields', 'Optional fields')}
-      <p>Omit <code>required: true</code> for optional fields. Other rules (format, minLength, etc.) are only enforced when the field has a value — empty optional fields always pass:</p>
-      ${codeBlock(highlight(`validation: {
-  // website is optional, but must be a valid URL if provided
-  'fields.website': { format: 'url' },
-}`, 'js'))}
-    `,
-  }),
-}

package/examples/.claude/commands/pulse-build.md

@@ -1,7 +0,0 @@
-Build this Pulse project for production.
-
-```bash
-pulse build
-```
-
-This bundles all pages into `public/dist/`. When complete, confirm the build succeeded and list the generated files.

package/examples/.claude/commands/pulse-dev.md

@@ -1,7 +0,0 @@
-Start (or restart) the Pulse dev server for this project.
-
-```bash
-pulse stop; pulse dev
-```
-
-The server port is read from `pulse.config.js` (defaults to 3000).

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

@@ -1,9 +0,0 @@
-Start the Pulse production server for this project.
-
-First ensure a build exists (`public/dist/`). Then run:
-
-```bash
-pulse start
-```
-
-The production server uses the port from `pulse.config.js` (defaults to 3000).

package/examples/.claude/commands/pulse-stop.md

@@ -1,5 +0,0 @@
-Stop the Pulse dev server for this project.
-
-```bash
-pulse stop
-```

package/examples/.claude/commands/verify.md

@@ -1,84 +0,0 @@
-# Verify
-
-Run the full verification loop on the current page or the page specified in $ARGUMENTS.
-
-## 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.
-
-### 2. Validate the spec
-
-Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid.
-
-### 3. Check the dev server
-
-Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
-
-**If `pulse_fetch_page` returns unexpected HTML (e.g. a different project's page title, a Next.js 404, or any non-Pulse response):** check the `X-Pulse` response header — Pulse servers always send this. If it is absent, the wrong server is running on that port. Stop and inform the user before continuing.
-
-### 4. Screenshot
-
-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.
-
-### 5. Lighthouse — desktop
-
-Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "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 2.
-
-### 6. Lighthouse — mobile
-
-Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
-
-**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
-
-**If you need to visually inspect the layout at a mobile viewport width** (e.g. to debug a wrapping or overflow issue), use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. The `emulate` tool reliably sets the viewport; `resize_page` does not reliably trigger responsive layout changes. Reset afterward with `emulate` using the desktop viewport: `"1440x900x1"`.
-
-### 7. 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.).
-
-### 8. Console errors
-
-Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
-
-### 9. Code review
-
-Call `pulse_review` with the absolute path to the spec file. Read the source, rendered HTML, validator output, and checklist it returns. Fix every issue before proceeding. This is the structured review — do not skip it or replace it with a manual checklist read.
-
-### 10. Close the browser
-
-Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__chrome-devtools__close_page` for every page ID returned. This closes the entire browser, not just the tab. `pageId` must be a number, not a string.
-
-### 11. Write verification stamp
-
-Run:
-
-```bash
-date +%s > .pulse-verified
-```
-
-**This must be the last write operation before stopping.** The stop hook compares each edited spec's modification time against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after writing the stamp.
-
-### 12. Report
-
-Summarise:
-- Validation: pass or fail (with errors if any)
-- Visual: what was visible in the screenshot
-- Lighthouse desktop: scores for all four categories
-- Lighthouse mobile: scores for all four categories
-- Performance: LCP and CLS values, any flagged insights
-- Console: any errors
-- Review: pass or issues found and fixed
-
-**Pass bar — all of these must be met before the page is confirmed good:**
-- Validation: clean (no errors, no warnings)
-- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
-- Lighthouse mobile: same
-- CLS: 0.00 — any layout shift is a blocker
-- LCP: report the value; flag and fix any insight that identifies a fixable cause
-- Console: no errors
-
-If any gate fails, fix the issue and run `/verify` again.

package/examples/.claude/coverage-check.js

@@ -1,196 +0,0 @@
-#!/usr/bin/env node
-/**
- * coverage-check.js
- *
- * 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 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'
-
-// 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*:/,
-]
-
-/**
- * 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>}
- */
-export function computeExemptLines(src) {
-  const srcLines = src.split('\n')
-  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()
-    if (EXEMPT_BLOCK_STARTS.some(re => re.test(trimmed))) {
-      let depth = 0
-      let started = false
-      while (i < srcLines.length) {
-        exemptLines.add(i + 1) // 1-based
-        for (const ch of srcLines[i]) {
-          if (ch === '{' || ch === '(') { depth++; started = true }
-          if (ch === '}' || ch === ')') { depth-- }
-        }
-        if (started && depth <= 0) break
-        i++
-      }
-    }
-    i++
-  }
-
-  // 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
-}
-
-/**
- * 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))
-}
-
-// ---------------------------------------------------------------------------
-// Main — only when executed directly (the exports above are unit-tested)
-// ---------------------------------------------------------------------------
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main()
-}
-
-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'),
-    }))
-  }
-}