@invisibleloop/pulse 0.14.1 → 0.15.0

package/docs/src/pages/how-it-works.js

@@ -87,13 +87,20 @@ export default {
       <p>Together these replace the need to paste documentation into a system prompt or rely on the agent's training data to know how Pulse works.</p>
 
       ${section('resources', 'Resources: what the agent knows')}
-      <p>The MCP server exposes two resources the agent reads before doing any work:</p>
-      <ul>
-        <li><strong><code>pulse://guide</code></strong> — the complete framework reference, split into focused sections so each fits comfortably in a single read. The agent fetches whichever sections are relevant to the task at hand.</li>
-        <li><strong><code>pulse://persona</code></strong> — the quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use <code>data-event</code> on text inputs. The persona defines what "done" means.</li>
-      </ul>
+      <p>The MCP server exposes read-only documents the agent fetches at any time. There are two top-level resources and a set of focused guide sections:</p>
+
+      <dl class="definition-list">
+        <dt><code>pulse://quickstart</code></dt>
+        <dd>Workflow phases, spec skeleton, component rules, and theming essentials combined into a single fetch. Used for targeted edits, bug fixes, or simple one-shot page builds — avoids loading the full guide for small tasks.</dd>
+
+        <dt><code>pulse://workflow</code></dt>
+        <dd>The full build workflow — every phase, pass gate, and ordering rule. The agent reads this before starting any new page or project.</dd>
+
+        <dt><code>pulse://persona</code></dt>
+        <dd>The quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use <code>data-event</code> on text inputs. The persona defines what "done" means.</dd>
+      </dl>
 
-      <p>The guide sections are:</p>
+      <p>The guide is split into topic sections the agent fetches as needed:</p>
       <dl class="definition-list">
         <dt><code>pulse://guide/spec</code></dt>
         <dd>Spec format — state, mutations, actions, streaming SSR, validation, key rules, and form layout.</dd>
@@ -112,12 +119,51 @@ export default {
 
         <dt><code>pulse://guide/examples</code></dt>
         <dd>Complete working page examples covering common patterns.</dd>
+
+        <dt><code>pulse://guide/templates</code></dt>
+        <dd>Pre-built landing page templates, adaptation rules, and theme CSS patterns. Fetched when building a new branded site or landing page.</dd>
+
+        <dt><code>pulse://guide/design-references</code></dt>
+        <dd>Twelve design directions with vibes, component combinations, palette patterns, and signature moves. Fetched during intake to pick the right aesthetic rather than defaulting to a generic SaaS look.</dd>
+
+        <dt><code>pulse://guide/design-gallery</code></dt>
+        <dd>All templates with visual descriptions and key components. Includes critical prop-name references and component recipes for cards, stat strips, and forms. Fetched when adapting a template or combining components.</dd>
+
+        <dt><code>pulse://guide/explore</code></dt>
+        <dd>Zone-based layout thinking, seven structural gestures, raw HTML patterns without components, and an anti-pattern checklist. Fetched when a distinctive or unusual layout is needed.</dd>
       </dl>
 
       ${callout('note', 'The guide is authoritative. When there is a question about how something should be structured — where state lives, how validation is wired, how streaming works — the guide answers it. The agent does not guess.')}
 
       ${section('tools', 'Tools: what the agent can do')}
-      <p>The MCP server provides tools across four categories:</p>
+      <p>The MCP server provides tools across five categories:</p>
+
+      <h3 class="doc-h3">Design &amp; intake</h3>
+      <dl class="definition-list">
+        <dt><code>pulse_extract_inspiration</code></dt>
+        <dd>Extracts a structured design brief from a URL or image shared as inspiration. Called before <code>pulse_intake</code> when the user says "I like the look of X" — it tells the agent exactly what to observe and capture.</dd>
+
+        <dt><code>pulse_intake</code></dt>
+        <dd>Captures the product name, pitch, features, palette, vibe, and anti-style before scaffolding any new page or branded template. Returns a structured brief with copy-ready content, early contrast warnings, and component suggestions. Always runs before <code>pulse_sketch</code>.</dd>
+
+        <dt><code>pulse_sketch</code></dt>
+        <dd>Generates three structurally distinct layout directions (full-bleed, asymmetric split, editorial flow, etc.) before any code is written. Called after <code>pulse_intake</code> — prevents every project from defaulting to the same centred-hero layout.</dd>
+
+        <dt><code>pulse_intent</code></dt>
+        <dd>Intent engine — describe what you want to build and get back a matched archetype, recommended components, a ready-to-adapt spec scaffold, and which guide sections to read first. An alternative entry point to <code>pulse://workflow</code> for targeted tasks.</dd>
+
+        <dt><code>pulse_design_review</code></dt>
+        <dd>Reviews the built page's visual design against the original product brief from <code>pulse_intake</code>. Checks whether the design looks and feels appropriate for the product, audience, and vibe. Runs after screenshot, before Lighthouse.</dd>
+
+        <dt><code>pulse_layout_review</code></dt>
+        <dd>Multi-viewport layout review — checks for overflow, collapsed sections, and broken images at different screen widths. Runs after design approval but before Lighthouse, catching layout issues that Lighthouse doesn't flag.</dd>
+
+        <dt><code>pulse_tokens</code></dt>
+        <dd>Lists all available <code>--ui-*</code> CSS custom property tokens from the installed <code>pulse-ui.css</code>. Used before writing theme overrides to avoid guessing token names.</dd>
+
+        <dt><code>pulse_check_contrast</code></dt>
+        <dd>Static WCAG contrast checker. Extracts colour variable definitions from a theme file and checks common foreground/background pairings for WCAG AA compliance. Run immediately after writing a theme file to catch palette mistakes before Lighthouse.</dd>
+      </dl>
 
       <h3 class="doc-h3">Scaffolding</h3>
       <dl class="definition-list">
@@ -136,11 +182,17 @@ export default {
 
       <h3 class="doc-h3">Inspection</h3>
       <dl class="definition-list">
+        <dt><code>pulse_status</code></dt>
+        <dd>Project health snapshot — pages, routes, server status, last build. Called at the start of a session to orient quickly without reading files individually.</dd>
+
         <dt><code>pulse_list_structure</code></dt>
         <dd>Lists every page, component, and store that already exists in the project. The agent calls this before creating anything — to avoid duplication and to understand what the codebase already provides.</dd>
 
         <dt><code>pulse_fetch_page</code></dt>
         <dd>Reads the full source of an existing spec file. Used when the agent needs to understand an existing page before editing it, or when a review of the current state is needed.</dd>
+
+        <dt><code>pulse_list_icons</code></dt>
+        <dd>Lists all available Pulse UI icon names, grouped by category. Called before importing icons — the agent never guesses a name.</dd>
       </dl>
 
       <h3 class="doc-h3">Validation &amp; review</h3>
@@ -148,26 +200,29 @@ export default {
         <dt><code>pulse_validate</code></dt>
         <dd>Validates a spec against the Pulse schema. Returns errors (which block progress) and warnings (which must also be resolved). The agent calls this after writing or editing every spec file.</dd>
 
+        <dt><code>pulse_suggest</code></dt>
+        <dd>Draft-mode feedback — paste a partial or complete spec and get constructive suggestions before running the hard validator. Unlike <code>pulse_validate</code>, it is collaborative rather than a gate: it notices patterns, spots likely omissions, and offers ideas. Used mid-build for a second opinion.</dd>
+
         <dt><code>pulse_review</code></dt>
         <dd>Switches the agent into reviewer mode. Returns the spec source, the rendered HTML output, and a structured checklist covering accessibility, empty states, error handling, component usage, security, and correctness. The agent reads its own output critically and fixes every issue before continuing.</dd>
+
+        <dt><code>pulse_run_tests</code></dt>
+        <dd>Runs the project test suite (<code>npm test</code>) and returns the full output. Called after writing or editing specs to verify nothing is broken.</dd>
       </dl>
 
-      <h3 class="doc-h3">Server</h3>
+      <h3 class="doc-h3">Server &amp; maintenance</h3>
       <dl class="definition-list">
         <dt><code>pulse_restart_server</code></dt>
         <dd>Restarts the Pulse dev server. Called after structural changes — adding a new page, modifying the server entry — to reload all specs and re-register routes.</dd>
 
         <dt><code>pulse_build</code></dt>
         <dd>Builds the project for production. Bundles specs, hashes assets, and writes the manifest. Called when the agent needs to verify the production build or prepare a release.</dd>
-      </dl>
 
-      <h3 class="doc-h3">Maintenance</h3>
-      <dl class="definition-list">
         <dt><code>pulse_check_version</code></dt>
         <dd>Reports the installed Pulse version and whether an update is available.</dd>
 
         <dt><code>pulse_update</code></dt>
-        <dd>Updates the Pulse package to the latest version.</dd>
+        <dd>Updates the Pulse package to the latest version and copies the latest UI assets and agent files into the project.</dd>
       </dl>
 
       ${section('flow', 'What happens when you ask for something')}

package/examples/.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/examples/.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/examples/.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/examples/.claude/commands/pulse-stop.md

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

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

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

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

@@ -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/examples/.claude/pulse-checklist.md

@@ -0,0 +1,177 @@
+## Spec review checklist
+
+Before finishing any spec, verify every point below. Fix anything that fails.
+
+### Critical
+
+- **`meta` must be a plain object — never a function.** Individual fields (`title`, `description`, `styles`) can be `async (ctx) => value` functions, but `meta` itself is always `{}`.
+
+  ```js
+  // WRONG — meta is not a function factory
+  meta: async (ctx) => ({ title: '...', styles: [...] })
+
+  // CORRECT — meta is a plain object; individual fields are functions
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title,
+    description: async (ctx) => (await post(ctx)).frontmatter.description,
+    styles:      ['/pulse-ui.css', '/app.css'],
+  }
+  ```
+
+- **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
+
+- **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
+
+### Components first — or creative override
+
+- **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.
+- **Do not reinvent component patterns.** These patterns have dedicated components — never write custom HTML for them unless a creative override applies (see below):
+  - Hero sections → `hero({ title, subtitle, actions, image, ... })`
+  - Product/service cards → `card({ title, body, image, footer, ... })`
+  - Image + text two-column layouts → `media({ image, content, reverse })`
+  - Horizontal strips/banners → `banner({ content, variant })`
+  - Feature tiles → `feature({ icon, title, description })`
+  - Testimonials → `testimonial({ quote, name, role, src })`
+  - CTAs → `cta({ title, subtitle, actions })`
+  - Navigation → `nav({ logo, links, actions })`
+  - Footers → `footer({ logo, links, columns, legal, ... })`
+
+- **Creative override — raw HTML throughout is permitted** when the design intent genuinely calls for it: a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe where components would constrain the expression. This is a deliberate design decision, not a shortcut. When taking this path:
+  - State it explicitly in the build brief: *"Building component-free — raw HTML throughout for creative control."*
+  - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason not to.
+  - `/pulse-ui.css` is always required — it provides the token system your custom CSS will use.
+  - The quality gate replaces the component checklist: **100/100/100/100 Lighthouse on both desktop and mobile is the pass bar.** A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+- When reviewing a spec built under creative override, do not flag raw section HTML as a violation — check the Lighthouse results instead.
+
+- **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
+
+  ```js
+  import { appBadge } from '@invisibleloop/pulse/ui'
+
+  // In a hero() actions slot:
+  ${hero({
+    actions: `
+      ${appBadge({ store: 'apple',  href: 'https://apps.apple.com/...' })}
+      ${appBadge({ store: 'google', href: 'https://play.google.com/...' })}
+    `,
+  })}
+  ```
+
+### 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.
+
+### CSS
+
+- **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
+- **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+
+### 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"]`, combinations (`button.primary[disabled]`), and **descendant combinators** (`result.count('.parent li')`, `result.find('tbody tr')`). Descendant selectors match the rightmost token within the ancestor context — they do not return 0 if the ancestor doesn't exist, they simply find no matching descendants.
+
+### Markdown
+
+- **Use `md()` from `@invisibleloop/pulse/md` for `.md` file content.** Never read and parse markdown manually. Pass the result's `html` to `prose()`.
+- **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
+- **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
+
+### 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.
+- **Every element with `data-event`, `data-store-event`, `data-dialog-open`, or `data-dialog-close` is natively interactive (`button`, `a`, `input`, `select`, `textarea`, `summary`) or has `tabindex="0"`.** Non-interactive tags (`div`, `span`, `li`, `td`, etc.) with these attributes are not keyboard reachable. Prefer `<button>` — it is focusable, fires on Enter/Space, and carries the correct ARIA role for free. Only use `tabindex="0"` on a non-interactive element when a `<button>` genuinely cannot be used.
+- **Every interactive element communicates its purpose and state:**
+  - Buttons have visible text or `aria-label`. Links use descriptive text — "click here", "here", "read more" are failures.
+  - Form inputs have an associated `<label for="id">` or `aria-label`. `placeholder` alone is not a label.
+  - Toggle controls (open/close, show/hide, expand/collapse) carry `aria-expanded="true|false"` or `aria-pressed="true|false"`.
+  - While an action is in flight, the trigger button has `aria-busy="true"` or its label changes (e.g. "Saving…"). A spinner alone is not enough.
+  - Active nav items have `aria-current="page"`. Selected items in a list, tab set, or option group have `aria-selected="true"`.
+- **The page has a logical tab order:**
+  - No `tabindex` value greater than 0. Positive tabindex values override the natural DOM order and create a broken tab sequence. Remove them and reorder the DOM instead.
+  - Visually hidden interactive content (off-canvas menus, collapsed panels, `opacity:0` elements) is removed from the tab order with `tabindex="-1"` or the `inert` attribute — CSS alone does not remove an element from tab order.
+  - DOM order matches the visual reading order. When flexbox `order` or CSS grid placement visually reposition elements, the tab sequence still follows the DOM — author the DOM in the order a user would read and interact with the page.

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

@@ -0,0 +1 @@
+0.14.1