@invisibleloop/pulse 0.17.2 → 0.17.3

package/.claude/pulse-checklist.md

@@ -113,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,7 +41,8 @@ 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',
@@ -121,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'],
@@ -141,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.
@@ -230,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'],

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

@@ -113,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/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

@@ -113,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.17.2
+0.17.3

package/src/agent/checklist.md

@@ -113,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/src/agent/guide-routing.md

@@ -126,6 +126,27 @@ Convention: name dynamic-route files [param].js inside a subfolder:
 
 This is purely a human readability convention. Pulse does not process [ ] in filenames.
 
+## Custom 404 page
+
+Create a spec with `route: '*'` — it renders through the normal pipeline (layout, styles, hydration) with status 404 whenever no route matches:
+
+```js
+// src/pages/not-found.js
+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>`,
+  }),
+}
+```
+
+- Use the shared `layout()` so the 404 carries the site's nav and footer.
+- **Every site should have one** — without it, visitors to a bad URL get the framework's unbranded default 404.
+- 500 errors are customised via `createServer`'s `onError` option, not a spec.
+
 ## Canonical URLs
 
 Pulse auto-derives a canonical URL from every request and emits `<link rel="canonical">` in the `<head>`. No config needed in most cases.

package/src/agent/guide-server.md

@@ -102,6 +102,40 @@ actions: {
 ```
 `_storeUpdate` is stripped from local page state — it is only forwarded to the store. The rest of `onSuccess` merges into the page's own state as normal.
 
+## Server-side forms — `spec.submit` (works without client JS)
+
+A spec with a `submit` handler accepts POST on its own route. The form works with JavaScript disabled — hydrated `actions` become an enhancement, not a requirement.
+
+```js
+export default {
+  route: '/contact',
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email)        return { errors: { email: 'Email is required' }, values: data ?? {} }
+    if (!isValid(data.email)) return { status: 422, errors: { email: 'Invalid email' }, 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>`,
+}
+```
+
+**Rules:**
+- `${server.csrf}` **must be inside every POST form** — CSRF protection is automatic and POSTs without a valid token are rejected with 403. Opt out with `csrf: false` only for endpoints with their own authentication (e.g. signed webhooks).
+- `{ redirect }` → 303 See Other. Always redirect after a successful mutation — rendering success directly from the POST means refresh resubmits the form.
+- Any other return value re-renders the page with it exposed as `server.form` — put `errors` and the submitted `values` there, and echo values back into inputs so failed validation doesn't wipe what the user typed. An optional `status` field sets the response status (e.g. 422).
+- 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.
+
 ## Server context — redirects, cookies, POST bodies
 
 The `ctx` object is available in `guard`, `server.*` fetchers, and `meta` functions.

package/src/agent/guide-spec.md

@@ -46,10 +46,31 @@ export default {
     // Resolved server-side before render. Passed to view() as second arg.
     posts: async () => fetchPostsFromDb(),
   },
+  // 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>.
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Required' }, values: data ?? {} }
+    await save(data)
+    return { redirect: '/thanks' }
+  },
   view: (state, serverState) => `<h1>${state.title}</h1>`,
 }
 ```
 
+## Server-side forms (`submit`)
+
+- A spec with `submit` accepts POST on its own route — plain `<form method="POST">`, no client JS needed.
+- **Always put `${server.csrf}` inside the form** — it renders the hidden CSRF input. POSTs without a valid token are rejected with 403. (`csrf: false` opts out — only for endpoints with their own auth.)
+- `server.form` holds the return value of `submit()` on a re-render: show `server.form?.errors`, echo `server.form?.values` back into inputs via `value=` so failed validation doesn't wipe the form.
+- After a successful mutation always `return { redirect: '/path' }` (POST-redirect-GET) — never render success from the POST itself. An optional `status` field on a re-render return sets the response status (e.g. 422).
+- Progressive enhancement: the same form can also have `data-action="name"` — hydrated visitors get the async action, no-JS visitors use the POST.
+
+## Custom not-found page
+
+A spec with `route: '*'` renders with **status 404** whenever no route matches — same pipeline as any page (layout, styles, hydration, validation). Every site should have one; the default framework 404 is unbranded.
+
 ## Streaming SSR — shell + deferred segments
 
 Use streaming when a page has slow data and you want the shell to paint instantly while slower content streams in.

package/src/runtime/ssr.js

@@ -36,7 +36,7 @@ export async function renderToString(spec, ctx = {}, pageState = {}) {
   const serverState = await resolveServerState(spec, ctx)
 
   // Merge declared store keys into server state — store keys lose to page-level keys
-  const mergedServerState = mergeStoreKeys(spec, serverState, ctx.store)
+  const mergedServerState = applyCtxExtras(mergeStoreKeys(spec, serverState, ctx.store), ctx)
 
   const tData = performance.now()
 
@@ -105,7 +105,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
 
       // Await only the fetchers the shell segments need
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
 
       // Write shell immediately — deferred fetchers may still be in-flight
       const shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
@@ -122,7 +122,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
         // Promise.all runs them concurrently — the fastest segment wins.
         await Promise.all(deferred.map(async (key) => {
           const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-          const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+          const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
           const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
 
           // Inline script replaces the placeholder with the rendered content
@@ -145,7 +145,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAllState = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAllState = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
       if (spec.hydrate && Object.keys(mergedAllState).length > 0) {
         controller.enqueue(encode(
           `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
@@ -218,7 +218,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
 
       // 2. Await shell fetchers then send shell HTML
       const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
-      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      const mergedShellState = applyCtxExtras(mergeStoreKeys(spec, shellServerState, ctx.store), ctx)
       let shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
 
       // Append <pulse-deferred> placeholders so the client knows where to inject deferred content
@@ -231,7 +231,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       // 3. Stream each deferred segment as soon as its own fetchers resolve
       await Promise.all(deferred.map(async (key) => {
         const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
-        const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+        const mergedSegState = applyCtxExtras(mergeStoreKeys(spec, segServerState, ctx.store), ctx)
         const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
         writeLine({ type: 'deferred', id: key, html: segHtml })
       }))
@@ -240,7 +240,7 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
       const allServerState = fetcherCache.size > 0
         ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
         : {}
-      const mergedAll = mergeStoreKeys(spec, allServerState, ctx.store)
+      const mergedAll = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
 
       writeLine({
         type:        'done',
@@ -426,6 +426,29 @@ function mergeStoreKeys(spec, serverState, storeState) {
   return { ...slice, ...serverState }
 }
 
+/**
+ * Merge per-request extras set by the server into the view's server state:
+ *
+ *   ctx._form      → serverState.form  — the return value of spec.submit() on a
+ *                    POST re-render (validation errors, submitted values, etc.)
+ *   ctx._csrfField → serverState.csrf  — ready-to-embed hidden <input> for CSRF;
+ *                    views include it inside <form method="POST"> as ${server.csrf}
+ *
+ * Only set by the server for specs that declare `submit` — other pages see
+ * neither key. Explicit server fetcher keys with the same names win.
+ *
+ * @param {Object} serverState
+ * @param {Object} ctx
+ * @returns {Object}
+ */
+function applyCtxExtras(serverState, ctx) {
+  if (ctx?._form === undefined && ctx?._csrfField === undefined) return serverState
+  const extras = {}
+  if (ctx._form      !== undefined) extras.form = ctx._form
+  if (ctx._csrfField !== undefined) extras.csrf = ctx._csrfField
+  return { ...extras, ...serverState }
+}
+
 // ---------------------------------------------------------------------------
 // Internal — server state resolution
 // ---------------------------------------------------------------------------

package/src/server/index.js

@@ -367,12 +367,14 @@ function buildCacheKey(spec, ctx) {
  *   - spec.stream.deferred    — deferred segments inject content via inline <script nonce="...">
  *                               tags; caching bakes in one nonce while subsequent CSP headers
  *                               carry a different nonce, causing a violation
+ *   - spec.submit             — form pages embed a per-visitor CSRF token; caching
+ *                               would serve one visitor's token to everyone
  *
  * In all these cases the cached HTML would contain a nonce that doesn't match
  * the nonce-free CSP used for cached responses, causing a CSP violation.
  */
 function isCacheablePage(spec) {
-  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length
+  return !spec.server && !spec.store?.length && !spec.hydrate && !spec.stream?.deferred?.length && !spec.submit
 }
 
 // ---------------------------------------------------------------------------
@@ -542,6 +544,8 @@ export async function createServer(entries, options = {}) {
     shutdownTimeout = 30000,        // ms to wait for in-flight requests before force-exit
     healthCheck    = '/healthz',    // path for health check endpoint, or false to disable
     csp            = {},            // extra CSP sources: { 'style-src': ['https://fonts.googleapis.com'] }
+    secret         = null,          // HMAC secret for CSRF tokens — set a stable value when running
+                                    // multiple instances; defaults to a random per-boot secret
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -585,8 +589,8 @@ export async function createServer(entries, options = {}) {
     const routeErrors = []
     if (!spec.route || typeof spec.route !== 'string') {
       routeErrors.push('spec.route is required and must be a string (e.g. "/contact")')
-    } else if (!spec.route.startsWith('/')) {
-      routeErrors.push('spec.route must start with "/" (e.g. "/contact")')
+    } else if (!spec.route.startsWith('/') && spec.route !== '*') {
+      routeErrors.push('spec.route must start with "/" (e.g. "/contact"), or be "*" for the custom not-found page')
     }
     const allErrors = [...errors, ...routeErrors]
     if (!valid || routeErrors.length > 0) {
@@ -597,8 +601,18 @@ export async function createServer(entries, options = {}) {
     }
   }
 
-  // Build route table — let so it can be swapped on hot reload
-  let router = buildRouter(specs)
+  // Custom not-found page — a spec with route '*' renders (with status 404)
+  // whenever no route matches. It goes through the normal render pipeline, so
+  // it gets the site's layout, styles, hydration, and validation like any page.
+  let notFoundSpec = specs.find(s => s.route === '*') || null
+
+  // Build route table — let so it can be swapped on hot reload.
+  // The '*' spec is excluded: it is not a route, it is the fallback.
+  let router = buildRouter(specs.filter(s => s.route !== '*'))
+
+  // CSRF secret — per-boot random unless pinned via options.secret. Tokens are
+  // tied to a cookie, so a restart only means in-flight forms re-render once.
+  const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
 
   // Resolve the logger module once at startup rather than dynamically importing
   // it on every request's `finish` event. `logRequest` stays null until loaded.
@@ -662,20 +676,32 @@ export async function createServer(entries, options = {}) {
       }
 
       // Match route
-      const match = matchRoute(router, pathname)
+      let match          = matchRoute(router, pathname)
+      let responseStatus = 200
 
       if (!match) {
-        res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
-        res.end(notFoundHtml(pathname))
-        return
+        // Custom not-found page — a '*' spec renders through the normal pipeline
+        // with status 404, so the site's branded 404 gets layout, styles, and
+        // hydration like any other page. Client-side navigation requests still
+        // get the plain 404 (navigate.js falls back to a full page load, which
+        // then renders the custom page).
+        if (notFoundSpec && (req.method === 'GET' || req.method === 'HEAD') && req.headers['x-pulse-navigate'] !== 'true') {
+          match          = { spec: notFoundSpec, params: {} }
+          responseStatus = 404
+        } else {
+          res.writeHead(404, { 'Content-Type': 'text/html', ...SECURITY_HEADERS, ...httpsHeaders(req) })
+          res.end(notFoundHtml(pathname))
+          return
+        }
       }
 
       // Method gating — raw response specs accept any HTTP method.
-      // Page specs default to GET/HEAD only; opt in to other methods via spec.methods.
+      // Page specs default to GET/HEAD only; spec.submit adds POST automatically;
+      // opt in to other methods via spec.methods.
       if (!match.spec.contentType) {
         const allowed = match.spec.methods
           ? match.spec.methods.map(m => m.toUpperCase())
-          : ['GET', 'HEAD']
+          : (typeof match.spec.submit === 'function' ? ['GET', 'HEAD', 'POST'] : ['GET', 'HEAD'])
         if (!allowed.includes(req.method)) {
           res.writeHead(405, {
             'Content-Type': 'text/plain',
@@ -738,6 +764,57 @@ export async function createServer(entries, options = {}) {
         }
       }
 
+      // -----------------------------------------------------------------------
+      // CSRF — specs with a `submit` handler get token protection automatically
+      // (opt out per spec with csrf: false, e.g. for token-authenticated routes).
+      // Double-submit pattern: an HttpOnly cookie holds a random id; the form
+      // carries HMAC(secret, id) in a hidden _csrf field; POST verifies the pair.
+      // Views embed the field inside <form method="POST"> as ${server.csrf}.
+      // -----------------------------------------------------------------------
+      if (typeof spec.submit === 'function' && spec.csrf !== false) {
+        let csrfId = ctx.cookies.pulse_csrf
+        if (!csrfId) {
+          csrfId = crypto.randomBytes(16).toString('base64url')
+          ctx.setCookie('pulse_csrf', csrfId, { httpOnly: true, sameSite: 'Lax', path: '/' })
+        }
+        ctx._csrfField = `<input type="hidden" name="_csrf" value="${csrfToken(csrfSecret, csrfId)}">`
+
+        if (req.method === 'POST') {
+          const form      = await ctx.formData()
+          const submitted = typeof form?._csrf === 'string' ? form._csrf : ''
+          const cookieId  = ctx.cookies.pulse_csrf
+          if (!cookieId || !safeEqual(submitted, csrfToken(csrfSecret, cookieId))) {
+            res.writeHead(403, mergeCtxHeaders(ctx, {
+              'Content-Type': 'text/plain',
+              ...SECURITY_HEADERS, ...httpsHeaders(req),
+            }))
+            res.end('Invalid or missing CSRF token. Reload the page and resubmit the form.')
+            return
+          }
+        }
+      }
+
+      // -----------------------------------------------------------------------
+      // Server-side form handling — spec.submit handles POST without client JS.
+      //   { redirect: '/path' }  → 303 See Other (POST-redirect-GET)
+      //   anything else          → re-render the page; the return value appears
+      //                            in the view as serverState.form (errors,
+      //                            submitted values, etc.). Optional status field
+      //                            sets the response status (e.g. 422).
+      // -----------------------------------------------------------------------
+      if (req.method === 'POST' && typeof spec.submit === 'function') {
+        const result = await spec.submit(ctx)
+        if (result?.redirect) {
+          res.writeHead(303, mergeCtxHeaders(ctx, { Location: result.redirect, ...SECURITY_HEADERS, ...httpsHeaders(req) }))
+          res.end()
+          return
+        }
+        ctx._form = result ?? {}
+        if (typeof result?.status === 'number') responseStatus = result.status
+        // POST re-renders always use the buffered path — the request body is
+        // consumed and streaming a form response has no benefit.
+      }
+
       // Derive the canonical base URL from the request.
       // Canonical path follows the trailingSlash mode so the <link> is consistent with redirects.
       // spec.meta.canonical (string or function) is resolved inside each handler, where serverState
@@ -776,7 +853,12 @@ export async function createServer(entries, options = {}) {
         return
       }
 
-      if (stream) {
+      // Non-200 renders (custom 404) and POST re-renders always use the buffered
+      // string path — they are small, must carry an explicit status, and POST
+      // bodies are already consumed.
+      if (responseStatus !== 200 || req.method === 'POST') {
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath, responseStatus)
+      } else if (stream) {
         await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
       } else {
         await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
@@ -865,7 +947,8 @@ export async function createServer(entries, options = {}) {
     server,
     shutdown,
     updateSpecs(newSpecs) {
-      router = buildRouter(newSpecs)
+      notFoundSpec = newSpecs.find(s => s.route === '*') || null
+      router = buildRouter(newSpecs.filter(s => s.route !== '*'))
     }
   }
 }
@@ -943,9 +1026,12 @@ async function handleNavStreamResponse(spec, ctx, req, res) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, status = 200) {
   const cacheKey = buildCacheKey(spec, ctx)
-  const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
+  // Never cache POST re-renders or non-200 responses (custom 404s) — POST output
+  // varies per submission and a cached 404 body would be served with a 200 later.
+  const cacheable = status === 200 && ctx.method !== 'POST' && isCacheablePage(spec)
+  const ttl       = cacheable ? pageCacheTtl(spec, dev, defaultCache) : 0
 
   let html, serverTimingValue, fromCache = false
 
@@ -984,7 +1070,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
   if (encoding)          headers['Content-Encoding'] = encoding
   if (serverTimingValue) headers['Server-Timing']    = serverTimingValue
 
-  res.writeHead(200, headers)
+  res.writeHead(status, headers)
   res.end(buf)
 }
 
@@ -1585,6 +1671,23 @@ function escHtml(str) {
     .replace(/'/g, '&#39;')
 }
 
+/**
+ * Derive the CSRF token for a cookie id: HMAC-SHA256(secret, id), base64url.
+ * The token goes in the form's hidden _csrf field; the id stays in an HttpOnly
+ * cookie. An attacker on another origin can trigger the cookie being sent but
+ * cannot read it or compute the HMAC, so they cannot forge the pair.
+ */
+function csrfToken(secret, id) {
+  return crypto.createHmac('sha256', secret).update(String(id)).digest('base64url')
+}
+
+/** Constant-time string comparison — length mismatch returns false without throwing. */
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  return ba.length === bb.length && crypto.timingSafeEqual(ba, bb)
+}
+
 function notFoundHtml(pathname) {
   return `<!DOCTYPE html>
 <html lang="en">

package/src/server/server.test.js

@@ -1246,6 +1246,206 @@ await test('health check fires before route matching — shadows a user spec at
 
 // ---------------------------------------------------------------------------
 
+console.log('\nCustom 404 page (route: "*")\n')
+
+const notFoundPageSpec = {
+  route: '*',
+  meta:  { title: 'Lost?' },
+  view:  () => '<main id="main-content"><h1>Custom not found</h1><a href="/">Home</a></main>',
+}
+
+await test('unknown route renders the "*" spec with status 404', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/nope')
+    assert(status === 404, `Expected 404, got ${status}`)
+    assert(body.includes('Custom not found'), `Expected custom 404 content, got: ${body.slice(0, 200)}`)
+    assert(body.includes('<title>Lost?</title>'), `Expected custom 404 title, got: ${body.slice(0, 300)}`)
+  })
+})
+
+await test('custom 404 renders in streaming mode too (forced string path)', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: true }, async (port) => {
+    const { status, body } = await get(port, '/still-nope')
+    assert(status === 404, `Expected 404, got ${status}`)
+    assert(body.includes('Custom not found'), `Expected custom 404 content`)
+  })
+})
+
+await test('known routes are unaffected by the "*" spec', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/hello')
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(body.includes('Hello world'), 'Expected normal page content')
+  })
+})
+
+await test('custom 404 responses are not cached as 200s', async () => {
+  await withServer([helloSpec, notFoundPageSpec], { stream: false, defaultCache: 3600, dev: false }, async (port) => {
+    const a = await get(port, '/missing')
+    const b = await get(port, '/missing')
+    assert(a.status === 404 && b.status === 404, `Expected both 404, got ${a.status}/${b.status}`)
+  })
+})
+
+await test('without a "*" spec the default 404 still works', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status, body } = await get(port, '/nope')
+    assert(status === 404 && body.includes('404'), 'Expected default 404 page')
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+console.log('\nServer-side forms (spec.submit) + CSRF\n')
+
+function requestFull(port, method, path, { headers = {}, body = null } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ method, hostname: 'localhost', port, path, headers }, (res) => {
+      let data = ''
+      res.on('data', c => { data += c })
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: data }))
+    })
+    req.on('error', reject)
+    if (body) req.write(body)
+    req.end()
+  })
+}
+
+function postForm(port, path, fields, cookie = '') {
+  const body = new URLSearchParams(fields).toString()
+  return requestFull(port, 'POST', path, {
+    headers: {
+      'Content-Type':   'application/x-www-form-urlencoded',
+      'Content-Length': Buffer.byteLength(body),
+      ...(cookie ? { Cookie: cookie } : {}),
+    },
+    body,
+  })
+}
+
+/** GET the form page and extract the CSRF cookie + token for a valid POST. */
+async function getCsrfPair(port, path) {
+  const res    = await get(port, path)
+  const setCookie = [].concat(res.headers['set-cookie'] || []).find(c => c.startsWith('pulse_csrf='))
+  const cookie = setCookie ? setCookie.split(';')[0] : ''
+  const token  = res.body.match(/name="_csrf" value="([^"]+)"/)?.[1] || ''
+  return { cookie, token, body: res.body }
+}
+
+const formSpec = {
+  route: '/signup',
+  meta:  { title: 'Sign up' },
+  submit: async (ctx) => {
+    const data = await ctx.formData()
+    if (!data?.email) return { errors: { email: 'Email is required' }, values: data ?? {} }
+    if (data.email === 'taken@example.com') return { status: 422, errors: { email: 'Already registered' }, values: data }
+    return { redirect: '/signup?done=1' }
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>Sign up</h1>
+      ${server.form?.errors?.email ? `<p class="error">${server.form.errors.email}</p>` : ''}
+      <form method="POST">
+        ${server.csrf ?? ''}
+        <label for="email">Email</label>
+        <input id="email" name="email" value="${server.form?.values?.email ?? ''}">
+        <button type="submit">Go</button>
+      </form>
+    </main>`,
+}
+
+await test('GET on a submit page sets the CSRF cookie and embeds the hidden field', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token, body } = await getCsrfPair(port, '/signup')
+    assert(cookie.startsWith('pulse_csrf='), `Expected pulse_csrf cookie, got: ${cookie}`)
+    assert(token.length > 20, `Expected a CSRF token in the form, got: ${token}`)
+    assert(body.includes('name="_csrf"'), 'Expected hidden _csrf input in the form')
+  })
+})
+
+await test('CSRF field is present in streaming mode too', async () => {
+  await withServer([formSpec], { stream: true }, async (port) => {
+    const { token } = await getCsrfPair(port, '/signup')
+    assert(token.length > 20, 'Expected CSRF token in streamed HTML')
+  })
+})
+
+await test('POST without a CSRF token is rejected with 403', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { status } = await postForm(port, '/signup', { email: 'a@b.com' })
+    assert(status === 403, `Expected 403, got ${status}`)
+  })
+})
+
+await test('POST with a forged token is rejected with 403', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie } = await getCsrfPair(port, '/signup')
+    const { status } = await postForm(port, '/signup', { email: 'a@b.com', _csrf: 'forged-token-value' }, cookie)
+    assert(status === 403, `Expected 403, got ${status}`)
+  })
+})
+
+await test('valid POST follows POST-redirect-GET with 303', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, headers } = await postForm(port, '/signup', { email: 'a@b.com', _csrf: token }, cookie)
+    assert(status === 303, `Expected 303, got ${status}`)
+    assert(headers.location === '/signup?done=1', `Expected PRG redirect, got ${headers.location}`)
+  })
+})
+
+await test('validation failure re-renders the page with server.form (errors + values)', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, body } = await postForm(port, '/signup', { email: '', _csrf: token }, cookie)
+    assert(status === 200, `Expected 200 re-render, got ${status}`)
+    assert(body.includes('Email is required'), `Expected error message in re-render, got: ${body.slice(0, 400)}`)
+  })
+})
+
+await test('submit can set a custom response status (422) and values are echoed back', async () => {
+  await withServer([formSpec], { stream: false }, async (port) => {
+    const { cookie, token } = await getCsrfPair(port, '/signup')
+    const { status, body } = await postForm(port, '/signup', { email: 'taken@example.com', _csrf: token }, cookie)
+    assert(status === 422, `Expected 422, got ${status}`)
+    assert(body.includes('Already registered'), 'Expected error in re-render')
+    assert(body.includes('value="taken@example.com"'), 'Expected submitted value echoed into the input')
+  })
+})
+
+await test('csrf: false opts a submit route out of CSRF protection', async () => {
+  const webhookish = {
+    route:  '/hook',
+    csrf:   false,
+    submit: async () => ({ redirect: '/hook?ok=1' }),
+    view:   () => '<main id="main-content">hook</main>',
+  }
+  await withServer([webhookish], { stream: false }, async (port) => {
+    const { status, headers } = await postForm(port, '/hook', { x: '1' })
+    assert(status === 303 && headers.location === '/hook?ok=1', `Expected 303 without CSRF, got ${status}`)
+  })
+})
+
+await test('POST to a page without submit is still 405', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status } = await postForm(port, '/hello', { x: '1' })
+    assert(status === 405, `Expected 405, got ${status}`)
+  })
+})
+
+await test('submit pages are excluded from the in-process page cache', async () => {
+  // Two different clients must get different CSRF tokens — a cached page would
+  // serve client A's token (and cookie pairing) to client B.
+  await withServer([formSpec], { stream: false, defaultCache: 3600 }, async (port) => {
+    const a = await getCsrfPair(port, '/signup')
+    const b = await getCsrfPair(port, '/signup')
+    assert(a.token && b.token && a.token !== b.token,
+      `Expected per-visitor CSRF tokens, got identical values (page was cached)`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nMalformed request handling\n')
 
 await test('malformed percent-encoding in path returns 404, not 500', async () => {

package/src/spec/schema.js

@@ -137,13 +137,30 @@ export function validateSpec(spec) {
     return { valid: false, errors: ['Spec must be a plain object'] }
   }
 
-  // route
+  // route — '*' is the custom not-found page, rendered with status 404 when no route matches
   if (spec.route === undefined) {
     warnings.push('spec.route is not set — the server cannot register this page without a route')
   } else if (typeof spec.route !== 'string') {
     errors.push('spec.route must be a string (e.g. "/contact")')
-  } else if (!spec.route.startsWith('/')) {
-    errors.push('spec.route must start with "/" (e.g. "/contact")')
+  } else if (!spec.route.startsWith('/') && spec.route !== '*') {
+    errors.push('spec.route must start with "/" (e.g. "/contact"), or be "*" for the custom not-found page')
+  }
+
+  // submit — server-side form handler: POST to the route is handled without client JS
+  if (spec.submit !== undefined) {
+    if (typeof spec.submit !== 'function') {
+      errors.push('spec.submit must be a function — async (ctx) => ({ redirect } | { ...form state }). It handles POST requests to this route server-side.')
+    }
+  }
+
+  // csrf — opt out of CSRF protection on the submit handler (default: enforced)
+  if (spec.csrf !== undefined) {
+    if (typeof spec.csrf !== 'boolean') {
+      errors.push('spec.csrf must be a boolean — set csrf: false only to disable CSRF protection for spec.submit (e.g. for token-authenticated endpoints)')
+    }
+    if (spec.csrf === false && typeof spec.submit === 'function') {
+      warnings.push('spec.csrf is false — POST submissions to this route are NOT CSRF-protected. Only do this for endpoints with their own auth (e.g. signed webhooks).')
+    }
   }
 
   // contentType — marks a raw content spec (RSS, sitemap, JSON API, etc.)

package/src/spec/schema.test.js

@@ -412,6 +412,39 @@ test('does not warn when meta.theme is a function', () => {
   assert(!warnings.some(w => w.includes('meta.theme')), 'Unexpected meta.theme warning when theme is a function')
 })
 
+// --- route '*', submit, csrf ------------------------------------------------
+
+test('route "*" (custom not-found page) is valid', () => {
+  const { valid, errors } = validateSpec({ route: '*', view: () => '<main id="main-content">404</main>' })
+  assert(valid, `Expected valid, got: ${errors.join('; ')}`)
+})
+
+test('non-"/" routes other than "*" are still rejected', () => {
+  const { valid } = validateSpec({ route: 'about', view: () => '' })
+  assert(!valid, 'Expected route without leading / to be invalid')
+})
+
+test('submit must be a function', () => {
+  const { valid, errors } = validateSpec({ route: '/x', view: () => '', submit: 'nope' })
+  assert(!valid && errors.some(e => e.includes('submit')), 'Expected submit type error')
+})
+
+test('a valid submit function passes', () => {
+  const { valid } = validateSpec({ route: '/x', view: () => '', submit: async () => ({ redirect: '/' }) })
+  assert(valid, 'Expected spec with submit function to be valid')
+})
+
+test('csrf must be a boolean', () => {
+  const { valid, errors } = validateSpec({ route: '/x', view: () => '', csrf: 'off' })
+  assert(!valid && errors.some(e => e.includes('csrf')), 'Expected csrf type error')
+})
+
+test('csrf: false with submit warns about unprotected POSTs', () => {
+  const { valid, warnings } = validateSpec({ route: '/x', view: () => '', submit: async () => {}, csrf: false })
+  assert(valid, 'csrf: false is valid')
+  assert(warnings.some(w => w.includes('CSRF')), 'Expected a warning about disabled CSRF protection')
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/types/schema.d.ts

@@ -65,6 +65,16 @@ export interface RequestContext {
 // Guard return value
 // ---------------------------------------------------------------------------
 
+/**
+ * Return value of spec.submit().
+ * { redirect } → 303 POST-redirect-GET. Any other object re-renders the page
+ * with the value exposed as serverState.form; an optional status field sets
+ * the HTTP response status (e.g. 422 for validation failures).
+ */
+export type SubmitResult =
+  | { redirect: string }
+  | { status?: number; [key: string]: unknown }
+
 export type GuardResult =
   | { redirect: string }
   | { status: number; json?: unknown; body?: string; headers?: Record<string, string> }
@@ -131,7 +141,10 @@ export interface MetaConfig {
 // ---------------------------------------------------------------------------
 
 export interface PulseSpec<S extends object = Record<string, unknown>> {
-  /** URL pattern. Supports :param segments. */
+  /**
+   * URL pattern. Supports :param segments.
+   * Use '*' for the custom not-found page — rendered with status 404 when no route matches.
+   */
   route: string
 
   /**
@@ -194,9 +207,25 @@ export interface PulseSpec<S extends object = Record<string, unknown>> {
   /** Global store keys this page subscribes to. Appear in view's server arg. */
   store?: string[]
 
-  /** HTTP methods this page accepts. Default ['GET', 'HEAD']. */
+  /** HTTP methods this page accepts. Default ['GET', 'HEAD'] (plus POST when submit is set). */
   methods?: Array<'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'>
 
+  /**
+   * Server-side form handler — POST to this route works without client JS.
+   * Return { redirect } for a 303 POST-redirect-GET; any other value re-renders
+   * the page with the value exposed to the view as serverState.form (an optional
+   * status field sets the response status, e.g. 422).
+   * CSRF protection is enforced automatically: the view must include
+   * ${server.csrf} inside the <form> or POSTs are rejected with 403.
+   */
+  submit?: (ctx: RequestContext) => Promise<SubmitResult | void> | SubmitResult | void
+
+  /**
+   * Set false to disable CSRF protection on the submit handler.
+   * Only for endpoints with their own authentication (e.g. signed webhooks).
+   */
+  csrf?: boolean
+
   /**
    * Called before server data fetchers on every request.
    * Return { redirect } to redirect, { status, json } for a custom response,

package/types/server.d.ts

@@ -72,6 +72,13 @@ export interface ServerOptions {
   /** Called on every request before routing. Return false to short-circuit Pulse handling. */
   onRequest?: (req: IncomingMessage, res: ServerResponse) => false | void | unknown
 
+  /**
+   * HMAC secret for CSRF tokens (spec.submit forms). Defaults to a random
+   * per-boot value — set a stable secret (e.g. from an env var) when running
+   * multiple instances so tokens issued by one instance validate on another.
+   */
+  secret?: string | null
+
   /**
    * Extra CSP sources to merge into the framework's default Content-Security-Policy.
    * Use this to allow external stylesheets, fonts, or API origins.