@invisibleloop/pulse 0.20.0 → 0.20.2

package/scripts/build.js

@@ -34,7 +34,10 @@ import { extractUsedClasses, purgeCss, minifyCss } from './css-purge.js'
  *     from being shipped to and evaluated in the browser
  *   - avoids bundling errors when server imports use Node-only modules
  */
-const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
+// NOTE: spec.submit is also server-only but must NOT be listed here — the key
+// scanner is line-anchored at any nesting depth, and `submit:` is the most
+// common ACTION name (actions: { submit: {…} }), which would get stripped too.
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render', 'sitemap']
 
 /**
  * Pulse subpath exports that are server-only (use Node built-ins).
@@ -42,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.
@@ -351,17 +354,22 @@ function scanTemplateLiteral(src, pos) {
 
 /**
  * esbuild plugin — strips server-only spec properties before bundling.
- * Only transforms files under src/pages/ to avoid touching runtime/server code.
+ * Transforms files under src/pages/ plus the global store file (pulse.store.js
+ * carries server fetchers that must never reach the browser) — never touches
+ * runtime/server code.
  *
- * @param {string} pagesDir  Absolute path to src/pages/
+ * @param {string} pagesDir         Absolute path to src/pages/
+ * @param {string|null} storePath   Absolute path to pulse.store.js, if it exists
  */
-function createStripServerPlugin(pagesDir) {
+function createStripServerPlugin(pagesDir, storePath = null) {
   return {
     name: 'pulse-strip-server',
     setup(build) {
       build.onLoad({ filter: /\.js$/ }, (args) => {
-        if (!args.path.startsWith(pagesDir + path.sep) &&
-            args.path !== pagesDir.replace(/\/$/, '') + '.js') return undefined
+        const isPage  = args.path.startsWith(pagesDir + path.sep) ||
+                        args.path === pagesDir.replace(/\/$/, '') + '.js'
+        const isStore = storePath && args.path === storePath
+        if (!isPage && !isStore) return undefined
 
         const source   = fs.readFileSync(args.path, 'utf8')
         const stripped = stripServerOnlyImports(stripServerOnlyKeys(source))
@@ -435,6 +443,11 @@ const NAVIGATE_PATH = new URL('../src/runtime/navigate.js', import.meta.url).pat
 
 const PAGES_DIR = path.join(ROOT, 'src', 'pages')
 
+// Global store — bundled into boot files (server fetchers stripped) when present
+const STORE_PATH = fs.existsSync(path.join(ROOT, 'pulse.store.js'))
+  ? path.join(ROOT, 'pulse.store.js')
+  : null
+
 const bootstrapFiles = pages.flatMap(({ filePath }) => {
   // Strip server-only keys/imports to check what's left for the client.
   // Skip specs with no view — these are API routes or raw content specs
@@ -453,15 +466,22 @@ const bootstrapFiles = pages.flatMap(({ filePath }) => {
   const relRuntime    = path.relative(TMP_DIR, RUNTIME_PATH)
   const relNavigate   = path.relative(TMP_DIR, NAVIGATE_PATH)
 
+  // Global store — when pulse.store.js exists, every boot bundle imports it and
+  // passes it to mount() so client store mutations register in production.
+  // The strip plugin removes its server fetchers from the browser bundle;
+  // esbuild's shared-chunk splitting keeps it from being duplicated per page.
+  const storeImport = STORE_PATH ? `\nimport store from '${path.relative(TMP_DIR, STORE_PATH)}'` : ''
+  const mountOpts   = STORE_PATH ? `{ ssr: true, store }` : `{ ssr: true }`
+
   fs.writeFileSync(bootstrapPath, `\
 import spec from '${relSpec}'
 import { mount } from '${relRuntime}'
-import { initNavigation } from '${relNavigate}'
+import { initNavigation } from '${relNavigate}'${storeImport}
 
 const root = document.getElementById('pulse-root')
 if (root && !root.dataset.pulseMounted) {
   root.dataset.pulseMounted = '1'
-  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+  mount(spec, root, window.__PULSE_SERVER__ || {}, ${mountOpts})
   initNavigation(root, mount)
 }
 
@@ -488,7 +508,7 @@ const result = await esbuild.build({
   metafile:    true,
   sourcemap:   false,
   treeShaking: true,
-  plugins:     [createStripServerPlugin(PAGES_DIR)],
+  plugins:     [createStripServerPlugin(PAGES_DIR, STORE_PATH)],
   define: {
     'process.env.NODE_ENV': '"production"'
   }

package/scripts/strip-server.test.js

@@ -7,8 +7,8 @@
 // Inline the scanner functions (duplicated here to keep test self-contained)
 // ---------------------------------------------------------------------------
 
-const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
-const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render', 'sitemap']
+const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md', '@invisibleloop/pulse']
 
 function stripServerOnlyKeys(source) {
   for (const key of SERVER_ONLY_KEYS) source = removeObjectKey(source, key)
@@ -398,5 +398,34 @@ devTest('leaves module-level constants intact',
 
 // ---------------------------------------------------------------------------
 
+console.log('\nStore + new spec fields\n')
+
+test('sitemap enumerator is stripped (server-only)',
+  `export default {\n  route: '/blog/:slug',\n  sitemap: async () => ['/blog/a'],\n  view: () => '',\n}`,
+  `export default {\n  route: '/blog/:slug',\n  view: () => '',\n}`
+)
+
+test('submit is NOT stripped — it collides with the common submit action name',
+  `export default {\n  route: '/x',\n  actions: {\n    submit: {\n      run: async () => 1,\n    },\n  },\n  view: () => '',\n}`,
+  `export default {\n  route: '/x',\n  actions: {\n    submit: {\n      run: async () => 1,\n    },\n  },\n  view: () => '',\n}`
+)
+
+test('store definition: server fetchers stripped, state and mutations survive',
+  `export default {\n  state: { basket: [] },\n  server: {\n    nav: async () => fetchNav(),\n  },\n  mutations: {\n    add: (store, item) => ({ basket: [...store.basket, item] }),\n  },\n}`,
+  `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`)
 if (fail > 0) process.exit(1)

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/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-server.md

@@ -18,12 +18,10 @@ Only declared keys are saved. Restored values that differ from the spec default
 
 The global store is a shared data layer. Server fetchers run per request; mutations run on the client and broadcast to all subscribed pages without a server round-trip.
 
-**Define the store** in `pulse.store.js`:
+**Define the store** in `pulse.store.js` at the project root — that's the whole setup. The CLI auto-discovers it (like pages in `src/pages/`), loads it server-side, serves it to the browser, and hot-reloads it on edit:
 ```js
 // pulse.store.js
 export default {
-  hydrate: '/pulse.store.js',                   // browser-importable path — required for mutations
-
   state: {                                      // default/fallback values
     user:     null,
     settings: { theme: 'dark', lang: 'en' },
@@ -45,10 +43,10 @@ export default {
 }
 ```
 
-**Register the store** in your server file:
+**No registration step is needed** with `pulse dev` / `pulse start` — `pulse.store.js` is auto-discovered. Only when you call `createServer` yourself do you pass it manually:
 ```js
 import store from './pulse.store.js'
-createServer([...specs], { store })
+createServer([...specs], { store })   // manual server entry only
 ```
 
 **Use store data in a page** — declare `spec.store` with the keys needed. They appear in the view's `server` argument:

package/src/agent/workflow.md

@@ -165,6 +165,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 +220,9 @@ 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.
+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.
 
 **Rule: never output `✓` before the tool call that confirms the result.**
 

package/src/cli/cli.test.js

@@ -105,6 +105,131 @@ for (const skill of requiredSkills) {
   })
 }
 
+// ---------------------------------------------------------------------------
+// Store auto-discovery (loadStore)
+// ---------------------------------------------------------------------------
+// Regression: pulse.store.js was documented but never loaded by the CLI —
+// dev/start servers got no store, so spec.store keys were always empty.
+
+console.log('\nStore auto-discovery\n')
+
+{
+  const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const { loadStore } = await import('./discover.js')
+
+  const dir = mkdtempSync(path.join(tmpdir(), 'pulse-store-'))
+  try {
+    // No store file → null
+    const none = await loadStore(dir)
+    test('loadStore returns null when pulse.store.js is absent', () => {
+      if (none !== null) throw new Error(`Expected null, got ${JSON.stringify(none)}`)
+    })
+
+    // Valid store file → definition with browser hydrate path set
+    writeFileSync(path.join(dir, 'pulse.store.js'),
+      `export default { state: { basket: [] }, server: { nav: async () => ['Home'] }, mutations: { add: (s, i) => ({ basket: [...s.basket, i] }) } }`)
+    const def = await loadStore(dir)
+    test('loadStore loads pulse.store.js and sets the browser hydrate path', () => {
+      if (!def)                                     throw new Error('Expected a store definition')
+      if (def.hydrate !== '/pulse.store.js')        throw new Error(`Expected hydrate /pulse.store.js, got ${def.hydrate}`)
+      if (typeof def.server?.nav !== 'function')    throw new Error('server fetchers missing')
+      if (typeof def.mutations?.add !== 'function') throw new Error('mutations missing')
+      if (!Array.isArray(def.state?.basket))        throw new Error('state missing')
+    })
+
+    // Cache-busted re-import returns the edited module (dev hot reload)
+    writeFileSync(path.join(dir, 'pulse.store.js'),
+      `export default { state: { basket: [], promo: true }, mutations: {} }`)
+    const fresh = await loadStore(dir, Date.now())
+    test('loadStore cache-busts for hot reload', () => {
+      if (fresh?.state?.promo !== true) throw new Error('Expected fresh store definition after edit')
+    })
+
+    // Bad export → clear error
+    writeFileSync(path.join(dir, 'pulse.store.js'), `export default 42`)
+    let threw = false
+    try { await loadStore(dir, Date.now() + 1) } catch (e) { threw = /store object/.test(e.message) }
+    test('loadStore throws a clear error for a non-object export', () => {
+      if (!threw) throw new Error('Expected a descriptive throw for bad default export')
+    })
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Coverage-check exemptions
+// ---------------------------------------------------------------------------
+// Regression: the stop hook blocked every session on uncovered guard/submit/
+// sitemap/meta lines (server-only, untestable), and c8 ignore comments were
+// not honoured because Node's built-in coverage ignores them.
+
+console.log('\nCoverage-check exemptions\n')
+
+{
+  const { computeExemptLines } = await import('../agent/coverage-check.js')
+
+  const src = [
+    /*  1 */ `export default {`,
+    /*  2 */ `  route: '/x',`,
+    /*  3 */ `  guard: async (ctx) => {`,
+    /*  4 */ `    if (!ctx.cookies.session) return { redirect: '/login' }`,
+    /*  5 */ `  },`,
+    /*  6 */ `  submit: async (ctx) => {`,
+    /*  7 */ `    return { redirect: '/done' }`,
+    /*  8 */ `  },`,
+    /*  9 */ `  sitemap: async () => ['/a'],`,
+    /* 10 */ `  meta: {`,
+    /* 11 */ `    title: async (ctx) => fetchTitle(ctx),`,
+    /* 12 */ `  },`,
+    /* 13 */ `  view: (state) => state.n,`,
+    /* 14 */ `  helpers: () => {`,
+    /* 15 */ `    /* c8 ignore next 2 */`,
+    /* 16 */ `    impossibleBranch()`,
+    /* 17 */ `    alsoImpossible()`,
+    /* 18 */ `    normalCode()`,
+    /* 19 */ `  },`,
+    /* 20 */ `}`,
+  ].join('\n')
+
+  const exempt = computeExemptLines(src)
+
+  test('guard, submit, sitemap, and meta blocks are exempt', () => {
+    for (const n of [3, 4, 5, 6, 7, 8, 9, 10, 11, 12]) {
+      if (!exempt.has(n)) throw new Error(`Expected line ${n} to be exempt`)
+    }
+  })
+
+  test('view and ordinary helper code are NOT exempt', () => {
+    for (const n of [13, 18]) {
+      if (exempt.has(n)) throw new Error(`Line ${n} must not be exempt`)
+    }
+  })
+
+  test('c8 ignore next N exempts exactly the following N lines', () => {
+    for (const n of [15, 16, 17]) {
+      if (!exempt.has(n)) throw new Error(`Expected line ${n} to be exempt via c8 ignore`)
+    }
+    if (exempt.has(18)) throw new Error('Line 18 is beyond the ignore count and must not be exempt')
+  })
+
+  test('c8 ignore start/stop exempts the whole range', () => {
+    const ranged = computeExemptLines([
+      `const a = 1`,            // 1
+      `/* c8 ignore start */`,  // 2
+      `untestable1()`,          // 3
+      `untestable2()`,          // 4
+      `/* c8 ignore stop */`,   // 5
+      `const b = 2`,            // 6
+    ].join('\n'))
+    for (const n of [2, 3, 4, 5]) {
+      if (!ranged.has(n)) throw new Error(`Expected line ${n} exempt in range`)
+    }
+    if (ranged.has(6)) throw new Error('Line after stop must not be exempt')
+  })
+}
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)