@invisibleloop/pulse 0.2.12 → 0.2.14

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

@@ -0,0 +1,7 @@
+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/docs/.claude/commands/pulse-dev.md

@@ -0,0 +1,7 @@
+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/docs/.claude/commands/pulse-start.md

@@ -0,0 +1,9 @@
+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/docs/.claude/commands/pulse-stop.md

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

package/docs/.claude/commands/verify.md

@@ -0,0 +1,72 @@
+# 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.
+
+### 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: Performance, Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score 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: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+
+### 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
+
+Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+
+### 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 records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+
+### 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
+
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/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

@@ -0,0 +1,127 @@
+#!/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 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 })
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+function allLinesExempt(filePath, uncoveredSpec) {
+  let src
+  try { src = fs.readFileSync(filePath, 'utf8') } catch { return false }
+  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()
+  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)
+      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]) {
+          if (ch === '{' || ch === '(') { depth++; started = true }
+          if (ch === '}' || ch === ')') { depth-- }
+        }
+        if (started && depth <= 0) break
+        i++
+      }
+    }
+    i++
+  }
+
+  return lineNums.every(n => exemptLines.has(n))
+}
+
+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.',
+      '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'),
+  }))
+}

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.5
+0.2.12

package/docs/server.js

@@ -1,7 +1,15 @@
+import fs                 from 'fs'
 import { createServer }   from '../src/server/index.js'
+import { initLayoutManifest } from './src/lib/layout.js'
 import { metrics }        from './src/lib/stats.js'
 import { metricsStore }   from './src/lib/metrics-store.js'
 metricsStore.current = metrics
+
+// Populate hashed asset paths in layout.js before any page renders
+try {
+  const raw = fs.readFileSync(new URL('./public/dist/manifest.json', import.meta.url), 'utf8')
+  initLayoutManifest(JSON.parse(raw))
+} catch { /* dev: no manifest yet, layout falls back to unhashed paths */ }
 import home               from './src/pages/home.js'
 import howItWorks        from './src/pages/how-it-works.js'
 import faq               from './src/pages/faq.js'

package/docs/src/lib/layout.js

@@ -8,6 +8,12 @@
 import { NAV } from './nav.js'
 import pkg from '../../../package.json' with { type: 'json' }
 
+// Resolve static asset paths through the build manifest (hashed in prod, raw in dev).
+// Populated by initLayoutManifest() in server.js before the server starts.
+let _manifest = {}
+export function initLayoutManifest(m) { _manifest = m }
+const asset = href => _manifest[href] || href
+
 const { version } = pkg
 
 function esc(s) {
@@ -90,8 +96,8 @@ export function renderLayout({ currentHref, content, prev = null, next = null })
         ${prevNextBar(prev, next)}
       </main>
     </div>
-    <script src="/menu.js"></script>
-    <script src="/pulse-ui.js"></script>`
+    <script src="${asset('/menu.js')}" defer></script>
+    <script src="${asset('/pulse-ui.js')}" defer></script>`
 }
 
 /**

package/docs/src/pages/components/charts.js

@@ -120,7 +120,7 @@ export default {
       )}
 
       <h2 class="doc-h2" id="donut">Donut chart</h2>
-      <p>Ring chart with multiple segments. Each item can override its colour. Pass <code>label</code> and <code>sublabel</code> for a centred annotation.</p>
+      <p>Ring chart with multiple segments. Each item can override its colour. Pass <code>label</code> and <code>sublabel</code> for a centred annotation. Add <code>fluid: true</code> to expand to the parent container width.</p>
       ${demo(
         `<div style="display:flex;justify-content:center">` +
         donutChart({
@@ -171,7 +171,7 @@ export default {
       )}
 
       <h2 class="doc-h2" id="sparkline">Sparkline</h2>
-      <p>Minimal inline trend line — pass a plain array of numbers. Designed to sit alongside <code>stat()</code> tiles or inside table cells.</p>
+      <p>Minimal inline trend line — pass a plain array of numbers. Designed to sit alongside <code>stat()</code> tiles or inside table cells. Add <code>fluid: true</code> to expand to the parent container width.</p>
       ${demo(
         `<div style="display:flex;gap:.75rem;align-items:center;flex-wrap:wrap">` +
           sparkline({ data: [12,18,14,22,19,28,24,31], color: 'accent',  area: true  }) +
@@ -228,14 +228,15 @@ sparkline({ data: [31,24,28,19,22,14,18,12], color: 'error',  area: true })`
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
-          ['<code>data</code>',       'array',   '—',       '<code>{ label, value }[]</code>'],
-          ['<code>height</code>',     'number',  '220',     'SVG height in px'],
+          ['<code>data</code>',       'array',   '—',        '<code>{ label, value }[]</code>'],
+          ['<code>height</code>',     'number',  '220',      'SVG height in px'],
           ['<code>color</code>',      'string',  "'accent'", 'accent · success · warning · error · blue · muted'],
-          ['<code>showValues</code>', 'boolean', 'false',   'Value labels above each bar'],
-          ['<code>showGrid</code>',   'boolean', 'true',    'Horizontal grid lines'],
-          ['<code>gap</code>',        'number',  '0.25',    'Gap between bars as fraction 0–0.9'],
+          ['<code>showValues</code>', 'boolean', 'false',    'Value labels above each bar'],
+          ['<code>showGrid</code>',   'boolean', 'true',     'Horizontal grid lines'],
+          ['<code>gap</code>',        'number',  '0.25',     'Gap between bars as fraction 0–0.9'],
         ]
       )}
+      <p class="doc-note u-mt-2">Always renders at full parent width (<code>width="100%"</code>).</p>
 
       <h3 class="doc-h3" style="margin-top:2rem">lineChart()</h3>
       ${table(
@@ -249,16 +250,18 @@ sparkline({ data: [31,24,28,19,22,14,18,12], color: 'error',  area: true })`
           ['<code>showGrid</code>',  'boolean', 'true',     'Horizontal grid lines'],
         ]
       )}
+      <p class="doc-note u-mt-2">Always renders at full parent width (<code>width="100%"</code>).</p>
 
       <h3 class="doc-h3" style="margin-top:2rem">donutChart()</h3>
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
-          ['<code>data</code>',      'array',  '—',    '<code>{ label, value, color? }[]</code> — color per segment'],
-          ['<code>size</code>',      'number', '200',  'Diameter in px'],
-          ['<code>thickness</code>', 'number', '40',   'Ring thickness in px'],
-          ['<code>label</code>',     'string', '—',    'Large centre text'],
-          ['<code>sublabel</code>',  'string', '—',    'Smaller text below centre label'],
+          ['<code>data</code>',      'array',   '—',     '<code>{ label, value, color? }[]</code> — color per segment'],
+          ['<code>size</code>',      'number',  '200',   'Diameter in px'],
+          ['<code>thickness</code>', 'number',  '40',    'Ring thickness in px'],
+          ['<code>label</code>',     'string',  '—',     'Large centre text'],
+          ['<code>sublabel</code>',  'string',  '—',     'Smaller text below centre label'],
+          ['<code>fluid</code>',     'boolean', 'false', 'Expand to parent width, preserving aspect ratio'],
         ]
       )}
 
@@ -267,10 +270,11 @@ sparkline({ data: [31,24,28,19,22,14,18,12], color: 'error',  area: true })`
         ['Prop', 'Type', 'Default', 'Description'],
         [
           ['<code>data</code>',   'number[]', '—',        'Plain array of numbers'],
-          ['<code>width</code>',  'number',   '80',       'SVG width in px'],
+          ['<code>width</code>',  'number',   '80',       'SVG width in px (ignored when fluid: true)'],
           ['<code>height</code>', 'number',   '32',       'SVG height in px'],
           ['<code>color</code>',  'string',   "'accent'", 'accent · success · warning · error · blue · muted'],
           ['<code>area</code>',   'boolean',  'false',    'Fill area under the line'],
+          ['<code>fluid</code>',  'boolean',  'false',    'Expand to parent width, preserving aspect ratio'],
         ]
       )}
     `,

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.12
+0.2.14

package/scripts/build.js

@@ -404,6 +404,12 @@ fs.rmSync(TMP_DIR, { recursive: true })
 
 await purgeCssStep(pages, manifest, ROOT, OUT_DIR)
 
+// ---------------------------------------------------------------------------
+// JS static assets — minify + hash any .js files directly in public/
+// ---------------------------------------------------------------------------
+
+await jsAssetsStep(ROOT, OUT_DIR, manifest)
+
 // ---------------------------------------------------------------------------
 // Report
 // ---------------------------------------------------------------------------
@@ -420,6 +426,39 @@ for (const [src, bundle] of Object.entries(manifest)) {
 }
 console.log('\n✓ manifest written to public/dist/manifest.json\n')
 
+// ---------------------------------------------------------------------------
+// JS static assets implementation
+// ---------------------------------------------------------------------------
+
+async function jsAssetsStep(root, outDir, manifest) {
+  const publicDir = path.join(root, 'public')
+  if (!fs.existsSync(publicDir)) return
+
+  const jsFiles = fs.readdirSync(publicDir).filter(f => f.endsWith('.js'))
+  if (jsFiles.length === 0) return
+
+  console.log('⚡ Hashing static JS assets...\n')
+
+  for (const file of jsFiles) {
+    const srcPath = path.join(publicDir, file)
+    const source  = fs.readFileSync(srcPath, 'utf8')
+    const { code } = await esbuild.transform(source, { minify: true, target: 'es2018' })
+    const hash    = createHash('sha256').update(code).digest('hex').slice(0, 8)
+    const name    = path.basename(file, '.js')
+    const outName = `${name}-${hash}.js`
+
+    fs.writeFileSync(path.join(outDir, outName), code)
+    manifest[`/${file}`] = `/dist/${outName}`
+
+    const origKb = (Buffer.byteLength(source) / 1024).toFixed(1)
+    const minKb  = (Buffer.byteLength(code)   / 1024).toFixed(1)
+    console.log(`  /${file.padEnd(24)} → /dist/${outName}  (${minKb} kB from ${origKb} kB)`)
+  }
+
+  fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2))
+  console.log('\n✓ JS asset entries added to manifest\n')
+}
+
 // ---------------------------------------------------------------------------
 // CSS Purge implementation
 // ---------------------------------------------------------------------------

package/src/server/index.js

@@ -1315,6 +1315,13 @@ function resolveSpec(spec, hydrateMap) {
     }
   }
 
+  if (Array.isArray(spec.meta?.scripts)) {
+    const resolvedScripts = spec.meta.scripts.map(href => hydrateMap[href] || href)
+    if (resolvedScripts.some((s, i) => s !== spec.meta.scripts[i])) {
+      resolved = { ...resolved, meta: { ...resolved.meta, scripts: resolvedScripts } }
+    }
+  }
+
   return resolved
 }
 

package/src/ui/charts.js

@@ -117,7 +117,7 @@ export function barChart({
   const ariaLabel = `Bar chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
   const clsAttr   = cls ? ` class="${e(cls)}"` : ''
 
-  return `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" width="100%" height="${height}" role="img" aria-label="${e(ariaLabel)}">${grid}${baseline}${bars}</svg>`
+  return `<div${clsAttr} style="width:100%;aspect-ratio:${IW}/${height}"><svg viewBox="0 0 ${IW} ${height}" width="100%" height="100%" style="display:block" role="img" aria-label="${e(ariaLabel)}">${grid}${baseline}${bars}</svg></div>`
 }
 
 // ─── Line chart ───────────────────────────────────────────────────────────────
@@ -193,7 +193,7 @@ export function lineChart({
   const ariaLabel = `Line chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
   const clsAttr   = cls ? ` class="${e(cls)}"` : ''
 
-  return `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" width="100%" height="${height}" role="img" aria-label="${e(ariaLabel)}">${grid}${areaPath}${line}${dots}${xlabels}</svg>`
+  return `<div${clsAttr} style="width:100%;aspect-ratio:${IW}/${height}"><svg viewBox="0 0 ${IW} ${height}" width="100%" height="100%" style="display:block" role="img" aria-label="${e(ariaLabel)}">${grid}${areaPath}${line}${dots}${xlabels}</svg></div>`
 }
 
 // ─── Donut chart ──────────────────────────────────────────────────────────────
@@ -207,6 +207,7 @@ export function lineChart({
  * @param {number}  opts.thickness - Ring thickness in px (default: 40)
  * @param {string}  opts.label     - Large text in the centre
  * @param {string}  opts.sublabel  - Smaller text below the centre label
+ * @param {boolean} opts.fluid     - Expand to parent width (preserves aspect ratio)
  * @param {string}  opts.class
  */
 export function donutChart({
@@ -215,6 +216,7 @@ export function donutChart({
   thickness  = 40,
   label      = '',
   sublabel   = '',
+  fluid      = false,
   class: cls = '',
 } = {}) {
   if (!data.length) return ''
@@ -267,8 +269,9 @@ export function donutChart({
 
   const ariaLabel = `Donut chart: ${data.map(d => `${d.label ?? ''} ${d.value}`).join(', ')}`
   const clsAttr   = cls ? ` class="${e(cls)}"` : ''
+  const dims      = fluid ? `style="display:block;width:100%"` : `width="${size}" height="${size}"`
 
-  return `<svg${clsAttr} viewBox="0 0 ${size} ${size}" width="${size}" height="${size}" role="img" aria-label="${e(ariaLabel)}">${segments}${labelEl}${subEl}</svg>`
+  return `<svg${clsAttr} viewBox="0 0 ${size} ${size}" ${dims} role="img" aria-label="${e(ariaLabel)}">${segments}${labelEl}${subEl}</svg>`
 }
 
 // ─── Sparkline ────────────────────────────────────────────────────────────────
@@ -283,6 +286,7 @@ export function donutChart({
  * @param {number}   opts.height - SVG height in px (default: 32)
  * @param {'accent'|'success'|'warning'|'error'|'blue'|'muted'} opts.color
  * @param {boolean}  opts.area   - Fill area under the line
+ * @param {boolean}  opts.fluid  - Expand to parent width (preserves aspect ratio)
  * @param {string}   opts.class
  */
 export function sparkline({
@@ -291,6 +295,7 @@ export function sparkline({
   height     = 32,
   color      = 'accent',
   area       = false,
+  fluid      = false,
   class: cls = '',
 } = {}) {
   if (data.length < 2) return ''
@@ -316,6 +321,9 @@ export function sparkline({
   }
 
   const clsAttr = cls ? ` class="${e(cls)}"` : ''
+  if (fluid) {
+    return `<div${clsAttr} style="width:100%;aspect-ratio:${width}/${height}"><svg viewBox="0 0 ${width} ${height}" width="100%" height="100%" style="display:block" aria-hidden="true">${areaPath}<polyline points="${points}" fill="none" stroke="${c}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></div>`
+  }
 
   return `<svg${clsAttr} viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" aria-hidden="true">${areaPath}<polyline points="${points}" fill="none" stroke="${c}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`
 }