@invisibleloop/pulse 0.17.1 → 0.17.3

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

@@ -50,7 +50,7 @@ Check for:
 - Layout looks correct
 - No console errors via `mcp__chrome-devtools__list_console_messages`
 
-Then ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
+Then **call `pulse_await_approval`** and ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks; the marker is harmless if the turn doesn't end. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 **Do not proceed to step 7 until the user explicitly confirms.** If they want changes, make them and return to step 6.
 

package/.claude/commands/verify.md

@@ -15,7 +15,7 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+2. **Call `pulse_await_approval` first**, then ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose. Always call the tool before asking, whichever way you ask: in some hosts (including Claude Code) even a question tool ends the turn and fires the Stop hooks. The marker is harmless if the turn doesn't end — it is consumed when the user replies.
 3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 ### 3. Validate the spec
@@ -46,7 +46,7 @@ The browser should still be on `http://localhost:3001/` from step 6. Run `mcp__c
 
 **Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 3.
 
-After both Lighthouse runs pass, call `pulse_restart_server` to return to the dev server.
+**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
 
@@ -54,7 +54,7 @@ Emulate a mobile viewport and take a screenshot to catch wrapping, overflow, and
 
 ```
 mcp__chrome-devtools__emulate  viewport: "390x844x2,mobile,touch"
-mcp__chrome-devtools__navigate_page  url: "http://localhost:3000/"
+mcp__chrome-devtools__navigate_page  url: "http://localhost:3001/"
 mcp__chrome-devtools__take_screenshot
 ```
 
@@ -72,7 +72,9 @@ mcp__chrome-devtools__emulate  viewport: "1440x900x1"
 
 ### 9. Performance
 
-Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+**Run the trace against the production server, not dev.** Navigate to `http://localhost:3001/<route>` first — if the production server is no longer running, run `pulse_build` again. Tracing the dev server (port 3000) reports misleading LCP/CLS. Then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+
+After the trace, call `pulse_restart_server` to return to the dev server.
 
 ### 10. Console errors
 

package/.claude/pulse-checklist.md

@@ -20,6 +20,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
+
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first — or creative override
@@ -111,6 +113,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 ### 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).
+- **`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
+
+- **Forms that must work without JavaScript use `spec.submit`** + `<form method="POST">` with `${server.csrf}` inside. Hydrated `data-action` on the same form is the enhancement, not the requirement.
+- On a validation re-render, show `server.form?.errors` and echo `server.form?.values` back into the inputs via `value=` — failed validation must not wipe what the user typed.
+- **Every site has a custom 404 page** — a spec with `route: '*'`, using the shared `layout()` so it carries the site's nav and footer. Without it, bad URLs show the framework's unbranded default.
 
 ### Tests
 

package/CLAUDE.md

@@ -41,12 +41,15 @@ A spec is a plain JS object. Every property is optional except `route` and `view
 
 ```js
 export const mySpec = {
-  route:   '/path',           // URL pattern, supports :params
+  route:   '/path',           // URL pattern, supports :params. Use '*' for the custom
+                              // not-found page — rendered with status 404 when no route matches
 
   meta: {
     title:       'Page Title',
     description: 'Meta description',
     styles:      ['/pulse.css'],
+    theme:       'light',        // 'light' | 'dark' — ⚠ default is DARK when unset; decide at write time
+    vibe:        'minimal',      // optional preset: radius, weight, spacing
     ogTitle:     '...',
     ogImage:     '...',
   },
@@ -119,6 +122,19 @@ export const mySpec = {
     }
   },
 
+  // Server-side form handling — POST to this route, no client JS required.
+  // CSRF protection is automatic: include ${server.csrf} inside the <form>.
+  //   { redirect: '/path' }   → 303 POST-redirect-GET
+  //   anything else           → page re-renders; return value appears as server.form
+  //                             (optional status field sets the response status, e.g. 422)
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Required' }, values: data ?? {} }
+    await saveSignup(data)
+    return { redirect: '/thanks' }
+  },
+  // csrf: false,             // opt out ONLY for endpoints with their own auth (e.g. signed webhooks)
+
   // Streaming SSR — split view into shell (instant) + deferred segments
   stream: {
     shell:    ['header', 'nav'],
@@ -139,6 +155,42 @@ export const mySpec = {
 export default mySpec  // required for hydration imports
 ```
 
+## Server-Side Forms (no client JS)
+
+A spec with `submit` accepts POST on its route — the form works with JavaScript disabled. **Always include `${server.csrf}` inside the form** (CSRF is enforced; POSTs without the token get 403):
+
+```js
+view: (state, server) => `
+  <main id="main-content">
+    ${server.form?.errors?.email ? alert({ variant: 'error', message: server.form.errors.email }) : ''}
+    <form method="POST">
+      ${server.csrf}
+      ${input({ label: 'Email', name: 'email', type: 'email', required: true, value: server.form?.values?.email ?? '' })}
+      ${button({ label: 'Sign up', type: 'submit' })}
+    </form>
+  </main>`,
+```
+
+- `server.form` is the return value of `submit()` on a re-render (validation errors, submitted values) — `undefined` on plain GET.
+- **Progressive enhancement:** the same form can also carry `data-action="signup"` — hydrated visitors get the async action (no page reload), no-JS visitors fall back to the POST. Echo submitted values back into inputs via `value=` so a failed validation doesn't wipe the form.
+- Always `return { redirect }` after a successful mutation (POST-redirect-GET) — never render success directly from the POST, or refresh resubmits the form.
+- Multi-instance deployments: set a stable `secret` in `createServer` so CSRF tokens validate across instances.
+
+## Custom 404 Page
+
+Create a spec with `route: '*'` — it renders through the normal pipeline (layout, styles, hydration, validation) with status 404 whenever no route matches:
+
+```js
+// src/pages/not-found.js
+export default {
+  route: '*',
+  meta:  { title: 'Page not found', styles: ['/pulse-ui.css', '/theme.css', '/app.css'] },
+  view:  () => `<main id="main-content"><h1>Page not found</h1><p><a href="/">Back home</a></p></main>`,
+}
+```
+
+Without a `'*'` spec, the framework's plain default 404 is served. 500s are customised via `createServer`'s `onError` option.
+
 ## HTML Event Binding
 
 Pulse binds to DOM attributes — no JSX, no templates.
@@ -228,6 +280,8 @@ await createServer(
                                   // 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
+    secret:       process.env.PULSE_SECRET,  // HMAC secret for CSRF tokens — set a stable value
+                                  // when running multiple instances (default: random per boot)
     csp: {                        // extra sources merged into the framework's default CSP
       'style-src': ['https://fonts.googleapis.com'],
       'font-src':  ['https://fonts.gstatic.com'],
@@ -468,7 +522,7 @@ For any **new page, landing page, or branded site**, run this sequence first. Do
 3. pulse_intent(description)                  → archetype + scaffold + guide list
 ```
 
-**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, vibe, and anti-style if not mentioned.
+**Before calling `pulse_intake`**, gather the required information by asking the user — one question at a time, in plain prose, no bullet lists. You need at minimum: the product name, what it does (pitch), and its key features. **Always ask first whether they have design inspiration** (a site they love, a screenshot, a mood board — dropped into `public/intake/` or pasted as a URL), and check `public/intake/` for images already there. Then ask for palette, **theme (light or dark — Pulse defaults to dark when unset)**, vibe, and anti-style if not mentioned.
 
 **`pulse_sketch` is mandatory** for `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes — those vibes fight the default centred-hero layout. Skip it only for `corporate` or `minimal` when no structural preference has been stated.
 

package/docs/.claude/pulse-checklist.md

@@ -20,6 +20,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
+
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first — or creative override
@@ -111,6 +113,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 ### 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).
+- **`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
+
+- **Forms that must work without JavaScript use `spec.submit`** + `<form method="POST">` with `${server.csrf}` inside. Hydrated `data-action` on the same form is the enhancement, not the requirement.
+- On a validation re-render, show `server.form?.errors` and echo `server.form?.values` back into the inputs via `value=` — failed validation must not wipe what the user typed.
+- **Every site has a custom 404 page** — a spec with `route: '*'`, using the shared `layout()` so it carries the site's nav and footer. Without it, bad URLs show the framework's unbranded default.
 
 ### Tests
 

package/docs/public/pulse-ui.css

@@ -4031,8 +4031,14 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 }
 
 .ui-drop-cap-letter {
-  font-weight: 700;
-  color:       var(--ui-text);
+  /* line-height ~cap height keeps the float box hugging the glyph so the cap
+     top-aligns with the first text line — a relative line-height makes serif
+     caps float below the opening line. Component sets font-size inline. */
+  float:        left;
+  font-weight:  700;
+  line-height:  0.82;
+  margin-right: 0.1em;
+  color:        var(--ui-text);
 }
 
 /* Colophon — minimal footer for editorial pages */

package/docs/server.js

@@ -45,9 +45,11 @@ await createServer(
     new URL('./src/pages/markdown.js',          import.meta.url),
     new URL('./src/pages/store.js',             import.meta.url),
     new URL('./src/pages/routing.js',           import.meta.url),
+    new URL('./src/pages/error-pages.js',       import.meta.url),
     new URL('./src/pages/streaming.js',         import.meta.url),
     new URL('./src/pages/caching.js',           import.meta.url),
     new URL('./src/pages/guard.js',             import.meta.url),
+    new URL('./src/pages/forms.js',             import.meta.url),
     new URL('./src/pages/raw-responses.js',     import.meta.url),
     new URL('./src/pages/server-api.js',        import.meta.url),
     new URL('./src/pages/extending.js',         import.meta.url),

package/docs/src/lib/nav.js

@@ -41,9 +41,11 @@ export const NAV = [
       { label: 'Markdown',       href: '/markdown'      },
       { label: 'Global Store',   href: '/store'         },
       { label: 'Routing',        href: '/routing'       },
+      { label: 'Error Pages',    href: '/error-pages'   },
       { label: 'Streaming SSR',  href: '/streaming'     },
       { label: 'Caching',        href: '/caching'       },
       { label: 'Guard',          href: '/guard'         },
+      { label: 'Forms',          href: '/forms'         },
       { label: 'Raw Responses',  href: '/raw-responses' },
       { label: 'Server API',     href: '/server-api'    },
       { label: 'Extending Pulse', href: '/extending'    },

package/docs/src/pages/actions.js

@@ -20,6 +20,8 @@ export default {
       ${h1('Actions')}
       ${lead('Actions handle async operations with an enforced lifecycle. The order of steps — capture inputs, validate, run, succeed or fail — is fixed. Skipping validation or running async work before showing a loading state is not possible within the action structure.')}
 
+      ${callout('tip', 'Actions run client-side and need hydration. For forms that must also work with JavaScript disabled, pair the action with a server-side <a href="/forms"><code>submit</code> handler</a> — the same form serves both paths.')}
+
       ${section('lifecycle', 'The action lifecycle')}
       <p>When a form with <code>data-action</code> is submitted, Pulse runs the action through a fixed sequence of steps:</p>
       ${codeBlock(highlight(`onStart(state, formData)

package/docs/src/pages/error-pages.js

@@ -0,0 +1,98 @@
+import { renderLayout, h1, lead, section, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/error-pages')
+
+export default {
+  route: '/error-pages',
+  meta: {
+    title: 'Error Pages — Pulse Docs',
+    description: 'Custom 404 pages in Pulse. A spec with route "*" renders through the normal pipeline with status 404 whenever no route matches.',
+    styles: ['/docs.css'],
+  },
+  view: () => renderLayout({
+    currentHref: '/error-pages',
+    prev,
+    next,
+    content: `
+      ${h1('Error Pages')}
+      ${lead('A spec with <code>route: \'*\'</code> is your site\'s custom 404 page. It renders through the normal pipeline — layout, styles, components, hydration — with status <strong>404</strong> whenever no route matches. Without one, visitors to a bad URL get the framework\'s unbranded default.')}
+
+      ${section('not-found', 'The custom 404 page')}
+      <p>Create a spec like any other page, with <code>'*'</code> as the route. Use the shared <code>layout()</code> so the page carries the site's nav and footer:</p>
+      ${codeBlock(highlight(`import { layout } from '../components/layout.js'
+
+export default {
+  route: '*',
+  meta: {
+    title:  'Page not found',
+    styles: ['/pulse-ui.css', '/theme.css', '/app.css'],
+  },
+  view: () => layout({
+    content: \`
+      <h1>Page not found</h1>
+      <p>That page doesn't exist. <a href="/">Back home</a></p>
+    \`,
+  }),
+}`, 'js', ), 'src/pages/not-found.js')}
+      <p>The filename doesn't matter — <code>not-found.js</code> is just a readable convention. The <code>route: '*'</code> property is what registers it as the fallback.</p>
+
+      ${callout('tip', 'Every site should have one. The framework\'s default 404 is a bare unstyled page with no navigation — a dead end for visitors and a missed signal for search engines crawling old URLs.')}
+
+      ${section('behaviour', 'How it behaves')}
+      ${table(
+        ['Aspect', 'Behaviour'],
+        [
+          ['Status code', 'Always <strong>404</strong> — correct for SEO; crawlers de-index dead URLs'],
+          ['Pipeline', 'Full normal render: <code>meta</code>, styles, components, hydration if it has mutations/actions'],
+          ['Validation', 'Validated at startup like every spec — a broken 404 page fails fast'],
+          ['Matching', 'Only when no other route matches. It is a fallback, not a route — it never shadows real pages'],
+          ['Client-side navigation', 'A bad link falls back to a full page load, which renders the custom 404'],
+          ['Caching', '404 responses are never stored in the in-process page cache'],
+        ]
+      )}
+
+      ${section('useful-404', 'Making the 404 useful')}
+      <p>The best 404 pages help the visitor recover. Since the page is a normal spec, it can use any component — search, popular links, even server data:</p>
+      ${codeBlock(highlight(`export default {
+  route: '*',
+  meta:  { title: 'Page not found', styles: ['/pulse-ui.css', '/theme.css', '/app.css'] },
+  server: {
+    popular: async () => getPopularPages(),   // suggest somewhere to go
+  },
+  view: (state, server) => layout({
+    content: \`
+      <h1>Page not found</h1>
+      <p>Try one of these instead:</p>
+      \${list({ items: (server.popular ?? []).map(p => \`<a href="\${p.href}">\${p.title}</a>\`) })}
+    \`,
+  }),
+}`, 'js'))}
+
+      ${section('server-errors', '500s and other errors')}
+      <p>Server errors are handled by <code>createServer</code>'s <code>onError</code> option, not a spec — when a render throws, the spec pipeline itself may be the thing that is broken, so the handler works at the HTTP level:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  onError: (err, req, res) => {
+    console.error(err)
+    if (res.headersSent) return
+    res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' })
+    res.end('<h1>Something went wrong</h1><p><a href="/">Back home</a></p>')
+  },
+})`, 'js'))}
+      <p>For errors thrown inside a <em>view</em> specifically, prefer <code>onViewError</code> on the spec — it returns a 200 with fallback HTML instead of a 500, keeping the page alive when one piece of data is malformed.</p>
+
+      ${callout('note', 'Three layers, three jobs: <code>route: \'*\'</code> for URLs that don\'t exist, <code>onViewError</code> for views that throw on bad data, <code>onError</code> for everything else that goes wrong server-side.')}
+
+      ${section('reference', 'Reference')}
+      ${table(
+        ['Property', 'Where', 'Notes'],
+        [
+          ['<code>route: \'*\'</code>', 'spec', 'Custom not-found page — rendered with status 404 when no route matches'],
+          ['<code>onViewError</code>', 'spec', 'Fallback HTML when the view throws — returns 200'],
+          ['<code>onError</code>', '<code>createServer</code> option', 'HTTP-level handler for unhandled server errors (500s)'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/forms.js

@@ -0,0 +1,128 @@
+import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/forms')
+
+export default {
+  route: '/forms',
+  meta: {
+    title: 'Forms — Pulse Docs',
+    description: 'Server-side form handling in Pulse. spec.submit processes POST requests without client JavaScript, with automatic CSRF protection and POST-redirect-GET.',
+    styles: ['/docs.css'],
+  },
+  view: () => renderLayout({
+    currentHref: '/forms',
+    prev,
+    next,
+    content: `
+      ${h1('Forms')}
+      ${lead('A spec with a <code>submit</code> handler accepts POST requests on its own route — the form works with JavaScript disabled. CSRF protection is automatic, and successful submissions follow POST-redirect-GET. Client-side <code>actions</code> become an enhancement, not a requirement.')}
+
+      ${section('basics', 'Basic usage')}
+      <p>Add a <code>submit</code> function to the spec and render a plain <code>&lt;form method="POST"&gt;</code>. The route accepts POST automatically — no <code>methods</code> declaration needed.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/contact',
+
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Email is required' }, values: data ?? {} }
+    await sendMessage(data)
+    return { redirect: '/contact?sent=1' }   // 303 POST-redirect-GET
+  },
+
+  view: (state, server) => \`
+    <main id="main-content">
+      \${server.form?.errors?.email ? \`<p class="error">\${escHtml(server.form.errors.email)}</p>\` : ''}
+      <form method="POST">
+        \${server.csrf}
+        \${input({ label: 'Email', name: 'email', type: 'email', required: true,
+                   value: server.form?.values?.email ?? '' })}
+        \${button({ label: 'Send', type: 'submit' })}
+      </form>
+    </main>
+  \`,
+}`, 'js'))}
+      <p>The flow: the browser POSTs the form, <code>submit(ctx)</code> runs server-side, and either redirects (success) or re-renders the page with the returned value available to the view as <code>server.form</code> (validation failure).</p>
+
+      ${callout('warning', '<strong><code>\${server.csrf}</code> must be inside every POST form.</strong> It renders the hidden CSRF token input — submissions without a valid token are rejected with <strong>403</strong> before <code>submit</code> runs.')}
+
+      ${section('return-values', 'Return values')}
+      ${table(
+        ['Return', 'Response', 'Use for'],
+        [
+          ['<code>{ redirect: \'/path\' }</code>', '<strong>303 See Other</strong>', 'Successful submissions — POST-redirect-GET means refresh never resubmits'],
+          ['<code>{ errors, values, … }</code>',  'Page re-renders (200), value exposed as <code>server.form</code>', 'Validation failures — show errors, echo values back into inputs'],
+          ['<code>{ status: 422, errors, … }</code>', 'Same re-render with status <strong>422</strong>', 'Validation failures where the status code matters (API clients, tests)'],
+          ['<code>undefined</code>', 'Page re-renders (200), <code>server.form</code> is <code>{}</code>', 'Fire-and-forget side effects'],
+        ]
+      )}
+      <p><strong>Always redirect after a successful mutation.</strong> Rendering a success message directly from the POST means a browser refresh resubmits the form. Redirect to a URL that shows the confirmation instead (e.g. <code>/contact?sent=1</code>).</p>
+
+      ${section('server-form', 'server.form — errors and echoed values')}
+      <p>On a re-render, whatever <code>submit</code> returned is available to the view as <code>server.form</code>. On a plain GET it is <code>undefined</code> — always use optional chaining.</p>
+      ${codeBlock(highlight(`// In submit — return errors AND the submitted values:
+return { errors: { email: 'Invalid email' }, values: data }
+
+// In the view — show the error, echo the value back so the form isn't wiped:
+\${server.form?.errors?.email ? \`<p class="error">\${escHtml(server.form.errors.email)}</p>\` : ''}
+\${input({ name: 'email', label: 'Email', value: server.form?.values?.email ?? '' })}`, 'js'))}
+      ${callout('warning', 'Escape user-submitted values before interpolating them into HTML — <code>server.form.values</code> is raw user input. Component props like <code>input({ value })</code> are auto-escaped; manual interpolation needs <code>escHtml()</code>.')}
+
+      ${section('csrf', 'CSRF protection')}
+      <p>Every <code>submit</code> spec gets CSRF protection automatically — there is nothing to configure. Under the hood Pulse uses an HMAC double-submit pattern:</p>
+      ${table(
+        ['Piece', 'Where it lives', 'What it does'],
+        [
+          ['Random id', '<code>pulse_csrf</code> cookie (HttpOnly, SameSite=Lax)', 'Set on the first GET of the form page'],
+          ['Token', 'Hidden <code>_csrf</code> input via <code>\${server.csrf}</code>', '<code>HMAC-SHA256(secret, id)</code> — embedded into the form server-side'],
+          ['Verification', 'On every POST, before <code>submit</code> runs', 'Recomputes the HMAC from the cookie and compares in constant time — mismatch is 403'],
+        ]
+      )}
+      <p>An attacker on another origin can cause the cookie to be sent, but cannot read it or compute the HMAC — so they cannot forge the pair.</p>
+
+      ${sub('multi-instance', 'Multiple server instances')}
+      <p>The HMAC secret defaults to a random value per server boot. Behind a load balancer, pin it so tokens issued by one instance validate on another:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  secret: process.env.PULSE_SECRET,   // stable across instances and restarts
+})`, 'js'))}
+
+      ${sub('opt-out', 'Opting out')}
+      <p>Set <code>csrf: false</code> on the spec to disable protection — only for endpoints with their own authentication, such as signed webhooks:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/webhooks/stripe',
+  csrf: false,                       // Stripe signs its requests — verify the signature instead
+  submit: async (ctx) => {
+    verifyStripeSignature(ctx.headers['stripe-signature'], await ctx.text())
+    // ...
+  },
+  view: () => '<main id="main-content">ok</main>',
+}`, 'js'))}
+      ${callout('warning', 'Never set <code>csrf: false</code> to "fix" a 403. The 403 means the form is missing <code>\${server.csrf}</code> — add the field, don\'t remove the protection.')}
+
+      ${section('progressive-enhancement', 'Progressive enhancement')}
+      <p>The same form can serve both worlds: <code>method="POST"</code> is the no-JS fallback, <code>data-action</code> is the hydrated path. With JavaScript enabled the runtime intercepts the submit and runs the async action (no page reload); without it the browser POSTs to <code>submit</code>.</p>
+      ${codeBlock(highlight(`<form method="POST" data-action="send">
+  \${server.csrf}
+  \${input({ label: 'Email', name: 'email', type: 'email', required: true })}
+  \${button({ label: 'Send', type: 'submit' })}
+</form>`, 'html'))}
+      <p>Keep the two paths consistent: <code>submit</code> and the action's <code>run</code> should call the same underlying function so validation and side effects cannot drift apart.</p>
+
+      ${section('caching', 'Interaction with caching')}
+      <p>Pages with <code>submit</code> are automatically excluded from the in-process page cache — the CSRF token is per-visitor, and a cached page would serve one visitor's token to everyone. POST responses are never cached.</p>
+
+      ${section('reference', 'Reference')}
+      ${table(
+        ['Property', 'Type', 'Notes'],
+        [
+          ['<code>submit</code>', '<code>async (ctx) =&gt; { redirect } | object | void</code>', 'Handles POST on the route. Guard runs first.'],
+          ['<code>csrf</code>', '<code>boolean</code>', 'Default <code>true</code>. Set <code>false</code> only for self-authenticated endpoints.'],
+          ['<code>server.csrf</code>', 'string (view)', 'Hidden <code>_csrf</code> input — required inside every POST form.'],
+          ['<code>server.form</code>', 'object | undefined (view)', 'Return value of <code>submit</code> on a re-render; <code>undefined</code> on GET.'],
+          ['<code>secret</code>', 'string (createServer option)', 'Stable HMAC secret for multi-instance deployments.'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/guard.js

@@ -105,6 +105,7 @@ export default {
   // return nothing to let a GET request proceed to the view
 }`, 'js'))}
       ${callout('note', 'To use <code>guard</code> as a POST handler, the spec must declare <code>methods: [\'GET\', \'POST\']</code>. Without it, POST requests are rejected with 405 before guard runs.')}
+      ${callout('tip', 'For HTML form submissions, prefer <a href="/forms"><code>spec.submit</code></a> — it accepts POST automatically, gets CSRF protection for free, and re-renders the page with validation errors. Guard-based POST handling is best for API-style endpoints.')}
 
       ${section('reference', 'Reference')}
       ${table(

package/docs/src/pages/routing.js

@@ -80,15 +80,13 @@ server: {
 }`, 'js'))}
 
       ${section('not-found', '404 handling')}
-      <p>If no spec matches the incoming request path, Pulse returns a 404 response. The response body is a minimal HTML page. To customise the 404 page, use the <code>onError</code> option in <code>createServer</code>:</p>
-      ${codeBlock(highlight(`createServer(specs, {
-  onError: (err, req, res) => {
-    if (err.status === 404) {
-      res.writeHead(404, { 'Content-Type': 'text/html' })
-      res.end('<h1>Not found</h1>')
-    }
-  }
-})`, 'js'))}
+      <p>If no spec matches the incoming request path, Pulse returns a 404. To customise it, create a spec with <code>route: '*'</code> — it renders through the normal pipeline (layout, styles, components) with status 404:</p>
+      ${codeBlock(highlight(`export default {
+  route: '*',
+  meta:  { title: 'Page not found', styles: ['/pulse-ui.css', '/theme.css', '/app.css'] },
+  view:  () => \`<main id="main-content"><h1>Page not found</h1><p><a href="/">Back home</a></p></main>\`,
+}`, 'js'), 'src/pages/not-found.js')}
+      <p>See <a href="/error-pages">Error Pages</a> for the full behaviour, including 500 handling.</p>
 
       ${section('conventions', 'File naming conventions')}
       <p>While Pulse does not auto-discover files, the recommended convention maps file names to routes:</p>

package/docs/src/pages/server-api.js

@@ -48,8 +48,9 @@ await createServer(entries, options)`, 'js'))}
           ['<code>shutdownTimeout</code>', '<code>number</code>', '<code>30000</code>', 'Milliseconds to wait for in-flight requests to finish during graceful shutdown before force-exiting. See <a href="#graceful-shutdown">Graceful shutdown</a>.'],
           ['<code>healthCheck</code>', '<code>string | false</code>', '<code>"/healthz"</code>', 'Path for the built-in health check endpoint. Returns <code>{ status: "ok", uptime }</code>. Set to <code>false</code> to disable. The endpoint bypasses <code>onRequest</code> so load balancers always get a response.'],
           ['<code>resolveBrand</code>', '<code>async (host) => any</code>', '<code>undefined</code>', 'Multi-brand support. Called once per host (cached 60s). Result is attached to <code>ctx.brand</code> and available in <code>guard</code>, <code>server</code>, and <code>meta</code> functions.'],
+          ['<code>secret</code>', '<code>string</code>', 'random per boot', 'HMAC secret for CSRF tokens (<a href="/forms">Forms</a>). Set a stable value when running multiple instances so tokens issued by one validate on another.'],
           ['<code>onRequest</code>', '<code>function</code>', '<code>undefined</code>', 'Called on every request before routing. Return <code>false</code> to short-circuit Pulse handling.'],
-          ['<code>onError</code>', '<code>function</code>', '<code>undefined</code>', 'Called on unhandled errors. Receives <code>(err, req, res)</code>.'],
+          ['<code>onError</code>', '<code>function</code>', '<code>undefined</code>', 'Called on unhandled errors. Receives <code>(err, req, res)</code>. See <a href="/error-pages">Error Pages</a>.'],
         ]
       )}
 

package/examples/.claude/pulse-checklist.md

@@ -20,6 +20,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **The default theme is DARK.** When `meta.theme` is unset, the page renders with the dark palette. If the design calls for a light page, set `meta.theme: 'light'` when you **first write the spec** — do not assume light and discover dark at the screenshot, which costs an edit → restart → re-approval cycle. Declare the theme in your plan/build brief, and ask the user if the brief doesn't say.
+
 - **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first — or creative override
@@ -111,6 +113,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 ### 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).
+- **`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
+
+- **Forms that must work without JavaScript use `spec.submit`** + `<form method="POST">` with `${server.csrf}` inside. Hydrated `data-action` on the same form is the enhancement, not the requirement.
+- On a validation re-render, show `server.form?.errors` and echo `server.form?.values` back into the inputs via `value=` — failed validation must not wipe what the user typed.
+- **Every site has a custom 404 page** — a spec with `route: '*'`, using the shared `layout()` so it carries the site's nav and footer. Without it, bad URLs show the framework's unbranded default.
 
 ### Tests