@invisibleloop/pulse 0.2.12 → 0.2.13

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.11

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.13",
   "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.13

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 `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" preserveAspectRatio="none" height="${height}" style="display:block;width:100%" role="img" aria-label="${e(ariaLabel)}">${grid}${baseline}${bars}</svg>`
 }
 
 // ─── 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 `<svg${clsAttr} viewBox="0 0 ${IW} ${height}" preserveAspectRatio="none" height="${height}" style="display:block;width:100%" role="img" aria-label="${e(ariaLabel)}">${grid}${areaPath}${line}${dots}${xlabels}</svg>`
 }
 
 // ─── 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,7 @@ export function sparkline({
   }
 
   const clsAttr = cls ? ` class="${e(cls)}"` : ''
+  const dims    = fluid ? `preserveAspectRatio="none" height="${height}" style="display:block;width:100%"` : `width="${width}" height="${height}"`
 
-  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>`
+  return `<svg${clsAttr} viewBox="0 0 ${width} ${height}" ${dims} aria-hidden="true">${areaPath}<polyline points="${points}" fill="none" stroke="${c}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`
 }