@invisibleloop/pulse 0.1.21

package/.claude/commands/build-page.md

@@ -0,0 +1,59 @@
+# Build Page
+
+Scaffold a new Pulse page spec, validate it, and visually confirm it renders correctly.
+
+## What to build
+
+$ARGUMENTS
+
+## Steps — follow in order
+
+### 1. Check existing components
+
+Read `src/ui/index.js` to see what UI components are available before writing any HTML. Note which components apply to this page.
+
+### 2. Plan
+
+State before writing any files:
+- The route (e.g. `/dashboard`)
+- The file path (e.g. `src/pages/dashboard.js`)
+- State shape
+- Mutations and/or actions needed
+- Which UI components will be used
+- Whether `server` data fetchers are needed
+- Whether `hydrate` is required (yes, if any mutations/actions)
+
+### 3. Build the spec
+
+Write the spec file. Follow these rules:
+- Use `class` not `className`, template literals not JSX
+- No React imports, hooks, or patterns — see CLAUDE.md "Pulse vs React" table
+- Use components from `src/ui/` — do not hand-write HTML that a component already covers
+- Include `hydrate` if the spec has mutations or actions
+- Use optional chaining (`?.`) on any server data that could be null
+- Escape any user-supplied values interpolated into HTML
+
+### 4. Validate
+
+Use `pulse_validate` on the spec. Fix any errors before continuing.
+
+### 5. Register with the server
+
+Check the project's server entry file (e.g. `src/server.js` or `pulse.config.js`) and add the new spec if needed.
+
+### 6. Screenshot
+
+Use `mcp__chrome-devtools__navigate_page` to load the page, then `mcp__chrome-devtools__take_screenshot`.
+
+Check for:
+- Page renders without a blank screen or error
+- Layout looks correct
+- No console errors via `mcp__chrome-devtools__list_console_messages`
+
+### 7. Run the checklist
+
+Go through `src/agent/checklist.md` and confirm every applicable point passes. Fix anything that fails.
+
+### 8. Report
+
+Summarise what was built, what components were used, and confirm validation + visual check passed.

package/.claude/commands/new-doc-page.md

@@ -0,0 +1,45 @@
+# New Docs Page
+
+Create a new documentation page for the Pulse docs site.
+
+## What to build
+
+$ARGUMENTS
+
+## Steps — follow in order
+
+### 1. Research
+- Read `docs/src/lib/nav.js` to understand the full nav structure and find where the new page fits
+- Read 2–3 adjacent pages (the pages that will be `prev`/`next` neighbours) to match tone, section depth, and helper usage (`h1`, `lead`, `section`, `sub`, `codeBlock`, `callout`, `table`)
+- Read `docs/src/lib/layout.js` exported functions to confirm available helpers
+- If the feature being documented has a source file (e.g. in `src/`), read it to ensure accuracy
+
+### 2. Plan
+Before writing any files, state:
+- The route (e.g. `/request-bodies`)
+- Where it sits in the nav (section, between which two pages)
+- Sections the page will cover (IDs + titles)
+- Any doc pages that need updating to link to or mention this page
+
+Wait for approval if anything is uncertain.
+
+### 3. Implement
+
+**a) Write the page file** at `docs/src/pages/<name>.js`:
+- Import from `../lib/layout.js`, `../lib/nav.js`, `../lib/highlight.js`
+- Use `prevNext('/your-route')` for prev/next links
+- Export a valid Pulse spec as `export default { route, meta, state, view }`
+- `meta.styles` must be `['/docs.css']`
+- Use `renderLayout({ currentHref, prev, next, content })` for the page body
+- All code examples must use `${codeBlock(highlight(\`...\`, 'js'))}` — never raw `<pre>`
+- Tables use `${table(['Col1', 'Col2'], [['val', 'val']])}`
+- Callouts use `${callout('note|tip|warning|info', 'text')}`
+- Section anchors use `${section('anchor-id', 'Section Title')}`
+
+**b) Register in nav** — add the entry to `docs/src/lib/nav.js` in the correct position
+
+**c) Verify syntax** — run `node --check docs/src/pages/<name>.js`
+
+**d) Check neighbours** — read the prev and next pages. If they reference topics this new page covers, add a cross-link.
+
+**e) Final check** — confirm the new route appears in `prevNext` output for its neighbours (the nav order drives prev/next automatically, so adding to NAV is sufficient).

package/.claude/commands/verify.md

@@ -0,0 +1,52 @@
+# 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. Console errors
+
+Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
+
+### 8. 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.
+
+### 9. 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
+- Console: any errors
+
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, and there are no console errors. Otherwise, fix and run `/verify` again.

package/.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/.claude/settings.local.json

@@ -0,0 +1,102 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__chrome-devtools__navigate_page",
+      "mcp__chrome-devtools__evaluate_script",
+      "Bash(grep:*)",
+      "mcp__chrome-devtools__list_console_messages",
+      "mcp__chrome-devtools__take_screenshot",
+      "Bash(pkill -f \"docs/server.js\")",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:4000/)",
+      "Bash(node:*)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Read(//Users/andy.stubbs/Repos/AS/pulse2/src/ui/**)",
+      "Bash(/dev/null done:*)",
+      "Bash(mkdir -p /Users/andy.stubbs/Repos/AS/agent-test/.claude)",
+      "Bash(mv /Users/andy.stubbs/Repos/AS/agent-test/CLAUDE.md /Users/andy.stubbs/Repos/AS/agent-test/.claude/CLAUDE.md)",
+      "Read(//Users/andy.stubbs/Repos/AS/agent-test-3/public/**)",
+      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/public/*.css /Users/andy.stubbs/Repos/AS/pulse2/public/*.js)",
+      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/agent-test-3/public/pulse-ui.css)",
+      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.js /Users/andy.stubbs/Repos/AS/agent-test-3/public/pulse-ui.js)",
+      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/agent-test/public/pulse-ui.css)",
+      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/my-amazing-pulse-project/public/pulse-ui.css)",
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "Bash(git config:*)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:4000)",
+      "Bash(curl:*)",
+      "Bash(xargs kill:*)",
+      "mcp__chrome-devtools__lighthouse_audit",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git pull:*)",
+      "Bash(git stash:*)",
+      "Bash(__NEW_LINE_9ac7abf2e7b711bb__ node -e \":*)",
+      "Bash(python3:*)",
+      "mcp__chrome-devtools__list_pages",
+      "mcp__chrome-devtools__emulate",
+      "Bash(npx tsc:*)",
+      "Bash(find /Users/andy.stubbs/.claude -name *.json)",
+      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/src/**/*.test.js)",
+      "mcp__chrome-devtools__list_network_requests",
+      "mcp__chrome-devtools__get_network_request",
+      "Bash(find /Users/andy.stubbs/Repos/AS/forge -name *.md -o -name *.txt)",
+      "Bash(node_modules/.bin/tsc --noEmit)",
+      "Bash(/Users/andy.stubbs/Repos/AS/forge/node_modules/.bin/tsc --noEmit --project /Users/andy.stubbs/Repos/AS/forge/tsconfig.json)",
+      "WebFetch(domain:localhost)",
+      "Skill(update-config)",
+      "Bash(jq:*)",
+      "Bash(ls /Users/andy.stubbs/Repos/AS/tasty/.claude/ grep -r \"pulse-dev\\\\|pulse-stop\\\\|pulse-build\\\\|pulse-start\\\\|Pulse project\" /Users/andy.stubbs/Repos/AS/tasty/.claude/ 2)",
+      "Bash(/dev/null grep:*)",
+      "Bash(ls -1 /Users/andy.stubbs/Repos/AS/pulse2/src/ui/*.js)",
+      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/*.js)",
+      "Bash(wc -c /Users/andy.stubbs/Repos/AS/pulse2/src/agent/guide-*.md)",
+      "Bash(npx:*)",
+      "Bash(npm install:*)",
+      "Bash(./node_modules/.bin/tsc --noEmit --strict --moduleResolution bundler --module esnext --target esnext --allowJs false --skipLibCheck false types/schema.d.ts types/server.d.ts types/runtime.d.ts types/navigate.d.ts types/ssr.d.ts types/html.d.ts types/image.d.ts types/ui.d.ts types/index.d.ts 2>&1)",
+      "Bash(./node_modules/.bin/tsc --noEmit --strict --moduleResolution bundler --module esnext --target esnext --allowJs false --lib esnext,dom types/schema.d.ts types/server.d.ts types/runtime.d.ts types/navigate.d.ts types/ssr.d.ts types/html.d.ts types/image.d.ts types/ui.d.ts types/index.d.ts 2>&1)",
+      "Bash(/Users/andy.stubbs/Repos/AS/pulse2/node_modules/.bin/tsc -p /tmp/tsconfig_test.json 2>&1)",
+      "Bash(find /Users/andy.stubbs/Repos/AS/pulse2 -name *.test.js -type f)",
+      "Bash(wc:*)",
+      "Bash(ls -1 *.js)",
+      "Bash(grep -l \"<h[2-6]\" /Users/andy.stubbs/Repos/AS/pulse2/src/ui/*.js)",
+      "Bash(node --input-type=module --eval \"import ''''/Users/andy.stubbs/Repos/AS/pulse2/src/cli/scaffold.js''''\")",
+      "Bash(head -10 grep -n \"level\\\\|heading\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/section.js)",
+      "Bash(head -10 grep -n \"level\\\\|heading\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/modal.js)",
+      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|flush\\\\|center\\\\|highlighted\\\\|eyebrow\\\\|align\\\\|size.*md\\\\|ui-modal\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/modal.js)",
+      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|eyebrow\\\\|padding\\\\|variant\\\\|subtitle\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/section.js)",
+      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|highlighted\\\\|badge\\\\|period\\\\|features\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/pricing.js)",
+      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|eyebrow\\\\|subtitle\\\\|actions\\\\|align\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/cta.js)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(xargs node:*)",
+      "Bash(find /Users/andy.stubbs/Repos/AS/ultimate-demo/twizzer -name server.js -o -name *.config.*)",
+      "Bash(xargs ls:*)",
+      "Bash(xargs -I{} lsof -p {})",
+      "Bash(brotli --best -c /Users/andy.stubbs/Repos/AS/ultimate-demo/twizzer/public/dist/home.boot-TJOPUIR4.js)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "Bash(ls:*)",
+      "Bash(git -C /Users/andy.stubbs/Repos/AS/pulse2 log --follow --diff-filter=A --format=\"%ar\" -- public/dist/runtime-YLZ4ZGK4.js)",
+      "Read(//Users/andy.stubbs/Repos/AS/pulse2/**)",
+      "Bash(GetFileInfo /Users/andy.stubbs/Repos/AS/pulse2/public/dist/runtime-YLZ4ZGK4.js)",
+      "mcp__chrome-devtools__performance_start_trace",
+      "Bash(pkill -f docs/server.js)",
+      "Bash(sleep 1 node -e \":*)",
+      "mcp__chrome-devtools__close_page",
+      "mcp__chrome-devtools__fill",
+      "mcp__chrome-devtools__click",
+      "mcp__chrome-devtools__take_snapshot",
+      "mcp__chrome-devtools__type_text",
+      "Bash(head -5 grep -n \"section\\\\|container\" /Users/andy.stubbs/Repos/AS/pulse2/src/ui/index.js)",
+      "Bash(head -35 grep \"ui-section-header\\\\|ui-section-title\\\\|ui-section-eyebrow\\\\|ui-section--\" /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css)",
+      "mcp__chrome-devtools__performance_analyze_insight",
+      "Bash(git checkout:*)",
+      "Bash(git branch:*)",
+      "Bash(gh run:*)",
+      "Bash(xargs -I{} gh run delete {} --repo invisibleloop/pulse-framework)",
+      "Bash(gh api:*)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump
+        type: choice
+        options: [patch, minor, major]
+        default: patch
+        required: true
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - run: npm test
+
+      - name: Bump version and tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          npm version ${{ inputs.bump }} -m "chore: release %s [skip ci]"
+          git push --follow-tags
+
+      - run: npm publish --provenance

package/.pulse/load-reports/home/1773432711417.json

@@ -0,0 +1,22 @@
+{
+  "timestamp": "2026-03-13T20:11:51.416Z",
+  "url": "http://localhost:4000/",
+  "config": {
+    "duration": 3,
+    "connections": 5
+  },
+  "rps": 17570.5,
+  "latency": {
+    "mean": 0.2,
+    "p50": 0,
+    "p95": 1,
+    "p99": 1,
+    "max": 16
+  },
+  "requests": {
+    "total": 61655,
+    "success": 61655,
+    "errors": 0
+  },
+  "duration": 3.5
+}