@invisibleloop/pulse 0.1.21

package/src/agent/guide-components.md

@@ -0,0 +1,274 @@
+## UI components — MANDATORY
+
+**RULE: Before writing any HTML, check whether a Pulse UI component exists for the purpose. If it does, you MUST use it. Raw HTML is only permitted for structural tags with no component equivalent (div, main, aside, footer, header).**
+
+**RULE: All components accept a `class` prop — never `className` (that is React). Use `class` to add utility classes or custom identifiers to any component.**
+
+Import only what you use. Icons are included — no third-party library needed. Always include `/pulse-ui.css` in `meta.styles`:
+```js
+import { nav, hero, feature, button, card, stat, grid, section, container, iconZap, iconShield, iconCheck } from '@invisibleloop/pulse/ui'
+meta: { styles: ['/pulse-ui.css', '/app.css'] }
+```
+
+Interactive components (carousel, tooltip) also need `/pulse-ui.js` in `meta.scripts`. Modal is handled natively by the Pulse runtime — no extra script needed.
+
+### Charts
+
+Server-rendered SVG charts — no JS, no dependencies. Drop into any card, section, or grid.
+
+```js
+import { barChart, lineChart, donutChart, sparkline } from '@invisibleloop/pulse/ui'
+
+barChart({
+  data: [{ label: 'Jan', value: 42 }, { label: 'Feb', value: 78 }],
+  color: 'accent',       // accent · success · warning · error · blue · muted
+  showValues: true,
+  showGrid: true,
+  gap: 0.25,
+  height: 220,
+})
+
+lineChart({
+  data: [{ label: 'Jan', value: 42 }, ...],
+  color: 'accent',
+  area: true,
+  showDots: true,
+  height: 220,
+})
+
+donutChart({
+  data: [
+    { label: 'Satisfied',   value: 73, color: 'success' },
+    { label: 'Neutral',     value: 18, color: 'muted'   },
+    { label: 'Unsatisfied', value: 9,  color: 'error'   },
+  ],
+  size: 200, thickness: 40, label: '73%', sublabel: 'satisfied',
+})
+
+sparkline({ data: [12,18,14,22,19,28], color: 'success', area: true })
+```
+
+Charts compose naturally:
+```js
+card({ title: 'Monthly signups', content: barChart({ data, height: 180 }) })
+grid({ cols: 2, content:
+  card({ title: 'Revenue', content: barChart({ data: monthly, color: 'accent' }) }) +
+  card({ title: 'Traffic', content: lineChart({ data: daily,  color: 'blue', area: true }) }),
+})
+```
+
+### Icons
+
+55 built-in icons — no third-party library needed. All are pure functions: `iconName({ size, class, bg, bgColor }) => svgString`.
+
+Props: `size` (px, default 16), `class`, `bg` ('circle' or 'square'), `bgColor` (accent/success/warning/error/muted).
+
+```js
+import { iconCheck, iconZap, iconShield, iconTrash } from '@invisibleloop/pulse/ui'
+
+feature({ icon: iconZap({ size: 20 }) })
+button({ label: 'Delete', variant: 'danger', icon: iconTrash({ size: 14 }) })
+iconZap({   size: 20, bg: 'circle', bgColor: 'accent'  })
+iconCheck({ size: 20, bg: 'circle', bgColor: 'success' })
+```
+
+Available icons:
+- **Navigation:** iconArrowLeft/Right/Up/Down, iconChevronLeft/Right/Up/Down, iconExternalLink, iconMenu, iconX, iconMoreHorizontal, iconMoreVertical
+- **Hand Pointers:** iconHandPointUp/Down/Left/Right
+- **Status:** iconCheck, iconCheckCircle, iconXCircle, iconAlertCircle, iconAlertTriangle, iconInfo
+- **Actions:** iconPlus, iconMinus, iconEdit, iconTrash, iconCopy, iconSearch, iconFilter, iconDownload, iconUpload, iconRefresh, iconSend
+- **UI Controls:** iconEye, iconEyeOff, iconLock, iconUnlock, iconSettings, iconBell
+- **People:** iconUser, iconUsers, iconMail, iconMessageSquare
+- **Pages:** iconHome, iconLogOut, iconLogIn
+- **Content:** iconFile, iconImage, iconLink, iconCode, iconCalendar, iconClock, iconBookmark, iconTag
+- **Media:** iconPlay, iconPause, iconVolume, iconStar, iconHeart
+- **Misc:** iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconPhone, iconGamepad, iconBug
+
+**Never use emoji in UI output.** Use icons instead.
+
+To add a missing icon: copy a Lucide path (MIT) into `src/ui/icons.js` using `s(paths, opts(o))` for stroke or `f(paths, opts(o))` for fill, export from `src/ui/index.js`.
+
+### Form components
+
+| Component | Key props |
+|-----------|-----------|
+| `button` | `label`, `variant` (primary/secondary/ghost/danger), `size` (sm/md/lg), `href`, `type`, `disabled`, `fullWidth`, `icon`, `iconAfter`, `attrs` |
+| `input` | `name`, `label`, `type`, `placeholder`, `value`, `error`, `hint`, `required`, `disabled`, `attrs` |
+| `search` | `name`, `label`, `labelHidden`, `placeholder`, `value`, `event` (e.g. `'input:setSearch'`), `debounce` (ms, default 200), `clearEvent` (shown when value non-empty), `disabled`, `attrs` — search input with icon + clear button. **Use this instead of `input({ type: 'search' })`.** |
+| `select` | `name`, `label`, `options` (strings or `{value,label}`), `value`, `error`, `required`, `event` |
+| `textarea` | `name`, `label`, `placeholder`, `value`, `rows`, `error`, `hint`, `required`, `disabled`, `attrs` |
+| `fieldset` | `legend`, `content` (HTML slot), `gap` (xs/sm/md/lg) |
+| `toggle` | `name`, `label`, `checked`, `disabled`, `hint`, `id`, `event` — iOS-style switch; reads as `'on'` in FormData |
+| `fileUpload` | `name`, `label`, `hint`, `error`, `accept`, `multiple`, `required`, `disabled`, `event` — drag-and-drop zone. **Never use `input({ type: 'file' })` for file uploads — always use `fileUpload()`.** |
+| `slider` | `name`, `label`, `min`, `max`, `step`, `value`, `disabled`, `hint`, `event` — use `change:mutationName` not `input` |
+| `segmented` | `name`, `options` ([{value,label}]), `value`, `size`, `disabled`, `event` — iOS-style segmented control. `value` must match an `options[].value` entry exactly — ensure `state` is initialised with a default that matches one of the option values. |
+| `radio` | `name`, `value`, `label`, `checked`, `disabled`, `id`, `event` |
+| `radioGroup` | `name`, `legend`, `options` ([{value,label,hint?,disabled?}]), `value`, `hint`, `error`, `gap`, `event` |
+| `rating` | `value` (0–max, 0.5 steps), `max` (5), `name` (enables interactive mode), `label`, `size`, `disabled` |
+
+### Display components
+
+| Component | Key props |
+|-----------|-----------|
+| `card` | `title`, `level` (1–6, default 3 — heading tag for title; visual style unchanged), `content` (HTML slot), `footer` (HTML slot), `flush` (full-bleed — removes body padding) |
+| `alert` | `variant` (info/success/warning/error), `title`, `content` |
+| `badge` | `label`, `variant` (default/success/warning/error/info) |
+| `stat` | `label`, `value`, `change`, `trend` (up/down/neutral), `center` |
+| `avatar` | `src`, `alt`, `size` (sm/md/lg/xl), `initials` |
+| `empty` | `title`, `description`, `action` ({label,href,variant}) |
+| `table` | `headers`, `rows` (2D array of HTML strings), `caption` |
+| `spinner` | `size` (sm/md/lg), `color` (accent/muted/white), `label` |
+| `progress` | `value`, `max` (100), `label`, `showLabel`, `showValue`, `variant`, `size` |
+| `breadcrumbs` | `items` ([{label,href}] — last item has no href), `separator` |
+| `stepper` | `steps` (array of label strings), `current` (0-based) |
+| `uiImage` | `src`, `alt`, `caption`, `ratio`, `rounded`, `pill`, `width`, `height`, `maxWidth` |
+| `pullquote` | `quote`, `cite`, `size` (md/lg) |
+| `timeline` | `direction` (vertical/horizontal), `items` ([{dot,dotColor,label,content}]) |
+| `timelineItem` | `content`, `label`, `dot`, `dotColor` (accent/success/warning/error/muted) |
+
+### Typography components
+
+| Component | Key props |
+|-----------|-----------|
+| `heading` | `level` (1–6), `text`, `size` (xs–4xl, overrides level default), `color` (default/muted/accent), `balance` (true — prevents orphaned words) |
+| `list` | `items` (array of HTML strings), `ordered`, `gap` (xs/sm/md) |
+| `prose` | `content` (raw HTML — not escaped), `size` (sm/base/lg) — for CMS/markdown content you don't control |
+
+**Never write raw `<h1>`–`<h6>` or `<ul>`/`<ol>` without styling.** Use `heading()` and `list()` instead.
+
+**Heading order across components.** `card`, `feature`, `section`, `pricing`, `cta`, and `modal` all accept a `level` prop. Use it to keep the document outline correct without changing visual style. For example, if a page has an h2 section title and each card inside it has a title, pass `level: 3` on the cards (the default) — but if the cards are the first heading on the page, pass `level: 2`. The CSS class stays the same (`ui-card-title` etc.) so appearance is unaffected.
+
+**`balance: true`** on `heading()` prevents orphaned words. Apply to any heading the verification orphan check flags.
+
+Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`list()` when writing content yourself.
+
+### Landing page components
+
+| Component | Key props |
+|-----------|-----------|
+| `nav` | `logo` (HTML slot), `logoHref`, `links` ([{label,href}]), `action` (HTML slot), `sticky` |
+| `hero` | `eyebrow`, `title`, `subtitle`, `actions` (HTML slot), `align` (center/left), `size` (md/sm) |
+| `feature` | `icon` (HTML slot), `title`, `level` (1–6, default 3), `description`, `center` |
+| `testimonial` | `quote`, `name`, `role`, `src`, `rating` (1–5) |
+| `pricing` | `name`, `level` (1–6, default 3), `price`, `period`, `features` ([strings]), `action` (HTML slot), `highlighted` |
+| `accordion` | `items` ([{title,content}]) — native `<details>`, no JS |
+| `appBadge` | `store` (apple/google), `href` |
+| `cta` | `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `actions` (HTML slot), `align` |
+
+### Layout components
+
+| Component | Key props |
+|-----------|-----------|
+| `container` | `content`, `size` (sm/md/lg/xl) |
+| `section` | `content`, `variant` (default/alt/dark), `padding` (sm/md/lg), `id`, `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `align` |
+| `grid` | `content`, `cols` (1–4), `gap` (sm/md/lg) — responsive, collapses on mobile |
+| `stack` | `content`, `gap` (xs–xl), `align` — flex column |
+| `cluster` | `content`, `gap`, `justify`, `align` — flex row with wrap |
+| `divider` | `label` |
+| `banner` | `content`, `variant` |
+| `media` | `image` (HTML slot), `content` (HTML slot), `reverse` — two-column image + text |
+| `codeWindow` | `content` (highlighted code HTML), `filename`, `lang` |
+| `footer` | `logo`, `logoHref`, `links`, `legal` |
+
+### Modal / dialog
+
+Use `modal()` + `modalTrigger()` (or `data-dialog-open`). **Never use `state.modalOpen` or conditional rendering** — this destroys the dialog element on every render, breaking focus, animation, and native ESC.
+
+```js
+import { modal, modalTrigger, button } from '@invisibleloop/pulse/ui'
+
+view: (state) => `
+  <main id="main-content">
+    <!-- Always in the DOM — never conditional -->
+    ${modal({
+      id:      'confirm',
+      title:   'Delete item?',
+      content: '<p>This cannot be undone.</p>',
+      footer:  button({ label: 'Delete', variant: 'danger', attrs: { 'data-dialog-close': '' } }),
+    })}
+
+    <!-- Opens the dialog — no spec state, no mutation needed -->
+    ${modalTrigger({ target: 'confirm', label: 'Delete', variant: 'ghost' })}
+
+    <!-- Or inline with any element -->
+    <button data-dialog-open="confirm">Delete</button>
+  </main>
+`
+```
+
+**How close works (all native — no JS needed):**
+- `<form method="dialog">` submit inside the modal (the X button uses this)
+- ESC key
+- Clicking the backdrop (outside the dialog content)
+- `data-dialog-close` attribute on any element inside or outside the dialog
+
+**`modal()` props:** `id` (required), `title`, `content`, `footer`, `size` (sm/md/lg/xl), `class`
+**`modalTrigger()` props:** `target` (dialog id), `label`, `variant`, `size`, `class`
+
+### Forms inside a modal
+
+**`modal()` wraps all content in `<form method="dialog">`. You cannot nest a `<form data-action="...">` inside it — browsers silently ignore nested forms, so the action will never fire.**
+
+When the modal action requires a Pulse action (e.g. confirm delete, submit settings), use the `form` HTML attribute to associate a button with an external form:
+
+```js
+view: (state) => `
+  <main id="main-content">
+    <!-- The action form lives OUTSIDE the modal -->
+    <form id="delete-form" data-action="deleteAccount" style="display:none"></form>
+
+    ${modal({
+      id:      'confirm-delete',
+      title:   'Delete account?',
+      content: '<p>This cannot be undone.</p>',
+      footer:
+        button({ label: 'Cancel',         variant: 'secondary', type: 'submit' }) +
+        button({ label: 'Confirm delete', variant: 'danger',    attrs: { form: 'delete-form', type: 'submit' } }),
+    })}
+
+    ${modalTrigger({ target: 'confirm-delete', label: 'Delete account', variant: 'danger' })}
+  </main>
+`
+```
+
+- **Cancel** — `type="submit"` with no `form` attribute submits the modal's own `<form method="dialog">`, closing it natively.
+- **Confirm** — `form="delete-form"` associates the button with the external form, triggering the Pulse action.
+- The hidden form needs no visible fields; `onStart` can read `state` directly for any data needed by the action.
+
+### Attaching Pulse events to components
+
+Pass events via `attrs` — must be an object:
+```js
+button({ label: 'Like',   attrs: { 'data-event': 'like' } })
+button({ label: 'Delete', attrs: { 'data-event': 'remove', 'data-id': item.id } })
+```
+
+### Typical landing page structure
+
+```js
+import { nav, hero, section, container, grid, feature, button } from '@invisibleloop/pulse/ui'
+
+view: () => `
+  ${nav({
+    logo:   'MyApp',
+    links:  [{ label: 'Docs', href: '/docs' }, { label: 'Pricing', href: '/pricing' }],
+    action: button({ label: 'Sign up', href: '/signup', variant: 'primary', size: 'sm' }),
+  })}
+  <main id="main-content">
+    ${hero({
+      eyebrow:  'Now in beta',
+      title:    'Build fast. Ship faster.',
+      subtitle: 'The framework that gets out of your way.',
+      actions:  button({ label: 'Get started →', href: '/docs', variant: 'primary', size: 'lg' }),
+    })}
+    ${section({ content: container({ content: grid({
+      cols:    3,
+      content: [
+        feature({ icon: iconZap({ size: 20, bg: 'circle' }),    title: 'Fast',    description: 'SSR always on.' }),
+        feature({ icon: iconShield({ size: 20, bg: 'circle' }), title: 'Safe',    description: 'Constraints enforced.' }),
+        feature({ icon: iconCheck({ size: 20, bg: 'circle' }),  title: 'Correct', description: '100 Lighthouse.' }),
+      ].join(''),
+    }) }) })}
+  </main>
+`
+```

package/src/agent/guide-examples.md

@@ -0,0 +1,54 @@
+## Example page — contact form
+
+```js
+import { nav, section, input, textarea, button, alert, container } from '@invisibleloop/pulse/ui'
+import { layout } from '../components/layout.js'
+
+export default {
+  meta: {
+    title:  'Contact',
+    styles: ['/app.css', '/pulse-ui.css'],
+  },
+  state: {
+    status: 'idle',
+    errors: [],
+  },
+  actions: {
+    send: {
+      onStart: (state, formData) => ({
+        status:  'loading',
+        name:    formData.get('name'),
+        email:   formData.get('email'),
+        message: formData.get('message'),
+      }),
+      run: async (state, serverState, formData) => {
+        const res = await fetch('/api/contact', { method: 'POST', body: formData })
+        if (!res.ok) throw new Error(await res.text())
+        return await res.json()
+      },
+      onSuccess: (state, result) => ({ status: 'success' }),
+      onError:   (state, err)    => ({
+        status: 'error',
+        errors: err?.validation ?? [{ message: err.message }],
+      }),
+    },
+  },
+  view: (state) => layout(`
+    ${container({ content: `
+      ${section({ title: 'Contact Us', subtitle: 'We will get back to you within 24 hours.' })}
+      ${state.status === 'success'
+        ? alert({ type: 'success', message: 'Message sent!' })
+        : `<form data-action="send" class="u-flex u-flex-col u-gap-4">
+            ${grid({ cols: 2, gap: 'md', content: `
+              ${input({ name: 'name',  label: 'Name',  placeholder: 'Your name',       required: true })}
+              ${input({ name: 'email', label: 'Email', type: 'email', placeholder: 'you@example.com', required: true })}
+            ` })}
+            ${textarea({ name: 'message', label: 'Message', rows: 5, required: true })}
+            ${state.errors.length ? alert({ type: 'error', message: state.errors[0].message }) : ''}
+            ${button({ label: state.status === 'loading' ? 'Sending…' : 'Send', type: 'submit', variant: 'primary', fullWidth: true })}
+          </form>`
+      }
+    ` })}
+  `),
+}
+```

package/src/agent/guide-routing.md

@@ -0,0 +1,36 @@
+## Site navigation
+
+Projects define navigation in src/components/layout.js via a NAV_LINKS array.
+To add a new page to the nav: edit NAV_LINKS in src/components/layout.js only — do NOT add links in individual page files.
+
+```js
+const NAV_LINKS = [
+  { label: 'Home', href: '/' },
+  { label: 'About', href: '/about' },  // ← add new pages here
+]
+```
+
+## Page discovery — no registration needed
+
+Pulse automatically discovers every .js file under src/pages/ and registers it as a route. You NEVER need to edit a server.js or register specs manually. Just create the file and it is live.
+
+File → derived route (used only when the spec has no route property):
+  src/pages/about.js          → /about
+  src/pages/blog.js           → /blog
+  src/pages/blog/index.js     → /blog
+  src/pages/home.js or index.js → /
+
+## Dynamic routes
+
+Use :param syntax in the spec's route property. The filename doesn't matter — name it [slug].js or post.js, it makes no difference. The route property controls matching.
+
+  route: '/blog/:slug'   ← param captured as ctx.params.slug
+
+The param is available in server fetchers and meta functions:
+  server: { post: async (ctx) => posts.find(p => p.slug === ctx.params.slug) ?? null }
+  meta:   { title: (ctx) => posts[ctx.params.slug]?.title ?? 'Not Found' }
+
+Convention: name dynamic-route files [param].js inside a subfolder:
+  src/pages/blog/[slug].js  with  route: '/blog/:slug'
+
+This is purely a human readability convention. Pulse does not process [ ] in filenames.

package/src/agent/guide-server.md

@@ -0,0 +1,258 @@
+## Cross-page state and persistence
+
+### Per-page persistence — `spec.persist`
+
+`spec.persist` is an array of state key names automatically saved to `localStorage` after every mutation/action, and restored on mount. Storage key is `pulse:/route-path` (scoped per route).
+
+```js
+export default {
+  route: '/cart',
+  state: { items: [], count: 0 },
+  persist: ['items', 'count'],  // survive page refresh
+}
+```
+
+Only declared keys are saved. Restored values that differ from the spec default trigger a re-render on mount (even after SSR).
+
+### Global store — `pulse.store.js`
+
+The global store is a shared data layer. Server fetchers run per request; mutations run on the client and broadcast to all subscribed pages without a server round-trip.
+
+**Define the store** in `pulse.store.js`:
+```js
+// pulse.store.js
+export default {
+  hydrate: '/pulse.store.js',                   // browser-importable path — required for mutations
+
+  state: {                                      // default/fallback values
+    user:     null,
+    settings: { theme: 'dark', lang: 'en' },
+    cart:     { count: 0 },
+  },
+  server: {                                     // async fetchers — run per request, server-side only
+    user:     async (ctx) => db.users.findByCookie(ctx.cookies.session),
+    settings: async (ctx) => db.settings.forUser(ctx.cookies.userId),
+  },
+  mutations: {                                  // synchronous client-side updates — broadcast to all subscribers
+    // Same contract as spec.mutations: (storeState, payload?) => Partial<storeState>
+    toggleTheme: (store) => ({
+      settings: { ...store.settings, theme: store.settings.theme === 'dark' ? 'light' : 'dark' },
+    }),
+    addToCart: (store, e) => ({
+      cart: { count: store.cart.count + 1 },
+    }),
+  },
+}
+```
+
+**Register the store** in your server file:
+```js
+import store from './pulse.store.js'
+createServer([...specs], { store })
+```
+
+**Use store data in a page** — declare `spec.store` with the keys needed. They appear in the view's `server` argument:
+```js
+export default {
+  route: '/dashboard',
+  store: ['user', 'settings'],        // declare which store keys this page uses
+  server: {
+    stats: async (ctx) => db.stats.forUser(ctx.store.user?.id),  // ctx.store available here
+  },
+  state: {},
+  view: (state, server) => `
+    <h1>Hello, ${server.user?.name}</h1>
+    <p>Theme: ${server.settings.theme}</p>
+    <p>Requests: ${server.stats.total}</p>
+  `,
+}
+```
+
+**Dispatch store mutations from any page** using `data-store-event` (same format as `data-event`):
+```html
+<button data-store-event="toggleTheme">Toggle theme</button>
+<button data-store-event="addToCart">Add to cart</button>
+<select data-store-event="change:setLang">...</select>
+```
+
+All pages that declare `spec.store` with the affected keys re-render automatically — no server round-trip, no page reload.
+
+- Store fetchers run **before** page server fetchers and guards — `ctx.store` is available in all of them
+- Only keys listed in `spec.store` are passed to the view — nothing leaks to pages that don't declare it
+- Page-level `server` keys win over store keys if there is a name collision
+- Pages with `spec.store` are never HTML-cached (same rule as pages with `spec.server`)
+
+**Reactive updates — no refresh needed**
+
+Return `_storeUpdate` from a page action's `onSuccess` to push a change into the global store. All mounted pages that subscribe to the affected keys re-render immediately:
+```js
+actions: {
+  saveTheme: {
+    run: async (state, server, payload) => {
+      await fetch('/api/settings', { method: 'PATCH', body: payload })
+      return payload.get('theme')
+    },
+    onSuccess: (state, theme) => ({
+      saved: true,
+      _storeUpdate: { settings: { theme } },  // ← broadcast to all subscribed pages
+    }),
+    onError: (state, err) => ({ error: err.message }),
+  },
+},
+```
+`_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 context — redirects, cookies, POST bodies
+
+The `ctx` object is available in `guard`, `server.*` fetchers, and `meta` functions.
+
+### Reading cookies
+`ctx.cookies` — plain object parsed from the request `Cookie` header:
+```js
+server: { user: async (ctx) => getUserByToken(ctx.cookies.session) }
+```
+
+### Redirects — use `guard`
+Return `{ redirect: '/path' }` from `guard` to redirect (302) before any data fetching.
+There is **no redirect mechanism from `server.*` fetchers** — use `guard` for that.
+```js
+guard: async (ctx) => {
+  if (!ctx.cookies.session) return { redirect: '/login' }
+}
+```
+
+### Setting cookies and headers
+`ctx.setCookie(name, value, opts)` — queues a `Set-Cookie` header. Options: `httpOnly`, `secure`, `path`, `maxAge`, `sameSite`, `domain`. Defaults: `Path=/`, `SameSite=Lax`.
+`ctx.setHeader(name, value)` — queues any arbitrary response header.
+
+### Reading the request body
+
+Body parsing is available in `guard`, `server.*` fetchers, and `render` (raw specs). All methods are lazy — the body stream is only consumed once and the result is memoised for the lifetime of the request.
+
+```js
+await ctx.json()      // parse JSON body → object | null
+await ctx.text()      // raw string body → string
+await ctx.formData()  // URL-encoded body → plain object | null
+await ctx.buffer()    // raw Buffer
+```
+
+Bodies larger than `maxBody` (default 1 MB, configurable in `createServer`) are rejected with a 413 response before the handler runs.
+
+**Page specs only accept GET/HEAD by default** (POST → 405). To handle POST on a page spec, opt in with `spec.methods`:
+
+```js
+export default {
+  route:   '/contact',
+  methods: ['GET', 'POST'],
+
+  guard: async (ctx) => {
+    if (ctx.method === 'POST') {
+      const data = await ctx.formData()
+      if (!data.email) return { redirect: '/contact?error=required' }
+      await db.leads.create(data)
+      // Flash cookie — consumed once, clears on next GET (see server fetcher below)
+      ctx.setCookie('flash_sent', '1', { maxAge: 30 })
+      return { redirect: '/contact' }
+    }
+  },
+
+  server: {
+    status: async (ctx) => {
+      const sent = ctx.cookies.flash_sent === '1'
+      if (sent) ctx.setCookie('flash_sent', '', { maxAge: 0 })  // clear immediately
+      return { sent, error: ctx.query?.error ?? null }
+    },
+  },
+
+  state: {},
+  view: (_state, server) => `
+    ${server.status.sent
+      ? '<p>Message sent!</p>'
+      : '<form method="POST">...</form>'
+    }
+  `,
+}
+```
+
+### Post-Redirect-Get (PRG) and success messages
+
+**Never use `?success=1` query params for success state.** They persist in the URL — refreshing re-shows the message, sharing the URL gives a false success to someone else, and it looks wrong.
+
+**Use a flash cookie instead:**
+
+1. After the POST succeeds: `ctx.setCookie('flash_sent', '1', { maxAge: 30 })` then redirect to the clean URL.
+2. In the `server.*` fetcher on the subsequent GET: read the cookie, then clear it immediately with `maxAge: 0`.
+3. Pass the flag to the view. On refresh the cookie is gone — the form renders normally.
+
+Error states (validation failures) are fine as query params (`?error=required`) because they are expected to persist until the user corrects the form.
+
+**Guard can return a custom HTTP response** (instead of a redirect) by returning `{ status, json?, body?, headers? }`:
+
+```js
+guard: async (ctx) => {
+  const token = ctx.headers.authorization
+  if (!token) return { status: 401, json: { error: 'Unauthorized' } }
+  // returning nothing lets the request proceed
+}
+```
+
+**Raw response specs** (`contentType` set) accept any HTTP method by default — use `ctx.method` and `await ctx.json()` / `ctx.text()` to build webhooks or JSON APIs:
+
+```js
+export default {
+  route:       '/api/hook',
+  contentType: 'application/json',
+  render: async (ctx) => {
+    const payload = await ctx.json()
+    await processWebhook(payload)
+    return JSON.stringify({ ok: true })
+  },
+}
+```
+
+## Health check endpoint
+
+Pulse exposes a built-in health check at `/healthz` by default. It responds **before** `onRequest`, static files, and route matching — so load balancers always get a response.
+
+```
+GET /healthz → 200 OK
+{ "status": "ok", "uptime": 42.3 }
+```
+
+Configure the path or disable it:
+
+```js
+createServer(specs, {
+  healthCheck: '/ping',   // custom path
+  // healthCheck: false,  // disable
+})
+```
+
+Key properties:
+- Bypasses `onRequest` — a faulty hook can't accidentally block health checks
+- `HEAD /healthz` is supported (no body)
+- `Cache-Control: no-store` — proxies never serve a stale health status
+- Fires before route matching — a user spec at `/healthz` is shadowed when the built-in is enabled
+
+## Graceful shutdown
+
+`createServer` registers `SIGTERM` and `SIGINT` handlers automatically. When either signal arrives:
+
+1. `server.close()` stops accepting new connections
+2. Idle keep-alive sockets are destroyed immediately
+3. In-flight requests are allowed to finish naturally
+4. A force-exit fires after `shutdownTimeout` ms (default 30 000 ms) to prevent a stuck request from blocking a deploy
+
+The `shutdown()` function is also returned from `createServer` so you can trigger it programmatically (useful in tests or custom process managers):
+
+```js
+const { server, shutdown } = createServer(specs, {
+  port: 3000,
+  shutdownTimeout: 10000,  // override default 30 s grace period
+})
+
+// Call manually when needed (SIGTERM is already wired up automatically)
+shutdown()
+```
+
+`shutdown()` is idempotent — calling it multiple times is safe.