@invisibleloop/pulse 0.1.21

package/CLAUDE.md

@@ -0,0 +1,383 @@
+# Pulse — AI Agent Guide
+
+Pulse is a spec-first frontend framework. The spec is the source of truth. No codegen, no virtual DOM, no dependencies (esbuild is dev-only).
+
+## Commands
+
+```bash
+npm run dev    # start dev server at http://localhost:3001
+npm test       # run all 92 unit tests
+npm run build  # bundle for production → public/dist/
+```
+
+## Project Structure
+
+```
+src/
+  spec/schema.js          # authoritative spec definition + validation
+  runtime/index.js        # client mount() + dispatch + constraints
+  runtime/ssr.js          # server-side rendering (string + stream)
+  runtime/navigate.js     # client-side navigation + history
+  server/index.js         # HTTP server (Node built-in, zero deps)
+examples/
+  counter.js              # simple client-only spec
+  contact.js              # spec with server data + async action
+  dev.server.js           # combined dev server for both specs
+scripts/
+  build.js                # esbuild bundler — generates public/dist/
+public/
+  pulse.css               # base stylesheet (dark theme)
+  dist/                   # generated — do not edit
+    runtime-[hash].js     # shared runtime chunk (mount + navigate)
+    [name].boot-[hash].js # per-page spec bundle
+    manifest.json         # source hydrate paths → bundle paths
+```
+
+## The Spec
+
+A spec is a plain JS object. Every property is optional except `route`, `state`, and `view`.
+
+```js
+export const mySpec = {
+  route:   '/path',           // URL pattern, supports :params
+  hydrate: '/path/to/spec.js',// browser-importable path → enables hydration
+
+  meta: {
+    title:       'Page Title',
+    description: 'Meta description',
+    styles:      ['/pulse.css'],
+    ogTitle:     '...',
+    ogImage:     '...',
+  },
+
+  // Server data — resolved before render, passed to view as second arg
+  server: {
+    data: async (ctx) => ({ ... })  // ctx has params, query, headers, cookies
+  },
+
+  // Timeout for all server fetchers on this page (ms). Overrides createServer fetcherTimeout.
+  serverTimeout: 5000,
+
+  // Global store keys this page subscribes to — appears in view's server arg
+  // Store mutations update all subscribed pages without a server round-trip
+  store: ['user', 'cart'],
+
+  // Initial client state — deep cloned on mount, never mutated directly
+  state: { count: 0 },
+
+  // Declarative min/max bounds — always enforced after mutations
+  constraints: {
+    count: { min: 0, max: 10 }
+  },
+
+  // Validation rules — checked when action.validate === true
+  validation: {
+    'fields.email': { required: true, format: 'email' },
+    'fields.name':  { required: true, minLength: 2, maxLength: 100 }
+    // formats: email | url | numeric
+    // rules:   required | minLength | maxLength | min | max | pattern
+  },
+
+  // Pure function(s) — return HTML string, no side effects
+  // Can be a single function or a keyed object of segment functions
+  view: (state, server) => `<main>...</main>`,
+
+  // Optional — called client-side when view() throws. Return an HTML string.
+  // Without this, the runtime shows an inline error message and logs to console.
+  // On the server, a throwing view always propagates to the server error handler
+  // unless onViewError is defined, in which case it returns the fallback HTML with 200.
+  onViewError: (err, state, serverState) => `<p>Something went wrong</p>`,
+
+  // Synchronous state changes — return partial state to merge
+  mutations: {
+    increment: (state, event) => ({ count: state.count + 1 }),
+  },
+
+  // Async operations — lifecycle: onStart → validate → run → onSuccess/onError
+  actions: {
+    submit: {
+      onStart:   (state, formData) => ({ status: 'loading', ... }),
+      validate:  true,           // runs validation before run()
+      run:       async (state, serverState, formData) => { /* fetch, etc */ },
+      onSuccess: (state, payload) => ({
+        status: 'success',
+        _toast: { message: 'Saved!', variant: 'success' },  // show a toast
+      }),
+      onError:   (state, err) => ({
+        status: 'error',
+        errors: err?.validation ?? [{ message: err.message }],
+        _toast: { message: 'Something went wrong', variant: 'error' },
+      }),
+    }
+  },
+
+  // Streaming SSR — split view into shell (instant) + deferred segments
+  stream: {
+    shell:    ['header', 'nav'],
+    deferred: ['feed']
+  }
+}
+
+export default mySpec  // required for hydration imports
+```
+
+## HTML Event Binding
+
+Pulse binds to DOM attributes — no JSX, no templates.
+
+```html
+<button data-event="increment">+</button>          <!-- click → mutation -->
+<input  data-event="change:setName">               <!-- change → mutation -->
+<input  data-event="input:setQuery">               <!-- input → mutation -->
+<input  data-event="input:search" data-debounce="300">  <!-- debounced input (300ms) -->
+<input  data-event="input:filter" data-throttle="100">  <!-- throttled input (100ms) -->
+<form   data-action="submit">...</form>             <!-- submit → action, passes FormData -->
+<button data-store-event="toggleTheme">Toggle</button>   <!-- click → store mutation -->
+<select data-store-event="change:setLang">...</select>   <!-- change → store mutation -->
+<button data-dialog-open="my-modal">Open modal</button> <!-- opens <dialog id="my-modal"> -->
+<button data-dialog-close>Cancel</button>                <!-- closes nearest ancestor <dialog> -->
+```
+
+**Modal pattern — never use `state.modalOpen`.** Always render the `<dialog>` in the DOM unconditionally and use `data-dialog-open` to show it. ESC key, backdrop click, and `<form method="dialog">` all close it natively with no spec state.
+
+**Important:** Do not use `data-event` on text inputs to mirror their value into state. The `innerHTML` replacement on every keystroke destroys focus. Instead, use uncontrolled inputs and capture `FormData` in `action.onStart` before `validate` runs.
+
+## Dev vs Production Hydration
+
+**Dev mode** — the HTML includes an inline bootstrap script importing source files directly:
+```html
+<script type="module">
+  import spec from '/examples/counter.js'
+  import { mount } from '/src/runtime/index.js'
+  import { initNavigation } from '/src/runtime/navigate.js'
+  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+  initNavigation(root, mount)
+</script>
+```
+
+**Production** — after `npm run build`, `spec.hydrate` is resolved via `manifest.json` to a content-hashed bundle. The HTML becomes a single external tag:
+```html
+<script type="module" src="/dist/counter.boot-HASH.js"></script>
+```
+
+The bundle is self-executing (imports spec, calls `mount` + `initNavigation` internally). The `{ ssr: true }` option tells `mount` to skip the initial re-render and only bind events — this preserves the SSR-painted LCP element.
+
+## Build Output
+
+`npm run build` generates three things per app:
+
+- `public/dist/runtime-[hash].js` — shared runtime (mount + navigate + schema, ~2.1 kB brotli)
+- `public/dist/[name].boot-[hash].js` — per-page spec bundle (~0.5–0.9 kB brotli)
+- `public/dist/manifest.json` — maps `/examples/foo.js` → `/dist/foo.boot-HASH.js`
+
+To add a new page to the build, add its spec path to the `ENTRIES` array in `scripts/build.js`.
+
+The server auto-detects the manifest from `staticDir/dist/manifest.json` when `staticDir` is set. No config needed.
+
+## Server
+
+```js
+import { createServer } from './src/server/index.js'
+
+createServer([specA, specB], {
+  port:         3000,
+  stream:       true,          // streaming SSR (default)
+  staticDir:    'public',      // serve static files + auto-load manifest
+  manifest:     null,          // explicit manifest path or object (overrides auto-detect)
+  defaultCache: 3600,          // default HTML cache TTL in seconds for all pages (prod only)
+                               // also accepts true (3600s + swr 86400s) or { public, maxAge, staleWhileRevalidate }
+                               // spec.cache overrides per-page; in-process + Cache-Control headers both set
+  fetcherTimeout:  5000,        // ms before any server fetcher times out (null = no limit)
+                                // spec.serverTimeout overrides per-page
+  shutdownTimeout: 30000,       // ms to wait for in-flight requests before force-exit on SIGTERM/SIGINT
+  healthCheck:     '/healthz',  // built-in health endpoint path, or false to disable
+  csp: {                        // extra sources merged into the framework's default CSP
+    'style-src': ['https://fonts.googleapis.com'],
+    'font-src':  ['https://fonts.gstatic.com'],
+  },
+  resolveBrand: async (host) => db.brands.findBySlug(host.split('.')[0]),
+                               // multi-brand: result cached 60s, attached to ctx.brand
+  onRequest:    (req, res) => { /* return false to short-circuit */ },
+  onError:      (err, req, res) => { /* custom error handling */ }
+})
+```
+
+All specs are validated at startup — bad specs throw before the server accepts connections.
+
+## Multi-brand Sites
+
+Pass `resolveBrand: async (host) => brandConfig` to `createServer`. The result is cached per host for 60 seconds and attached to `ctx.brand`. It is available in `guard`, `server` fetchers, and any `meta` field that is a function.
+
+Any `meta` field can be a function `(ctx) => value` — called per request, not at startup:
+
+```js
+export default {
+  meta: {
+    title:  (ctx) => `${ctx.brand.name} — Home`,
+    styles: (ctx) => ['/pulse-ui.css', `/themes/${ctx.brand.slug}.css`],
+  },
+  server: {
+    brand: (ctx) => ctx.brand,   // expose to view as serverState.brand
+  },
+  view: (state, { brand }) => `<h1>${brand.name}</h1>`,
+  guard: async (ctx) => {
+    if (!ctx.brand) return { redirect: '/not-found' }
+  },
+}
+```
+
+Keep brand differences in CSS custom properties — one `/pulse-ui.css` for components, one small `/themes/slug.css` per brand that overrides `:root` variables only.
+
+## Custom Fonts
+
+`pulse-ui.css` exposes `--ui-font: var(--font, system-ui, ...)` and `--ui-mono: var(--mono, ...)`. All components use these tokens. To set a custom font, override `--font` in `:root` — it cascades into every component automatically.
+
+```css
+/* app.css */
+:root {
+  --font: 'Inter', system-ui, sans-serif;
+}
+```
+
+Load the font via `meta.styles` before `pulse-ui.css`, or self-host in `staticDir/fonts/` with `@font-face`:
+
+```js
+meta: {
+  styles: [
+    'https://fonts.googleapis.com/css2?family=Inter&display=swap',
+    '/pulse-ui.css',
+    '/app.css',
+  ]
+}
+```
+
+For multi-brand setups, each brand theme file just overrides `--font` in `:root`.
+
+## HTTP Response Behaviour
+
+- **Full page request** — SSR HTML with hydration bootstrap
+- **`X-Pulse-Navigate: true`** — returns JSON `{ html, title, hydrate, serverState }` for client-side navigation
+- **Security headers** — on every response: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy`
+- **Compression** — brotli preferred, gzip fallback for all compressible types
+- **Cache** — `/dist/*` bundles: `immutable, max-age=31536000`; static assets: `max-age=3600`; HTML: `no-store`
+
+## Client Navigation
+
+`initNavigation(root, mount)` intercepts same-origin `<a>` clicks:
+1. Fetches the new page with `X-Pulse-Navigate: true`
+2. Swaps `root.innerHTML` + updates `document.title`
+3. Dynamically imports the new spec bundle (`import(hydrate)`)
+4. Calls `mount(spec, root, serverState)` to re-attach interactivity
+
+Falls back to `location.href` on any error.
+
+## Testing
+
+Tests use Node.js built-in `node:test` and `node:assert`. Each test file is run directly:
+
+```bash
+node src/spec/schema.test.js
+node src/runtime/runtime.test.js
+node src/runtime/ssr.test.js
+node src/server/server.test.js
+```
+
+Server tests use an incrementing port counter (`withServer` helper) to avoid TCP TIME_WAIT conflicts between tests. Each test gets its own port.
+
+### View testing — `@invisibleloop/pulse/testing`
+
+Use `renderSync` and `render` to test view HTML output. Both return a `RenderResult` with CSS-like query helpers — no DOM, no jsdom, pure Node.js.
+
+```js
+import { renderSync, render } from '@invisibleloop/pulse/testing'
+
+// Sync — calls view directly, pass mock state/server
+const result = renderSync(mySpec, { state: { count: 5 }, server: { items: [] } })
+result.has('button')                        // → true/false
+result.get('#count').text                   // → '5'  (throws if not found)
+result.find('.title')?.text                 // → string | null
+result.findAll('li')                        // → Element[]
+result.count('li')                          // → number
+result.attr('input[name="email"]', 'value') // → string | null
+result.text()                               // → all text, tags stripped
+
+// Async — runs real spec.server fetchers (pass server to mock them)
+const result = await render(mySpec, { server: { product: mockProduct } })
+const result = await render(mySpec, { ctx: { params: { id: '1' } } }) // real fetchers
+```
+
+**Supported selectors:** `button`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations: `button.primary[type="submit"]`.
+`Element` also has `.find()`, `.findAll()`, `.has()`, `.attr()`, `.text`, `.tag`, `.attrs`.
+
+## Key Decisions (Do Not Reverse)
+
+| Decision | Reason |
+|---|---|
+| `{ ssr: true }` skips initial render in `mount()` | Preserves SSR-painted LCP — re-rendering would cause a flash and push LCP to ~500ms |
+| `onStart` captures `FormData` before `validate` runs | Uncontrolled inputs — `innerHTML` replacement on keystroke destroys focus |
+| Self-executing bundles with `export default spec` | Single HTTP request for JS; spec exported so client navigation can re-mount |
+| `splitting: true` in esbuild | Shared runtime extracted once, cached across all page navigations |
+| `window.__PULSE_SERVER__` injected by `renderToStream` | Streaming path must serialize server state into HTML — client hydration reads it without a second request |
+| Bundle path detection via `/dist/` prefix | `wrapDocument` and streaming path emit `<script src>` for bundles, inline bootstrap for dev source files |
+| Security headers on every response, including 404/405 | Defense in depth — error responses are also entry points |
+
+## Build Workflow
+
+Every build task follows this sequence. Each phase has a pass gate — do not advance until it clears.
+
+**Before calling any slow tool (`pulse_build`, `lighthouse_audit`), output a status message to the user first** — e.g. "Building for production — ~30 s…" or "Running Lighthouse desktop audit…". Never call a slow tool silently.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1. Understand | Read guides, call `pulse_list_structure` | — |
+| 2. Plan | Present plan to user, wait for confirmation | User confirms |
+| 3. Build | Write spec + related files | — |
+| 4. Validate | `pulse_validate` — fix all errors + warnings | Clean output |
+| 5. Browser | Screenshot + Lighthouse desktop + mobile | 100/100/100 (Accessibility, Best Practices, SEO) both strategies |
+| 6. Tests | Write tests, run them, fix failures | All pass |
+| 7. Review Agent | Invoke review — **only after phases 4–6 all pass** | — |
+| 8. Fix | Fix every review issue, re-run affected gates | All gates still pass |
+
+**Skip phase 2 confirmation only for trivially small, unambiguous tasks.** When in doubt, confirm.
+
+**The Review Agent is always last.** Never invoke it before validate, Lighthouse, and tests all pass.
+
+The `/verify` command runs the browser check loop (phases 4–5) automatically. Use it.
+
+## Pulse vs React — Do Not Do These
+
+Pulse views are plain JS template literals, not JSX. These React patterns are **wrong in Pulse**:
+
+| Wrong (React) | Correct (Pulse) |
+|---|---|
+| `className="foo"` | `class="foo"` |
+| `htmlFor="id"` | `for="id"` |
+| `onClick={handler}` | `data-event="click:mutationName"` |
+| `onChange={handler}` | `data-event="change:mutationName"` |
+| `<input value={state.x}>` | Uncontrolled — read via `FormData` in `onStart` |
+| `{expression}` in JSX | `${expression}` in template literal |
+| `<>...</>` fragments | No fragments — use a real wrapper element |
+| `import React from 'react'` | No import needed — plain JS |
+| `useState`, `useEffect`, `useRef` | No hooks — use `state`, `mutations`, `actions` |
+| `key={item.id}` on list items | No `key` props — no virtual DOM |
+| Capitalized `<MyComponent />` | Call as a plain function: `${myComponent(props)}` |
+| `setState(prev => ...)` | Mutations return partial state: `(state) => ({ x: state.x + 1 })` |
+
+Also: mutations must be pure (no fetch, no DOM access). Only `actions` can be async.
+
+## Check Components Before Building
+
+Before writing any UI HTML by hand, check `src/ui/index.js` — there are 50+ components available. Use them. Do not reinvent `button`, `card`, `alert`, `modal`, `spinner`, `badge`, `input`, etc.
+
+@src/agent/checklist.md
+
+## Performance Baseline
+
+| Page | CLS | JS (brotli) |
+|---|---|---|
+| /counter | 0.00 | 3.5 kB (first visit) / 0.35 kB (cached runtime) |
+| /contact | 0.00 | 3.6 kB (first visit) / 0.47 kB (cached runtime) |
+
+Lighthouse: 100/100/100 (Accessibility / Best Practices / SEO) on both pages.
+
+LCP is fast by design (streaming SSR sends HTML before data resolves) but actual millisecond values depend on machine speed, browser, network conditions, and server location — do not quote specific numbers.

package/README.md

@@ -0,0 +1,95 @@
+# Pulse
+
+**A spec-first, AI-native web framework.** Early access — v0.1.
+
+Write a plain JavaScript object that describes what a page does. Pulse handles routing, SSR, hydration, client-side navigation, compression, security headers, and caching automatically.
+
+```js
+export default {
+  route: '/counter',
+  hydrate: '/src/pages/counter.js',
+  meta: {
+    title: 'Counter',
+    styles: ['/app.css'],
+  },
+
+  state: { count: 0 },
+
+  constraints: {
+    count: { min: 0, max: 10 },
+  },
+
+  view: (state) => `
+    <main id="main-content">
+      <p>${state.count}</p>
+      <button data-event="decrement">−</button>
+      <button data-event="increment">+</button>
+    </main>
+  `,
+
+  mutations: {
+    increment: (state) => ({ count: state.count + 1 }),
+    decrement: (state) => ({ count: state.count - 1 }),
+  },
+}
+```
+
+## Requirements
+
+Node.js 22 or later.
+
+## Getting started
+
+```bash
+npm install -g @invisibleloop/pulse
+mkdir my-project && cd my-project
+pulse
+```
+
+Running `pulse` in an empty directory scaffolds a new project and starts an AI coding session. Your agent has MCP tools and slash commands available from the first prompt.
+
+Full documentation: **[pulseframework.dev](https://pulseframework.dev)**
+
+## Key ideas
+
+**The spec is the source of truth.** Every page is a single JS object — data fetching, state, mutations, async actions, and view all in one place. No separate files for routes, controllers, or templates.
+
+**Performance is built in.** Streaming SSR, immutable asset caching, and zero layout shift are automatic. Every scaffolded project targets Lighthouse 100 across all four categories.
+
+**No client-side dependencies.** Pulse ships no runtime framework to the browser — only a small hydration bundle (~2 kB brotli) that binds your spec's mutations and actions to the DOM.
+
+**AI-native.** The CLI starts an MCP server alongside the dev server, giving the coding agent tools to create pages, validate specs, and run Lighthouse audits — all without leaving the editor.
+
+## CLI
+
+```bash
+pulse              # scaffold a new project or start AI session
+pulse dev          # dev server (default port 3000)
+pulse build        # production build → public/dist/
+pulse start        # production server
+```
+
+## Docs
+
+Full reference at [pulseframework.dev](https://pulseframework.dev):
+
+- **Getting started** — install, scaffold, first page
+- **The spec** — full reference for every property
+- **State, mutations, actions** — client interactivity
+- **Server data** — async data fetching before render
+- **Routing** — dynamic routes and URL params
+- **Streaming SSR** — shell + deferred segments
+- **Caching** — per-page TTL and HTTP cache headers
+- **Guard** — authentication and authorisation before data fetches
+- **Validation & constraints** — declarative form validation and state bounds
+- **Raw responses** — RSS feeds, sitemaps, JSON APIs
+- **Performance** — how the framework hits Lighthouse 100
+- **UI components** — 50+ built-in components
+
+## Status
+
+This is an early-access release. The core architecture is stable and production-quality, but the API may evolve before v1. Feedback and issues welcome on [GitHub](https://github.com/invisibleloop/pulse).
+
+## License
+
+MIT

package/docs/.claude/pulse-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/docs/public/.pulse-ui-version

@@ -0,0 +1 @@
+0.1.20