@invisibleloop/pulse 0.17.2 → 0.18.0

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',
@@ -67,6 +68,13 @@ export const mySpec = {
   // query param, list it here so distinct values get distinct cache entries.
   cacheVary: ['q', 'page'],
 
+  // Sitemap inclusion (when createServer has sitemap: true).
+  // Static routes are included automatically — only set this to:
+  //   false              → exclude this page
+  //   true               → include a guarded page (excluded by default)
+  //   async () => [...]  → enumerate a dynamic :param route's URLs
+  sitemap: async () => (await db.posts.list()).map(p => `/blog/${p.slug}`),
+
   // Global store keys this page subscribes to — appears in view's server arg
   // Store mutations update all subscribed pages without a server round-trip
   store: ['user', 'cart'],
@@ -121,6 +129,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 +162,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 +287,13 @@ 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)
+    sitemap:      true,           // auto-serve /sitemap.xml + robots.txt from registered routes
+                                  // also accepts { origin: 'https://mysite.com' } to pin the URL origin;
+                                  // dynamic :param routes contribute via spec.sitemap enumerators;
+                                  // a physical sitemap.xml/robots.txt in staticDir always wins
+    robots:       null,           // robots.txt when sitemap on: null = auto, false = off, string = verbatim
     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/meta.js

@@ -115,6 +115,33 @@ meta: {
 }`, 'js'))}
       ${callout('note', '<strong>Streaming caveat:</strong> when <code>stream: true</code> (the default), the <code>&lt;head&gt;</code> is written before server fetchers resolve, so <code>serverState</code> will be <code>null</code> for streaming responses. If your canonical depends on server data, set <code>stream: false</code> on that spec, or derive it from <code>ctx.params</code> instead.')}
 
+      ${section('sitemap', 'Sitemap & robots.txt')}
+      <p>Pulse generates <code>/sitemap.xml</code> and <code>/robots.txt</code> from the registered routes — enable it with one option:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  sitemap: true,                          // or { origin: 'https://mysite.com' } to pin the origin
+})`, 'js'))}
+      <p>Static page routes are included automatically. Excluded by default: the <code>route: '*'</code> not-found page, raw content specs, guarded pages (set <code>sitemap: true</code> on the spec to opt one in), and any page with <code>sitemap: false</code>.</p>
+      <p>Dynamic <code>:param</code> routes can't be enumerated automatically — give them a <code>sitemap</code> enumerator or they are skipped (the server logs a startup hint listing them):</p>
+      ${codeBlock(highlight(`export default {
+  route: '/blog/:slug',
+  sitemap: async () => {
+    const posts = await db.posts.allPublished()
+    return posts.map(p => ({ path: \`/blog/\${p.slug}\`, lastmod: p.updatedAt }))
+  },
+  // entries are '/path' strings or { path, lastmod } objects
+}`, 'js'))}
+      ${table(
+        ['Where', 'Value', 'Effect'],
+        [
+          ['<code>createServer</code>', '<code>sitemap: true | { origin }</code>', 'Enables generation. Origin defaults to the request host; pin it for multi-domain setups.'],
+          ['<code>createServer</code>', '<code>robots: false | string</code>', 'Disable robots.txt, or serve a custom string verbatim. Default auto-generates allow-all + the Sitemap line.'],
+          ['spec', '<code>sitemap: false</code>', 'Exclude this page.'],
+          ['spec', '<code>sitemap: true</code>', 'Include a guarded page that would be excluded by default.'],
+          ['spec', '<code>sitemap: array | function</code>', 'Enumerate URLs — required for dynamic routes.'],
+        ]
+      )}
+      ${callout('note', 'A physical <code>sitemap.xml</code> or <code>robots.txt</code> in <code>staticDir</code> always wins over the generated one — drop a file in <code>public/</code> to take full manual control. For fully hand-built XML, see <a href="/raw-responses#sitemap">Raw Responses</a>.')}
+
       ${section('styles', 'Stylesheets')}
       <p>The <code>styles</code> array accepts any number of stylesheet URLs. They are emitted as <code>&lt;link rel="stylesheet"&gt;</code> tags in the <code>&lt;head&gt;</code> in the order declared:</p>
       ${codeBlock(highlight(`meta: {

package/docs/src/pages/raw-responses.js

@@ -66,6 +66,7 @@ export default {
 }`, 'js'))}
 
       ${section('sitemap', 'XML sitemap')}
+      ${callout('tip', 'For most sites you don\'t need a raw spec for this — set <code>sitemap: true</code> in <code>createServer</code> and Pulse generates <code>/sitemap.xml</code> and <code>robots.txt</code> from the registered routes automatically. See <a href="/meta#sitemap">Metadata &amp; SEO</a>. Write a raw sitemap spec only when you need full control over the XML.')}
       ${codeBlock(highlight(`export default {
   route: '/sitemap.xml',
   contentType: 'application/xml',

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,11 @@ 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>sitemap</code>', '<code>boolean | { origin }</code>', '<code>false</code>', 'Auto-serve <code>/sitemap.xml</code> + <code>robots.txt</code> from the registered routes. Dynamic <code>:param</code> routes contribute via <code>spec.sitemap</code> enumerators. See <a href="/meta#sitemap">Metadata &amp; SEO</a>.'],
+          ['<code>robots</code>', '<code>string | false</code>', 'auto', 'robots.txt behaviour when sitemap is enabled — <code>false</code> disables, a string is served verbatim.'],
           ['<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.18.0",
   "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.18.0

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,52 @@ 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.
+
+## Sitemap & robots.txt
+
+Enable in `pulse.config.js` / `createServer` — the framework serves `/sitemap.xml` and `/robots.txt` generated from the registered routes:
+
+```js
+// pulse.config.js
+export default {
+  sitemap: true,                              // or { origin: 'https://mysite.com' } to pin the origin
+}
+```
+
+- **Static routes are included automatically.** Excluded by default: `route: '*'`, raw content specs, guarded pages (set `sitemap: true` on the spec to opt a guarded page in), and `sitemap: false` pages.
+- **Dynamic `:param` routes need an enumerator** or they are skipped (a startup hint lists them):
+
+```js
+export default {
+  route:   '/blog/:slug',
+  sitemap: async () => (await db.posts.list()).map(p => ({ path: `/blog/${p.slug}`, lastmod: p.updatedAt })),
+  // entries can be '/path' strings or { path, lastmod } objects
+}
+```
+
+- `robots: false` disables robots.txt; a string serves verbatim. A physical `sitemap.xml`/`robots.txt` in `staticDir` always wins over the generated one.
+- **Always enable this on production sites** — it is one config line and crawlers need it.
+
 ## 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.