@invisibleloop/pulse 0.1.21

package/scripts/build.js

@@ -0,0 +1,411 @@
+/**
+ * Pulse — Build script
+ *
+ * Auto-discovers pages from src/pages/, generates a self-executing bootstrap
+ * module per page, bundles everything with a shared runtime chunk.
+ *
+ * Usage:
+ *   node scripts/build.js [--root /path/to/project]
+ *
+ * Output:
+ *   public/dist/<name>-<hash>.js   — minified self-executing bundle per page
+ *   public/dist/runtime-<hash>.js  — shared runtime chunk
+ *   public/dist/manifest.json      — maps source hydrate paths → bundle paths
+ */
+
+import * as esbuild from 'esbuild'
+import fs           from 'fs'
+import path         from 'path'
+import { createHash } from 'crypto'
+import { discoverPages } from '../src/cli/discover.js'
+import { renderToString } from '../src/runtime/ssr.js'
+
+// Project root — can be overridden via --root flag for CLI usage
+const rootArg = process.argv.indexOf('--root')
+const ROOT    = rootArg !== -1
+  ? path.resolve(process.argv[rootArg + 1])
+  : path.resolve(import.meta.dirname, '..')
+
+const OUT_DIR = path.join(ROOT, 'public', 'dist')
+const TMP_DIR = path.join(ROOT, '.pulse-build')
+
+// ---------------------------------------------------------------------------
+// Discover pages
+// ---------------------------------------------------------------------------
+
+const pages = discoverPages(ROOT)
+
+if (pages.length === 0) {
+  console.error('No pages found in src/pages/. Nothing to build.')
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// Clean output directories
+// ---------------------------------------------------------------------------
+
+for (const dir of [OUT_DIR, TMP_DIR]) {
+  if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true })
+  fs.mkdirSync(dir, { recursive: true })
+}
+
+console.log('⚡ Building Pulse client bundles...\n')
+
+// ---------------------------------------------------------------------------
+// Generate bootstrap entry points
+// ---------------------------------------------------------------------------
+
+const RUNTIME_PATH = new URL('../src/runtime/index.js', import.meta.url).pathname
+const NAVIGATE_PATH = new URL('../src/runtime/navigate.js', import.meta.url).pathname
+
+const PAGES_DIR = path.join(ROOT, 'src', 'pages')
+
+const bootstrapFiles = pages.map(({ filePath }) => {
+  // Use the path relative to src/pages/ so nested pages get unique names.
+  // e.g. src/pages/api/products.js → 'api--products' (not 'products')
+  const relToPages    = path.relative(PAGES_DIR, filePath)
+  const name          = relToPages.replace(/\.js$/, '').replace(/[\\/]/g, '--')
+  const bootstrapPath = path.join(TMP_DIR, `${name}.boot.js`)
+  const relSpec       = path.relative(TMP_DIR, filePath)
+  const relRuntime    = path.relative(TMP_DIR, RUNTIME_PATH)
+  const relNavigate   = path.relative(TMP_DIR, NAVIGATE_PATH)
+
+  fs.writeFileSync(bootstrapPath, `\
+import spec from '${relSpec}'
+import { mount } from '${relRuntime}'
+import { initNavigation } from '${relNavigate}'
+
+const root = document.getElementById('pulse-root')
+if (root && !root.dataset.pulseMounted) {
+  root.dataset.pulseMounted = '1'
+  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+  initNavigation(root, mount)
+}
+
+export default spec
+`)
+
+  return { filePath, bootstrapPath, name }
+})
+
+// ---------------------------------------------------------------------------
+// Bundle
+// ---------------------------------------------------------------------------
+
+const result = await esbuild.build({
+  entryPoints: bootstrapFiles.map(b => b.bootstrapPath),
+  bundle:      true,
+  format:      'esm',
+  platform:    'browser',
+  outdir:      OUT_DIR,
+  entryNames:  '[name]-[hash]',
+  chunkNames:  'runtime-[hash]',
+  splitting:   true,
+  minify:      true,
+  metafile:    true,
+  sourcemap:   false,
+  treeShaking: true,
+  define: {
+    'process.env.NODE_ENV': '"production"'
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Build manifest — maps source hydrate paths → bundle paths
+// ---------------------------------------------------------------------------
+
+const manifest = {}
+
+for (const [outFile, meta] of Object.entries(result.metafile.outputs)) {
+  const bundlePath = '/' + path.relative(path.join(ROOT, 'public'), path.join(ROOT, outFile))
+
+  // Shared runtime chunk — esbuild generates this via splitting, no entryPoint
+  if (!meta.entryPoint && path.basename(outFile).startsWith('runtime-')) {
+    manifest['_runtime'] = bundlePath
+    continue
+  }
+
+  if (!meta.entryPoint) continue
+
+  const bootstrapName = path.basename(meta.entryPoint, '.boot.js')
+  const entry         = bootstrapFiles.find(b => b.name === bootstrapName)
+  if (!entry) continue
+
+  // Hydrate key is the path the browser uses to import the spec
+  const sourceKey  = '/' + path.relative(ROOT, entry.filePath)
+  manifest[sourceKey] = bundlePath
+}
+
+fs.writeFileSync(path.join(OUT_DIR, 'manifest.json'), JSON.stringify(manifest, null, 2))
+
+// ---------------------------------------------------------------------------
+// Cleanup temp dir
+// ---------------------------------------------------------------------------
+
+fs.rmSync(TMP_DIR, { recursive: true })
+
+// ---------------------------------------------------------------------------
+// CSS Purge — strip unused styles, write content-hashed CSS bundles
+// ---------------------------------------------------------------------------
+
+await purgeCssStep(pages, manifest, ROOT, OUT_DIR)
+
+// ---------------------------------------------------------------------------
+// Report
+// ---------------------------------------------------------------------------
+
+console.log('Bundles:\n')
+for (const [src, bundle] of Object.entries(manifest)) {
+  if (bundle.startsWith('/dist/')) {
+    const filePath = path.join(ROOT, 'public', bundle)
+    if (fs.existsSync(filePath)) {
+      const size = fs.statSync(filePath).size
+      console.log(`  ${src.padEnd(36)} → ${bundle}  (${(size / 1024).toFixed(1)} kB)`)
+    }
+  }
+}
+console.log('\n✓ manifest written to public/dist/manifest.json\n')
+
+// ---------------------------------------------------------------------------
+// CSS Purge implementation
+// ---------------------------------------------------------------------------
+
+async function purgeCssStep(pages, manifest, root, outDir) {
+  console.log('⚡ Purging CSS...\n')
+
+  const htmlContents = []
+  const jsContents   = []
+  const cssFiles     = new Set()
+
+  for (const { filePath } of pages) {
+    try {
+      const mod  = await import(filePath)
+      const spec = mod.default
+      if (!spec || typeof spec !== 'object') continue
+
+      // Collect CSS files referenced by this page
+      if (Array.isArray(spec.meta?.styles)) {
+        for (const href of spec.meta.styles) cssFiles.add(href)
+      }
+
+      // SSR render to extract class names from the actual HTML output
+      try {
+        const { html } = await renderToString(spec, {})
+        htmlContents.push(html)
+      } catch {
+        // Server data might fail in build context — fall back to direct view call
+        try {
+          const html = spec.view(spec.state || {}, {})
+          if (typeof html === 'string') htmlContents.push(html)
+        } catch {}
+      }
+
+      // Also scan source JS for conditionally-applied class names
+      jsContents.push(fs.readFileSync(filePath, 'utf8'))
+    } catch {}
+  }
+
+  // Scan project components directory for conditional class names
+  const componentsDir = path.join(root, 'src', 'components')
+  if (fs.existsSync(componentsDir)) {
+    const componentFiles = fs.readdirSync(componentsDir).filter(f => f.endsWith('.js'))
+    for (const f of componentFiles) {
+      try { jsContents.push(fs.readFileSync(path.join(componentsDir, f), 'utf8')) } catch {}
+    }
+  }
+
+  if (cssFiles.size === 0) {
+    console.log('  No CSS files referenced — skipping.\n')
+    return
+  }
+
+  const usedClasses = extractUsedClasses(htmlContents, jsContents)
+
+  for (const cssHref of cssFiles) {
+    // CSS path is relative to public/ (e.g. '/pulse-ui.css' → public/pulse-ui.css)
+    const cssPath = path.join(root, 'public', cssHref.replace(/^\//, ''))
+    if (!fs.existsSync(cssPath)) continue
+
+    const original = fs.readFileSync(cssPath, 'utf8')
+    const purged   = minifyCss(purgeCss(original, usedClasses))
+
+    const hash    = createHash('sha256').update(purged).digest('hex').slice(0, 8)
+    const name    = path.basename(cssHref, '.css')
+    const outName = `${name}-${hash}.css`
+    const outPath = path.join(outDir, outName)
+
+    fs.writeFileSync(outPath, purged)
+
+    const origKb  = (Buffer.byteLength(original) / 1024).toFixed(1)
+    const purgKb  = (Buffer.byteLength(purged)   / 1024).toFixed(1)
+    const pct     = Math.round((1 - Buffer.byteLength(purged) / Buffer.byteLength(original)) * 100)
+
+    console.log(`  ${cssHref.padEnd(28)} → /dist/${outName}  (${purgKb} kB, ${pct}% removed from ${origKb} kB)`)
+
+    manifest[cssHref] = `/dist/${outName}`
+  }
+
+  // Re-write manifest with CSS entries added
+  fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
+  console.log('\n✓ CSS entries added to manifest\n')
+}
+
+// ---------------------------------------------------------------------------
+// CSS class extractor
+// ---------------------------------------------------------------------------
+
+function extractUsedClasses(htmlContents, jsContents) {
+  const used = new Set()
+
+  // Extract from class="..." in both rendered HTML and JS template literals
+  for (const content of [...htmlContents, ...jsContents]) {
+    const re = /class(?:Name)?=["']([^"'\n]+)["']/g
+    let m
+    while ((m = re.exec(content)) !== null) {
+      for (const cls of m[1].trim().split(/\s+/)) {
+        if (cls) used.add(cls)
+      }
+    }
+  }
+
+  // Scan JS source for quoted strings that look like CSS class names (contain hyphens)
+  // Catches conditionally-applied classes like 'ui-btn--disabled' in ternaries
+  for (const js of jsContents) {
+    const re = /['"`]((?:[a-zA-Z][a-zA-Z0-9]*-[a-zA-Z0-9-]*)(?:\s+[a-zA-Z][a-zA-Z0-9-]*)*)['"`]/g
+    let m
+    while ((m = re.exec(js)) !== null) {
+      for (const cls of m[1].trim().split(/\s+/)) {
+        if (cls && cls.includes('-')) used.add(cls)
+      }
+    }
+  }
+
+  return used
+}
+
+// ---------------------------------------------------------------------------
+// CSS purger — strips unused rules, preserves @media / :root / element rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CSS text into top-level blocks using a bracket-depth counter.
+ * Returns [{ type, selector?, prelude?, inner?, raw }]
+ */
+function parseCssBlocks(css) {
+  const blocks = []
+  let i = 0
+  const len = css.length
+
+  while (i < len) {
+    // Skip whitespace
+    while (i < len && /\s/.test(css[i])) i++
+    if (i >= len) break
+
+    // Skip block comments
+    if (css[i] === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2)
+      i = end === -1 ? len : end + 2
+      continue
+    }
+
+    const start = i
+    let depth = 0
+
+    while (i < len) {
+      // Skip inline comments
+      if (css[i] === '/' && css[i + 1] === '*') {
+        const end = css.indexOf('*/', i + 2)
+        i = end === -1 ? len : end + 2
+        continue
+      }
+      if (css[i] === '{') { depth++; i++; continue }
+      if (css[i] === '}') { depth--; i++; if (depth === 0) break; continue }
+      if (css[i] === ';' && depth === 0) { i++; break }
+      i++
+    }
+
+    const raw = css.slice(start, i).trim()
+    if (!raw) continue
+
+    if (raw.startsWith('@')) {
+      const braceIdx = raw.indexOf('{')
+      if (braceIdx === -1) {
+        blocks.push({ type: 'at-simple', raw })
+      } else {
+        const prelude = raw.slice(0, braceIdx).trim()
+        const inner   = raw.slice(braceIdx + 1, raw.lastIndexOf('}')).trim()
+        blocks.push({ type: 'at-block', prelude, inner, raw })
+      }
+    } else {
+      const braceIdx = raw.indexOf('{')
+      if (braceIdx !== -1) {
+        blocks.push({ type: 'rule', selector: raw.slice(0, braceIdx).trim(), raw })
+      }
+    }
+  }
+
+  return blocks
+}
+
+/**
+ * Return true if any selector in the rule should be kept.
+ * Keeps: element selectors, *, :root, and any rule where a used class appears.
+ */
+function selectorUsed(selector, usedClasses) {
+  const selectors = selector.split(',').map(s => s.trim())
+
+  for (const sel of selectors) {
+    // Strip pseudo-classes/elements and attribute selectors to find the base
+    const base = sel
+      .replace(/::?[a-z-]+(\([^)]*\))?/gi, '')
+      .replace(/\[[^\]]*\]/g, '')
+      .trim()
+
+    // Keep element selectors, *, :root — no class tokens
+    if (!base.includes('.')) return true
+
+    // Keep if any class in the selector is in the used set
+    const classes = [...sel.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g)].map(m => m[1])
+    if (classes.some(cls => usedClasses.has(cls))) return true
+  }
+
+  return false
+}
+
+/**
+ * Purge unused CSS rules from a CSS string.
+ * Recursively processes @media and @supports blocks.
+ */
+function minifyCss(css) {
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, '')   // strip comments
+    .replace(/\s+/g, ' ')               // collapse whitespace
+    .replace(/\s*([{}:;,>~+])\s*/g, '$1') // remove spaces around punctuation
+    .replace(/;}/g, '}')                // remove trailing semicolons
+    .trim()
+}
+
+function purgeCss(cssText, usedClasses) {
+  const blocks = parseCssBlocks(cssText)
+  const kept   = []
+
+  for (const block of blocks) {
+    if (block.type === 'at-simple') {
+      kept.push(block.raw)
+    } else if (block.type === 'at-block') {
+      const p = block.prelude.toLowerCase()
+      if (/^@(?:keyframes|font-face|charset)/.test(p)) {
+        kept.push(block.raw)
+      } else if (/^@(?:media|supports|layer)/.test(p)) {
+        const innerPurged = purgeCss(block.inner, usedClasses)
+        if (innerPurged.trim()) kept.push(`${block.prelude} {\n${innerPurged}\n}`)
+      } else {
+        kept.push(block.raw) // unknown at-blocks — keep to be safe
+      }
+    } else if (block.type === 'rule') {
+      if (selectorUsed(block.selector, usedClasses)) kept.push(block.raw)
+    }
+  }
+
+  return kept.join('\n\n')
+}

package/src/agent/checklist.md

@@ -0,0 +1,111 @@
+## Spec review checklist
+
+Before finishing any spec, verify every point below. Fix anything that fails.
+
+### Critical
+
+- **`hydrate` is set on every interactive page.** Without it, `data-event` / `data-action` bindings do nothing, `persist` never runs, and client-side navigation cannot re-mount the page. Every spec with `mutations`, `actions`, or `persist` must include:
+  ```js
+  hydrate: '/src/pages/my-page.js',  // browser-importable path to this file
+  ```
+  Omit `hydrate` only for purely server-rendered pages with zero client interactivity.
+
+### Components first
+
+- **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
+
+### Reuse (DRY)
+
+- **Extract a view helper when the same HTML pattern appears 3 or more times in a single spec.** A plain JS function returning an HTML string is sufficient — no framework needed:
+  ```js
+  const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
+  ```
+- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+
+### Correctness
+
+- Mutations return plain partial-state objects and have no side effects (no fetch, no DOM access).
+- `persist` contains only serialisable state that should survive a page reload — not ephemeral UI state like a loading flag or temporary selection.
+- `e.target` assumptions in mutations are safe if the element has child nodes — use `e.target.closest('[data-index]')` rather than assuming `e.target` is the element with the attribute.
+- State shape is consistent — avoid a single field that is sometimes `null`, sometimes a string, sometimes a boolean. Use a dedicated `status` field instead.
+- **Never use `state.modalOpen` or conditional modal rendering.** This destroys the `<dialog>` on every render, breaking focus, animation, and native ESC handling. Instead, always render the `<dialog>` in the DOM and use `data-dialog-open="id"` to open it — the runtime handles this without any spec state:
+  ```html
+  <!-- always in the view, never conditional -->
+  ${modal({ id: 'confirm', title: 'Confirm', content: '...' })}
+  <!-- anywhere on the page — opens the dialog, no mutation needed -->
+  ${modalTrigger({ target: 'confirm', label: 'Open' })}
+  <!-- or inline: -->
+  <button data-dialog-open="confirm">Open</button>
+  ```
+  Close is handled natively by `<form method="dialog">` (inside the modal), ESC key, backdrop click, or `data-dialog-close` on any element.
+
+### Defensive data handling
+
+- **Always check `res.ok` before parsing fetch responses.** Never call `res.json()` on a response that may have failed. Never use `await res.text()` as an error message — on a 404 or 500, this returns raw HTML which surfaces directly in toasts and error alerts. The correct pattern:
+  ```js
+  const res = await fetch('/api/...')
+  if (!res.ok) {
+    let message = `Request failed: ${res.status}`
+    try { const j = await res.json(); message = j.message || j.error || message } catch {}
+    throw new Error(message)
+  }
+  return await res.json()
+  ```
+- **Never assume the shape of data from external APIs or server fetchers.** Use optional chaining (`?.`) and nullish coalescing (`??`) at every access point. If a server fetcher can return `null`, the view must handle it — `server.user?.name ?? 'Guest'` not `server.user.name`.
+- **Validate FormData fields before use.** `formData.get('email')` returns `null` if the field is missing. Check for null/empty before passing to an API or database.
+- **Do not trust URL params.** `ctx.params.id` is a raw string from the URL. Validate it before use — check it exists, is the right type, and refers to a real resource. Return a 404 or redirect if it doesn't.
+
+### Security
+
+- Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.
+
+### Tests
+
+- Pure logic functions extracted from a spec (e.g. `checkResult`, `validate`, `formatPrice`) must have unit tests in a corresponding `.test.js` file.
+- **When fixing a bug, write a failing test first.** The test must reproduce the bug before the fix is applied, then pass after. This pins the behaviour so the bug cannot silently return. A fix without a regression test is incomplete.
+- **Use `renderSync` / `render` from `@invisibleloop/pulse/testing` to test view HTML output.** Do not test views with raw `html.includes()` — use the query helpers instead:
+  ```js
+  import { renderSync, render } from '@invisibleloop/pulse/testing'
+
+  // Sync — call view directly with mock state/server
+  const result = renderSync(mySpec, { state: { count: 5 }, server: { items: [] } })
+  assert(result.has('button'))
+  assert.equal(result.get('#count').text, '5')
+  assert.equal(result.count('li'), 0)
+
+  // Async — run real server fetchers (integration), or pass server to skip them
+  const result = await render(mySpec, { server: { product: mockProduct } })
+  assert.equal(result.get('h1').text, mockProduct.name)
+  assert.equal(result.attr('img', 'src'), mockProduct.image)
+  ```
+  Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
+
+### View error handling
+
+- **Define `onViewError` on any page where the view could throw due to bad or missing data.** Without it, a runtime view error returns a 500 on the server and shows a generic inline message on the client. With it, the server returns 200 with your fallback HTML instead of a 500, and the client renders your fallback:
+  ```js
+  onViewError: (err, state, serverState) => `
+    <div class="u-p-4 u-text-center">
+      <p>Something went wrong. <a href="">Reload</a></p>
+    </div>
+  `
+  ```
+  Use this on pages that render data from external APIs or user-supplied content — any path where the view can encounter `null`, `undefined`, or unexpected shapes that would cause a crash. It is not required on simple pages with predictable data.
+
+### Store updates from actions
+
+- **Use `_storeUpdate` to push changes to the global store from an action.** Return it from `onSuccess` alongside the local state update — it is stripped from page state and forwarded to the store. All mounted pages that subscribe to the affected keys re-render immediately:
+  ```js
+  onSuccess: (state, theme) => ({
+    saved:        true,
+    _storeUpdate: { settings: { theme } },  // ← merged into store state
+  }),
+  ```
+  `_storeUpdate` only merges into the store — it does not appear in the page's own state. The rest of the return is merged into local state as normal. Use this instead of a full-page reload when a user action changes shared data (theme, cart count, user profile, etc.).
+
+### Accessibility
+
+- Interactive elements without visible text have an `aria-label`.
+- Disabled state is reflected with the `disabled` attribute, not just CSS.
+- The page has a `<main id="main-content">` landmark.

package/src/agent/coverage-check.js

@@ -0,0 +1,66 @@
+#!/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 async action run() and server fetcher functions
+ * which cannot be tested without mocking real APIs.
+ *
+ * Outputs a Claude Code hook JSON decision to stdout.
+ */
+
+import { execSync } from 'child_process'
+import fs from 'fs'
+
+// 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 gaps = []
+
+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') {
+      gaps.push(`  ${m[1].trim()} — uncovered lines: ${uncov}`)
+    }
+  }
+}
+
+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'),
+  }))
+}