@invisibleloop/pulse 0.20.10 → 0.20.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.10",
+  "version": "0.20.19",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -61,10 +61,10 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
     "typecheck": "tsc --noEmit",
-    "docs": "node --watch src/cli/dev.js --root docs --port 4000",
-    "docs:start": "node docs/server.js"
+    "docs": "node --watch src/cli/dev.js --root ../../docs --port 4000",
+    "docs:start": "node ../../docs/server.js"
   },
   "engines": {
     "node": ">=22"
@@ -75,7 +75,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/invisibleloop/pulse-framework"
+    "url": "https://github.com/invisibleloop/pulse-framework",
+    "directory": "packages/pulse"
   },
   "publishConfig": {
     "access": "public"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.10
+0.20.19

package/scripts/build.js

@@ -59,6 +59,24 @@ function stripServerOnlyKeys(source) {
   return source
 }
 
+/**
+ * A page needs a client boot bundle only if it needs hydration — matches
+ * discover.js's needsHydration() exactly (mutations || actions || persist ||
+ * store). Call this on source that has already had stripServerOnlyKeys/Imports
+ * applied, and that has already been confirmed to have a `view:` key
+ * (a view alone is necessary but not sufficient — a purely server-rendered
+ * page, e.g. a redirect handler or a spec.submit-only form, has a view and
+ * no hydration need at all).
+ *
+ * `store` counts even with no local mutations/actions: mount() is what wires
+ * up data-store-event dispatch AND the live SSE store-push subscription — a
+ * store-only page with no client bundle would silently never receive
+ * pushStore() broadcasts and have a dead data-store-event button.
+ */
+function needsClientBundle(strippedSource) {
+  return /\b(mutations|actions|persist|store)\s*:/.test(strippedSource)
+}
+
 /**
  * Strip import statements for server-only modules and any top-level
  * variable declarations whose right-hand side calls the imported names.
@@ -456,6 +474,14 @@ const bootstrapFiles = pages.flatMap(({ filePath }) => {
   const source   = fs.readFileSync(filePath, 'utf8')
   const stripped = stripServerOnlyImports(stripServerOnlyKeys(source))
   if (!/\bview\s*:/.test(stripped)) return []
+  // A view alone doesn't need hydration — see needsClientBundle's doc comment.
+  // Without this, a purely server-rendered page (a redirect handler, a custom
+  // 404, any spec.submit-only page) got a client bundle generated anyway —
+  // wasted build output that's silently never referenced, and worse, a real
+  // build failure if that page imports a local server-only helper module
+  // (e.g. a persistence layer using node:fs) that esbuild then tries to
+  // bundle for the browser.
+  if (!needsClientBundle(stripped)) return []
 
   // Use the path relative to src/pages/ so nested pages get unique names.
   // e.g. src/pages/api/products.js → 'api--products' (not 'products')

package/scripts/release-version.js

@@ -2,29 +2,38 @@
 /**
  * Determine the next version from conventional commits.
  *
- * Reads all commits since the last "chore: release X.Y.Z [skip ci]" commit,
- * applies conventional commit rules to determine the bump level, then prints
- * the new version string to stdout.
+ * Reads all commits since the last "chore: release X.Y.Z [skip ci]" commit
+ * that touched packages/pulse, applies conventional commit rules to
+ * determine the bump level, then prints the new version string to stdout.
  *
  * Bump rules:
  *   BREAKING CHANGE footer or "type!:" prefix  →  major
  *   feat:                                       →  minor
  *   anything else (fix, perf, chore, docs…)    →  patch
  *
- * Usage: node scripts/release-version.js
+ * Scoped to `-- packages/pulse`: this repo is a monorepo where sibling
+ * packages could share the same git history — without the path filter, a
+ * commit that only touches a sibling package would incorrectly drive a
+ * version bump for the @invisibleloop/pulse framework package.
+ *
+ * Usage: node scripts/release-version.js (run from packages/pulse/)
  */
 
 import { execSync } from 'child_process'
 import { readFileSync } from 'fs'
+import path from 'path'
 
-const pkg     = JSON.parse(readFileSync('package.json', 'utf8'))
+const PKG_DIR = path.resolve(import.meta.dirname, '..')
+const pkg     = JSON.parse(readFileSync(path.join(PKG_DIR, 'package.json'), 'utf8'))
 const [major, minor, patch] = pkg.version.split('.').map(Number)
 
-// Collect commit subjects since the last release commit.
-// git log outputs newest-first; we stop at the first release commit we see.
+// Collect commit subjects since the last release commit that touched this
+// package. git log outputs newest-first; we stop at the first release
+// commit we see. Must be run with cwd inside the repo (any subdirectory) —
+// `-- packages/pulse` is resolved relative to the repo root by git itself.
 let commits = []
 try {
-  const log = execSync('git log --pretty=format:%s', { encoding: 'utf8' }).trim()
+  const log = execSync('git log --pretty=format:%s -- packages/pulse', { encoding: 'utf8' }).trim()
   for (const line of log.split('\n')) {
     if (/^chore: release \d+\.\d+\.\d+/.test(line)) break
     if (line) commits.push(line)

package/scripts/strip-server.test.js

@@ -50,6 +50,11 @@ function strip(source) {
   return stripServerOnlyImports(stripServerOnlyKeys(source))
 }
 
+// Mirrors needsClientBundle() in build.js exactly — see its doc comment there.
+function needsClientBundle(strippedSource) {
+  return /\b(mutations|actions|persist|store)\s*:/.test(strippedSource)
+}
+
 function isInsideString(source, pos) {
   let i = 0
   const stack = []
@@ -425,6 +430,61 @@ test('subpath imports (/ui) are NOT stripped by the root entry',
   `import { button } from '@invisibleloop/pulse/ui'\nexport default {\n  route: '/x',\n  view: () => button({ label: 'x' }),\n}`
 )
 
+// ---------------------------------------------------------------------------
+// needsClientBundle — must match discover.js's needsHydration() exactly.
+// Regression: found via dogfooding. This check used to be "does the spec have
+// a `view:` key" alone, so a purely server-rendered page (a redirect handler,
+// a custom 404, a spec.submit-only form) still got a client bundle generated —
+// and if that page imported a local server-only helper module (e.g. a
+// node:fs-based persistence layer), the production build failed outright when
+// esbuild tried to bundle Node built-ins for the browser.
+// ---------------------------------------------------------------------------
+
+console.log('\nneedsClientBundle — matches discover.js hydration logic\n')
+
+function boolTest(label, input, expected) {
+  const got = needsClientBundle(strip(input))
+  if (got === expected) {
+    console.log('  ✓ ' + label)
+    pass++
+  } else {
+    console.log('  ✗ ' + label)
+    console.log('    expected: ' + expected)
+    console.log('    got:      ' + got)
+    fail++
+  }
+}
+
+boolTest('a view-only spec (no mutations/actions/persist) does not need a bundle — the exact bug this fixes',
+  `export default {\n  route: '/:code',\n  guard: async (ctx) => {},\n  view: () => '',\n}`,
+  false
+)
+
+boolTest('a spec.submit-only page does not need a bundle',
+  `export default {\n  route: '/',\n  submit: async (ctx) => ({ redirect: '/' }),\n  view: () => '',\n}`,
+  false
+)
+
+boolTest('mutations require a bundle',
+  `export default {\n  route: '/x',\n  state: {},\n  mutations: {\n    inc: (s) => ({ n: s.n + 1 }),\n  },\n  view: () => '',\n}`,
+  true
+)
+
+boolTest('actions require a bundle',
+  `export default {\n  route: '/x',\n  state: {},\n  actions: {\n    save: { run: async () => {} },\n  },\n  view: () => '',\n}`,
+  true
+)
+
+boolTest('persist requires a bundle',
+  `export default {\n  route: '/x',\n  state: { count: 0 },\n  persist: ['count'],\n  view: () => '',\n}`,
+  true
+)
+
+boolTest('store alone (no local mutations/actions) requires a bundle — regression: mount() is what wires up data-store-event dispatch AND the live SSE store-push subscription; a store-only page with no client bundle would silently never receive pushStore() broadcasts and have a dead data-store-event button',
+  `export default {\n  route: '/x',\n  store: ['count'],\n  state: {},\n  view: (state, server) => \`\${server.count}\`,\n}`,
+  true
+)
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)

package/src/agent/checklist.md

@@ -2,6 +2,8 @@
 
 Before finishing any spec, verify every point below. Fix anything that fails.
 
+**Most of these are already mechanically checked** by `pulse_review` (auto-checked items: hex colours, tabindex, `data-event` on inputs, React patterns, main landmark, XSS test presence, modal-state pattern, CSRF token presence, `_storeUpdate` shape, creative-override detection). Where a rule is auto-checked, this file states *why* the rule exists and how to judge edge cases (e.g. "is this a real creative override?") — it does not restate the mechanical check itself. Rules with no entry below in "Auto-checked" are prose-only — nothing catches them but you.
+
 ### 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 `{}`.
@@ -37,15 +39,9 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   - 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, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. When taking this path:
-  - **Declare it in a comment at the top of the spec** so the reviewer recognises it: `// component-free — creative override: <reason>`. This is the signal the review tool reads.
-  - 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: **Lighthouse 100 on Accessibility, Best Practices, and SEO — desktop and mobile — plus CLS 0.00 is the pass bar.** (Performance is reported but not gated; it varies with machine load.) A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
-
-- **When reviewing**: before flagging a class name like `.hero` as a violation, first ask whether the `hero()` component could actually reproduce the layout. If the answer is no, it is a creative override — check Lighthouse instead of refactoring. Do not flatten a good custom layout into a generic component just to clear a pattern-match.
+- **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, or a layout that requires features a component simply doesn't support (e.g. full-viewport height, custom gradient glows, clamp-scaled display type). This is a deliberate design decision, not a shortcut. **Declare it in a comment at the top of the spec** — `// component-free — creative override: <reason>` — that's the only signal `pulse_review` reads to switch component checks from failures to advisory. Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there's a specific design reason not to. The quality gate replaces the component checklist: Lighthouse 100 on Accessibility/Best Practices/SEO, desktop and mobile, plus CLS 0.00.
 
-- **The review tool auto-detects creative override** from the spec comment. When detected, component pattern checks are shown as advisory (`⚡`) not as failures, and the Lighthouse gate is the stated pass bar.
+- **The judgment call, not the mechanics:** before flagging a class name like `.hero` as a violation, ask whether the `hero()` component could actually reproduce the layout. If no, it's a legitimate creative override — check Lighthouse instead of refactoring. Don't flatten a good custom layout into a generic component just to clear a pattern-match.
 
 - **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.
 
@@ -76,7 +72,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - `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:
+- **Never use `state.modalOpen` or conditional modal rendering** (auto-checked). 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: '...' })}
@@ -105,14 +101,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### 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.
+- **`app.css` must contain no hex values or raw colour values** (auto-checked, lint hook also blocks 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.
 - **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 
 - Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.
-- **Every `<form method="POST">` on a `submit` page includes `${server.csrf}`.** CSRF is enforced — a form without the hidden token field gets 403 on submit. Never set `csrf: false` to "fix" a 403; that disables the protection. `csrf: false` is only for endpoints with their own authentication (e.g. signed webhooks).
+- **Every `<form method="POST">` on a `submit` page includes `${server.csrf}`** (auto-checked). CSRF is enforced — a form without the hidden token field gets 403 on submit. Never set `csrf: false` to "fix" a 403; that disables the protection. `csrf: false` is only for endpoints with their own authentication (e.g. signed webhooks).
 - **`submit` returns `{ redirect }` after a successful mutation** (POST-redirect-GET). Rendering success directly from the POST means browser refresh resubmits the form.
 
 ### Server-side forms & error pages
@@ -162,7 +158,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### 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:
+- **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. It must be an object, not a primitive (auto-checked). All mounted pages that subscribe to the affected keys re-render immediately:
   ```js
   onSuccess: (state, theme) => ({
     saved:        true,

package/src/agent/commands/pulse-start.md

@@ -9,3 +9,5 @@ pulse start --port 3001
 If `pulse.config.js` sets a custom `port`, use that value + 1 instead.
 
 > **Why the flag:** plain `pulse start` binds the configured port (3000) because in real deployment it is the only server and platforms inject `PORT`. Locally that collides with the dev server and breaks the convention used by `pulse_build`, Lighthouse, and the performance trace — production is always dev port + 1. Never use `--port` in actual deployment.
+
+**If the server doesn't come up on the port you expected:** check whether a `PORT` environment variable is set in this shell (`echo $PORT`) — it silently overrides `--port` (correct behavior for real PaaS deployment, where the platform's injected `PORT` must always win, but a stray local `PORT` from a sandbox/CI/shell profile will do the same thing here with no indication why). `pulse start` now warns to stderr when this happens; if you see that warning, either unset `PORT` for this session or work with whatever port it actually bound to.

package/src/agent/commands/verify.md

@@ -40,18 +40,33 @@ Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chr
 
 **Pre-flight (required before every Lighthouse run):**
 1. Call `pulse_build` to produce a production build and start the production server on port 3001.
-2. Call `navigate_page` with `url: "http://localhost:3001/"` so the browser is on the production server.
+2. Call `pulse_check_bundles` — reads the actual generated bundle files, not just their sizes. Lighthouse scores can pass on a bundle that shouldn't exist at all (a page with no mutations/actions/persist that got a boot file anyway) or one containing leaked server-only code — neither shows up as a score failure. If it flags anything, fix it and restart from step 3.
+3. Call `navigate_page` with `url: "http://localhost:3001/"` so the browser is on the production server.
 
 Then run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "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 3.
 
+Keep the score numbers from this run — step 7a saves both desktop and mobile together.
+
 ### 7. Lighthouse — mobile *(skip in quick mode)*
 
 The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__chrome-devtools__lighthouse_audit` with `{ "device": "mobile" }`.
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
+### 7a. Save the Lighthouse reports *(skip in quick mode — do not skip this if you ran steps 6–7)*
+
+**This is a required step, not optional narrative — a Lighthouse run that passes step 6/7 and skips this one leaves no record anywhere except this conversation.** `pulse report-server` and any dashboard watching `.pulse/reports/` (including a companion app) read only what actually got saved to disk; reporting scores in chat is not the same as saving them, no matter how many times `/verify` passes.
+
+Run one `Bash` call per device — **not an MCP tool call**, and run from the project root (the directory containing `pulse.config.js`):
+
+```
+pulse save-report --url "http://localhost:3001/<route>" --data '{"scores":{"performance":<N>,"accessibility":100,"bestPractices":100,"seo":100},"metrics":{"lcp":<N>,"cls":<N>,"fcp":<N>,"tbt":<N>}}'
+```
+
+Use the real numbers from step 6's result for one call and step 7's result for a second call. `<route>` is the page's route (`/` for the homepage). Confirm each call printed `✓ Report saved for ... (slug: ...)` — if it errored, fix the command and retry before moving on; do not silently continue to step 8 with an unsaved report.
+
 **Stay on the production server (port 3001)** — steps 8 and 9 use it too. Do not call `pulse_restart_server` yet.
 
 ### 8. Mobile layout check *(skip in quick mode)*
@@ -88,9 +103,7 @@ Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexp
 
 ### 11. Code review
 
-Call `pulse_review` with the spec file path. This runs a full code review AND atomically writes the `.pulse-verified` stamp server-side, eliminating any race condition with the stop hook.
-
-Work through every item the review returns. Fix anything that fails before proceeding.
+Call `pulse_review` with the spec file path. Work through every item the review returns. Fix anything that fails before proceeding.
 
 ### 12. Close extra browser tabs
 
@@ -98,20 +111,29 @@ Use `mcp__chrome-devtools__list_pages` to get all open pages. Close every page *
 
 If there is only one page open, skip this step — there is nothing to close.
 
-### 13. Write verification stamp
+### 13. Check for unresolved errors on this route
+
+Call `pulse_diagnose` with `{ route: "<this page's route>" }`. If it returns any unresolved entries, **do not proceed to step 14** — something threw during this session that hasn't been addressed. Fix the underlying issue and restart from step 3.
+
+If it returns none, continue — `pulse_stamp` in the next step auto-resolves any journal entries for this route, since a clean pass this far means whatever was flagged either wasn't real or has already been fixed by an earlier step in this loop.
+
+### 14. Write verification stamp
+
+Call `pulse_stamp` with `{ route: "<this page's route>", mode: "full" }` in full mode, or just `{ route: "<this page's route>" }` in quick mode (quick never runs Lighthouse, so there's nothing to check). This writes `.pulse-verified` via the MCP server, which is more reliable than the `date +%s` shell command — the MCP write always lands after all spec edits, avoiding the mtime race condition that can cause the stop hook to block immediately after verification. It also marks any error-journal entries for this route as resolved.
 
-Call `pulse_stamp`. This writes `.pulse-verified` via the MCP server, which is more reliable than the `date +%s` shell command — the MCP write always lands after all spec edits, avoiding the mtime race condition that can cause the stop hook to block immediately after verification.
+**In full mode, `pulse_stamp` refuses to write the stamp unless it finds a Lighthouse report actually saved for this route in the last 10 minutes** (i.e. step 7a genuinely happened, not just step 6/7's scores existing in this conversation). If it refuses, go back and run the missing `pulse save-report` call(s) from step 7a, then call `pulse_stamp` again — do not work around the refusal any other way.
 
 **This must be the last operation before stopping.** The stop hook compares each edited spec's mtime against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after calling `pulse_stamp`.
 
-### 14. Report
+### 15. Report
 
 Summarise:
 - Validation: pass or fail (with errors if any)
 - Visual: desktop screenshot — any issues found and fixed
 - Console: any errors
 - Review: pass or issues found and fixed
-- **Full mode only:** Lighthouse desktop/mobile scores, mobile layout check, LCP and CLS values
+- Error journal: clean, or resolved N entries
+- **Full mode only:** bundle content check (clean, or issues found and fixed), Lighthouse desktop/mobile scores, whether both were saved via `pulse save-report` (step 7a), mobile layout check, LCP and CLS values
 
 In quick mode, end with: "Quick check passed — run `/verify` when you're ready for the full Lighthouse audit."
 

package/src/agent/guide-components.md

@@ -157,7 +157,7 @@ To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(
 | `stat` | `label`, `value`, `change`, `trend` (up/down/neutral), `size` (sm/md/lg — lg for hero KPIs), `center` |
 | `avatar` | `src`, `alt`, `size` (sm/md/lg/xl), `initials` |
 | `empty` | `title`, `description`, `action` ({label,href,variant}) |
-| `table` | `headers`, `rows` (2D array of HTML strings), `caption` | ⚠ Each cell item must be **raw HTML content** — `table()` wraps each item in `<td>` itself. Do NOT pass `<td>...</td>` strings or you will get double-nested cells. |
+| `table` | `headers`, `rows` (2D array of HTML strings), `caption` | ⚠ Each cell item must be **raw HTML content** — `table()` wraps each item in `<td>` itself. Do NOT pass `<td>...</td>` strings or you will get double-nested cells. Raw HTML you put in a cell (a `<a>` link, a `<button>`, anything) gets **no styling from the component** — `table()` only styles the table structure, not injected content. A bare `<a href="...">text</a>` in a cell falls back to the browser's default link blue, which fails contrast on a dark theme. Style it explicitly (`color: var(--ui-accent)`, `:hover { color: var(--ui-accent-hover) }`) the same as any raw HTML you'd write directly in a view. |
 | `spinner` | `size` (sm/md/lg), `color` (accent/muted/white), `label` |
 | `progress` | `value`, `max` (100), `label`, `showLabel`, `showValue`, `variant`, `size` |
 | `breadcrumbs` | `items` ([{label,href}] — last item has no href), `separator` |
@@ -229,32 +229,14 @@ ${heading({ level: 1, text: 'In Search of Lost Code', class: 'display-heading' }
 
 #### When components feel restrictive
 
-**Symptom:** You're fighting a component's wrapper styles (padding, max-width, centering) in your CSS overrides.
+Symptom: fighting a component's wrapper styles (padding, max-width, centering) in CSS overrides. Fix, in order of preference:
+1. Editorial/typographic page → compose from `heading()`, `prose()`, raw HTML (creative override) instead of forcing `hero()`/`feature()`/`cta()` into that shape.
+2. Structure diverges significantly (asymmetric grid, full-bleed, custom positioning) → write the outer HTML yourself; still use components for primitives (`button`, `card`, `input`, `badge`).
+3. Only cosmetic → override with higher specificity in `app.css`: `.my-editorial-hero .ui-hero-inner { max-width: none; padding: 0; }` (component wrappers use single class names like `.ui-hero`).
 
-**Solutions:**
-1. **Use the right approach for your design.** If the page is editorial/typographic, compose from `heading()`, `prose()`, and raw HTML (creative override) instead of trying to force `hero()`, `feature()`, `cta()` into an editorial shape.
-2. **Write custom markup for structural differences.** Components provide sensible defaults for common patterns. When your design structure diverges significantly (asymmetric grid, full-bleed sections, custom positioning), write the HTML directly — that's permitted for layouts. Use components for the UI primitives (`button`, `card`, `input`, `badge`), but write the outer structure yourself.
-3. **Override with higher specificity.** Component wrappers use single class names (`.ui-hero`, `.ui-cta`). Override with a more specific selector in your `app.css`:
-   ```css
-   .my-editorial-hero .ui-hero-inner {
-     max-width: none;
-     padding: 0;
-   }
-   ```
+#### Vibes are a paint job, not a structural transformation
 
-Components are opinionated by design — they enforce accessibility, consistency, and tested patterns. When the design requires breaking those patterns, prefer custom markup over fighting the component.
-
-#### Important: Vibes affect CSS tokens, not component HTML structure
-
-The `meta.vibe` setting (`warm`, `editorial`, `playful`, `minimal`, `bold`, `brutalist`, `retro`, `corporate`, `neon`, `paper`) applies CSS variable overrides via `data-vibe` on the `<body>` element. This changes **visual styling** — border radius, font size, letter-spacing, heading weight — but does **not** change the **HTML structure** of components.
-
-For example:
-- `hero()` with `vibe: 'editorial'` still renders eyebrow + title + subtitle + actions (SaaS structure)
-- The vibe adjusts the font sizes, tracking, and spacing, but the component HTML is unchanged
-
-**If you need different HTML structure for an editorial design** — e.g., a large display title + asymmetric layout + drop cap instead of eyebrow/subtitle/actions — write custom markup styled with `heading()`/`prose()` plus utility classes or `app.css`. Do not expect `hero()` to become structurally editorial when `vibe: 'editorial'` is set.
-
-This is by design: vibes are a paint job, not a structural transformation. Components stay predictable and testable. When the design structure itself differs from the SaaS patterns (centred hero, three-column features, pricing cards), reach for custom layout instead of trying to force `hero()` / `feature()` / `cta()` into shapes they weren't designed for.
+`meta.vibe` (`warm`/`editorial`/`playful`/`minimal`/`bold`/`brutalist`/`retro`/`corporate`/`neon`/`paper`) sets `data-vibe` on `<body>` — changes radius/font-size/letter-spacing/weight tokens only. **Never changes component HTML structure.** `hero({ vibe: 'editorial' })` still renders eyebrow+title+subtitle+actions — vibe ≠ structural editorial layout. For a genuinely different structure (large display title + asymmetric layout + drop cap instead of eyebrow/subtitle/actions), write custom markup with `heading()`/`prose()` + utility classes — don't expect the vibe setting to produce it.
 
 ### Landing page components
 

package/src/agent/guide-routing.md

@@ -89,18 +89,6 @@ Use the global store (`pulse.store.js`) for state that needs to be consistent ac
 
 See `pulse://guide/server` for the full store API.
 
-## Site navigation
-
-Projects define navigation in src/components/layout.js via a NAV_LINKS array.
-To add a new page to the nav: edit NAV_LINKS in src/components/layout.js only — do NOT add links in individual page files.
-
-```js
-const NAV_LINKS = [
-  { label: 'Home', href: '/' },
-  { label: 'About', href: '/about' },  // ← add new pages here
-]
-```
-
 ## Page discovery — no registration needed
 
 Pulse automatically discovers every .js file under src/pages/ and registers it as a route. You NEVER need to edit a server.js or register specs manually. Just create the file and it is live.

package/src/agent/guide-server.md

@@ -80,6 +80,8 @@ All pages that declare `spec.store` with the affected keys re-render automatical
 - Page-level `server` keys win over store keys if there is a name collision
 - Pages with `spec.store` are never HTML-cached (same rule as pages with `spec.server`)
 
+**Testing `pulse.store.js` — put the test file next to it, at the project root, not under `src/`.** `npm test`'s glob covers `src/**/*.test.js` plus a root-level `*.test.js` specifically so `pulse.store.test.js` is picked up — a store test placed anywhere under `src/pages/` instead (following the page-test convention out of habit) still runs, but `pulse.store.test.js` itself only runs from the root. Import the store the normal relative way: `import store from '../pulse.store.js'` from `src/pages/`, or `import store from './pulse.store.js'` from the root.
+
 **Reactive updates — no refresh needed**
 
 Return `_storeUpdate` from a page action's `onSuccess` to push a change into the global store. All mounted pages that subscribe to the affected keys re-render immediately:
@@ -177,6 +179,87 @@ export default {
 - Escape user-submitted values before interpolating them into HTML (`escHtml`).
 - **Progressive enhancement:** add `data-action="send"` to the same form — hydrated visitors get the async action with no page reload; no-JS visitors fall back to the POST.
 - Multi-instance deployments: pass a stable `secret` to `createServer` (e.g. from an env var) so CSRF tokens issued by one instance validate on another.
+- **On a longer page, a form mid-page needs to scroll the success/error state into view after the redirect.** The 303 lands the browser at the top of the page — a success message rendered next to the form (or anywhere below the fold) is invisible until the visitor scrolls down manually, which they have no reason to do after just submitting. Give the form section an `id`, add `${server.form?.sent ? '<script nonce=\"${server.nonce}\">document.getElementById(\"contact-form\").scrollIntoView()</script>' : ''}` right after it, or simplest: `<form id="contact-form" method="POST">`. Don't skip this on a short/single-purpose page (the form IS the page, nothing to scroll past) — it only matters once the form sits below other content.
+
+## Server-side data persistence — outside the store and `spec.persist`
+
+Neither of Pulse's two built-in state mechanisms is durable, shared server-side storage:
+- `spec.persist` is **client-side** `localStorage`, scoped per route — gone if the visitor clears their browser, invisible to other visitors.
+- The global store (`pulse.store.js`) is **in-memory**, shared across connected clients via SSE, but reset on every server restart and never written to disk.
+
+For anything that needs to survive a restart and be shared across all requests — a URL shortener's code→URL map, a simple content store, any small dataset a form writes to — there's no built-in database, and the framework has no opinion on which one to use. **A JSON file on disk is a reasonable zero-dependency default for a small, low-concurrency dataset** (a few thousand records, not a high-write-throughput service); for anything bigger, bring your own database. Either way, write the persistence layer as its own module under `src/lib/`, imported from `guard`/`server`/`submit`/`actions.*.run` — never from the view.
+
+```js
+// src/lib/data-store.js — a minimal safe pattern for a small JSON-backed store
+import fs   from 'node:fs/promises'
+import path from 'node:path'
+
+const FILE = path.join(process.cwd(), 'data', 'store.json')
+let cache = null                 // in-memory, refreshed on write — avoids a disk read per request
+let writeQueue = Promise.resolve()  // serializes writes so concurrent requests can't interleave
+
+async function load() {
+  if (cache) return cache
+  try {
+    cache = JSON.parse(await fs.readFile(FILE, 'utf8'))
+  } catch {
+    cache = {}   // file doesn't exist yet — start empty
+  }
+  return cache
+}
+
+async function persist(next) {
+  // Atomic write: write to a temp file, then rename — rename is atomic on POSIX,
+  // so a crash mid-write can never leave a corrupt/partial file on disk.
+  const tmp = FILE + '.tmp'
+  await fs.mkdir(path.dirname(FILE), { recursive: true })
+  await fs.writeFile(tmp, JSON.stringify(next, null, 2))
+  await fs.rename(tmp, FILE)
+  cache = next
+}
+
+// Serialize every write through one promise chain — without this, two
+// concurrent requests can both read the same state, modify it separately,
+// and the second write silently clobbers the first (a classic lost update).
+export function mutate(fn) {
+  writeQueue = writeQueue.then(load).then(async (data) => {
+    const next = await fn(data)
+    await persist(next)
+    return next
+  })
+  return writeQueue
+}
+
+export const read = load
+```
+
+**Rules:**
+- Load-on-first-read, cache in memory, refresh the cache on every write — the hot path (a read-heavy redirect lookup, say) shouldn't hit disk on every request.
+- Serialize writes through a single promise queue, as above. This is single-process only — it does not protect against two separate server *instances* writing the same file; for multi-instance deployment, use a real database instead.
+- Write via temp-file-then-rename, never `fs.writeFile` directly to the real path — a process killed mid-write leaves the rename-source temp file intact and the real file untouched, not a half-written JSON file that fails to parse on next boot.
+- Add the data file to `.gitignore` — it's runtime state, not something to commit.
+- **This local helper module must not be imported into a page's `view` or client-side `mutations`/`actions`** — only into `guard`, `server` fetchers, `submit`, or an action's `run`. A local module using `node:fs` (or any Node built-in) that ends up reachable from client code will break the production build — see the next point.
+- **A page whose only server-side logic is `guard`/`submit`/`server` (no `mutations`, `actions`, or `persist`) gets zero client JS** — this is the normal, correct outcome for a redirect handler, a form-only page, or anything else that's purely server-rendered. If a build ever tries to bundle a local server-only module (e.g. you see esbuild choke on `node:fs` or similar), that's the build's hydration-need check misfiring, not something to work around in your spec — it should already match this rule.
+
+## Third-party inline scripts — `server.nonce`
+
+The framework auto-nonces its own inline `<script>` tags for CSP (`script-src` is nonce-restricted, not `'unsafe-inline'`). A hand-written `<script>` in a view — e.g. an ad network's or analytics tool's inline snippet that the framework doesn't generate itself — needs that same nonce or the browser blocks it as a CSP violation.
+
+`server.nonce` is the per-request CSP nonce, available in every view with no extra setup:
+
+```js
+view: (state, server) => `
+  <main id="main-content">
+    <script nonce="${server.nonce}">
+      (adsbygoogle = window.adsbygoogle || []).push({});
+    </script>
+  </main>`,
+```
+
+**Rules:**
+- Only covers **inline** `<script>` content. An external `<script src="...">` doesn't need a nonce at all — CSP's `script-src` origin allowlist (`csp: { 'script-src': ['https://example.com'] }` in `createServer`) gates those instead; add the third party's origin there.
+- Never hardcode a nonce value — it's per-request and regenerated on every response. `server.nonce` always reflects the current request's real value.
+- If the third party's own SDK tries to register a [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) policy (some ad networks do), the framework's CSP restricts `trusted-types` to its own `pulse` policy — that's a separate, unrelated CSP dimension from nonces and isn't solved by `server.nonce`. It **is** extendable via `csp: { 'trusted-types': ['policy-name'] }` (merges with `pulse`, doesn't replace it) — see "Third-party scripts" in `pulse://guide/styles` for the full pattern and the explicit trade-off it represents.
 
 ## Server context — redirects, cookies, POST bodies
 
@@ -208,12 +291,14 @@ Body parsing is available in `guard`, `server.*` fetchers, and `render` (raw spe
 ```js
 await ctx.json()      // parse JSON body → object | null
 await ctx.text()      // raw string body → string
-await ctx.formData()  // URL-encoded body → plain object | null
+await ctx.formData()  // URL-encoded body → plain object | null — NOT a FormData, see below
 await ctx.buffer()    // raw Buffer
 ```
 
 Bodies larger than `maxBody` (default 1 MB, configurable in `createServer`) are rejected with a 413 response before the handler runs.
 
+**`ctx.formData()` returns a plain object, not a browser `FormData`.** Read fields directly — `data?.email`, not `data.get('email')` — the latter throws `TypeError: data.get is not a function`. This trips people up because client-side action code (`actions.*.run(state, serverState, formData)`) receives a real `FormData` object with a `.get()` method — same method name, different context, different shape. If you're writing `spec.submit` and reach for `.get()`, that's the tell you've copied the client-side pattern by mistake.
+
 **Page specs only accept GET/HEAD by default** (POST → 405). To handle POST on a page spec, opt in with `spec.methods`:
 
 ```js
@@ -310,6 +395,22 @@ Key properties:
 - `Cache-Control: no-store` — proxies never serve a stale health status
 - Fires before route matching — a user spec at `/healthz` is shadowed when the built-in is enabled
 
+## Error journal — mechanized, agent-facing error tracking
+
+In dev mode (`dev: true`), every error the three error layers above catch — plus post-hydration client view/action failures — is also recorded to `.pulse/errors.json`. This is a machine-checkable diagnostic, not a console line you have to notice: read it with `pulse_diagnose`, clear entries with `pulse_resolve_error`.
+
+```js
+// .pulse/errors.json — written automatically, never edit directly
+[{ id, ts, route, phase, message, stack, resolved }]
+// phase: 'view' | 'action' | 'server' | 'guard'
+```
+
+**Call `pulse_diagnose` when something seems broken and the cause isn't obvious**, or proactively after building/testing a page to confirm nothing threw during the session. Pass `{ route }` to filter to one page. `/verify` already calls this automatically before writing the stamp — an unresolved error for the target route blocks the stamp; a clean pass auto-resolves the route's entries via `pulse_stamp`. You don't need to call `pulse_resolve_error` manually in the normal `/verify` flow — only if you fixed something outside that loop and want it cleared immediately.
+
+- Ring-buffered at 50 entries — a diagnostic tool, not a production error tracker
+- `dev`-only — nothing is written in production, and the client-reporting endpoint (`/__pulse/error`) doesn't exist outside dev mode
+- Never write to this file directly — it's framework-managed
+
 ## Graceful shutdown
 
 `createServer` registers `SIGTERM` and `SIGINT` handlers automatically. When either signal arrives:

package/src/agent/guide-spec.md

@@ -49,8 +49,15 @@ export default {
   // Server-side form handling — POST works with JavaScript disabled.
   // { redirect } → 303 PRG; anything else → re-render with the value as server.form.
   // CSRF enforced automatically: the view MUST include ${server.csrf} inside the <form>.
+  //
+  // ⚠ ctx.formData() here is NOT the same type as the client-side FormData used
+  // in actions.run above. Server-side it's already parsed into a plain object —
+  // read fields directly (data?.email), not with .get('email'). Calling .get()
+  // on it throws "data.get is not a function". This is the single most common
+  // mistake writing spec.submit — the two formData()s look identical but return
+  // different shapes because one runs in the browser and one runs server-side.
   submit: async (ctx) => {
-    const data = await ctx.formData()
+    const data = await ctx.formData()   // plain object: { email: '...', ... } | null
     if (!data?.email) return { errors: { email: 'Required' }, values: data ?? {} }
     await save(data)
     return { redirect: '/thanks' }

package/src/agent/guide-styles.md

@@ -238,6 +238,29 @@ createServer(specs, {
 
 Without this, external images will be blocked in production and Lighthouse will flag a Best Practices failure. Use the same pattern for other external resource types (`media-src` for video, `connect-src` for fetch/XHR to external APIs).
 
+### Third-party scripts (ad networks, analytics SDKs)
+
+**Every `csp` key merges the same way — including `trusted-types` and `require-trusted-types-for`.** This is a real, tested behavior, not a guess: `csp` passed to `createServer` (or `pulse.config.js`) is spread onto the framework's base CSP directive-by-directive, so `csp: { 'trusted-types': ['google'] }` produces `trusted-types pulse google` in the response header — it does not replace or drop the framework's own `pulse` policy.
+
+A third-party script (Google AdSense, GTM, and similar SDKs) typically needs up to three separate CSP extensions — do not assume only one is needed:
+
+```js
+// pulse.config.js
+export default {
+  csp: {
+    // The loader <script src="..."> itself — origin allowlist, no nonce needed
+    'script-src':    ['https://pagead2.googlesyndication.com'],
+    // If the SDK creates its own Trusted Types policy (some ad SDKs do) —
+    // scoped to exactly the policy name it registers, not a broad relaxation
+    'trusted-types': ['google'],
+  },
+}
+```
+
+For the **inline** per-slot script the SDK's own docs tell you to paste in (e.g. `(adsbygoogle = window.adsbygoogle || []).push({})`), use `server.nonce` — see "Third-party inline scripts" in `pulse://guide/server`. `csp.script-src` origin allowlisting only covers `<script src="...">`, not inline `<script>` content.
+
+**Without the `trusted-types` extension, this is a hard failure, not a cosmetic one:** a script that calls `trustedTypes.createPolicy(...)` under a name other than `pulse` throws in the browser console, the SDK fails to initialize, AND `lighthouse_audit` fails Best Practices on the resulting console error/CSP violation — confirmed directly (an agent hit exactly this running a real audit against AdSense). This is not a "check the console if something seems off" edge case; if you're integrating a third-party SDK and Lighthouse Best Practices won't reach 100, check the browser console for a Trusted Types policy rejection before assuming the problem is elsewhere.
+
 For multiple weights or italic variants, separate them with a semicolon in the URL:
 ```
 ?family=Inter:ital,wght@0,400;0,700;1,400&display=swap