@invisibleloop/pulse 0.1.21

package/docs/src/pages/routing.js

@@ -0,0 +1,99 @@
+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('/routing')
+
+export default {
+  route: '/routing',
+  meta: {
+    title: 'Routing — Pulse Docs',
+    description: 'How Pulse routes requests to page specs — static and dynamic routes, params, and conventions.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/routing',
+    prev,
+    next,
+    content: `
+      ${h1('Routing')}
+      ${lead('Every route in Pulse is explicitly declared in the spec. There is no file-based routing, no magic directory conventions, and no implicit mapping. Every page\'s URL is visible in its spec file and nowhere else.')}
+
+      ${section('route-field', 'The route field')}
+      <p>Every spec has a <code>route</code> field. This is the URL pattern the spec handles:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/about',
+  state: {},
+  view: () => \`<h1>About</h1>\`,
+}`, 'js'))}
+      <p>Pulse matches the exact path. Trailing slashes are normalised — <code>/about</code> and <code>/about/</code> are treated the same.</p>
+
+      ${section('dynamic', 'Dynamic segments')}
+      <p>Use a colon prefix for dynamic path segments. Named segments are captured and available in <code>ctx.params</code> in <a href="/server-data">server data</a>:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/products/:id',
+  state: { quantity: 1 },
+  server: {
+    data: async (ctx) => {
+      // ctx.params.id is the captured segment
+      const product = await db.products.find(ctx.params.id)
+      return { product }
+    },
+  },
+  view: (state, server) => \`<h1>\${server.product.name}</h1>\`,
+}`, 'js'))}
+
+      ${section('multi-segment', 'Multiple dynamic segments')}
+      <p>Any number of dynamic segments can appear in a route:</p>
+      ${codeBlock(highlight(`route: '/blog/:year/:month/:slug'
+// Matches: /blog/2025/03/my-first-post
+// ctx.params = { year: '2025', month: '03', slug: 'my-first-post' }`, 'js'))}
+
+      ${section('registering', 'Registering routes')}
+      <p>Specs are registered explicitly by passing them to <code>createServer</code> as an array. Routes are matched in order — more specific routes must come before more general ones:</p>
+      ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
+import home     from './src/pages/home.js'
+import products from './src/pages/products.js'
+import product  from './src/pages/product.js'   // more specific — comes first
+import blog     from './src/pages/blog.js'
+
+createServer([home, product, products, blog], { port: 3000 })`, 'js'))}
+
+      ${section('query', 'Query strings')}
+      <p>Query string parameters are not part of the route pattern but are accessible via <code>ctx.query</code> in server data:</p>
+      ${codeBlock(highlight(`// URL: /products?category=shoes&sort=price
+server: {
+  data: async (ctx) => {
+    const { category, sort } = ctx.query
+    return { products: await db.products.list({ category, sort }) }
+  },
+}`, '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'))}
+
+      ${section('conventions', 'File naming conventions')}
+      <p>While Pulse does not auto-discover files, the recommended convention maps file names to routes:</p>
+      ${table(
+        ['File', 'Route'],
+        [
+          ['<code>src/pages/home.js</code>', '<code>/</code>'],
+          ['<code>src/pages/about.js</code>', '<code>/about</code>'],
+          ['<code>src/pages/products.js</code>', '<code>/products</code>'],
+          ['<code>src/pages/product.js</code>', '<code>/products/:id</code>'],
+          ['<code>src/pages/blog-post.js</code>', '<code>/blog/:slug</code>'],
+        ]
+      )}
+      ${callout('tip', 'The filename does not need to match the route exactly — it is just a helpful convention. A file named <code>product.js</code> can handle <code>/products/:id</code> without any issue.')}
+    `,
+  }),
+}

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

@@ -0,0 +1,281 @@
+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('/server-api')
+
+export default {
+  route: '/server-api',
+  meta: {
+    title: 'Server API — Pulse Docs',
+    description: 'Complete reference for createServer — all options, hooks, and response behaviour.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/server-api',
+    prev,
+    next,
+    content: `
+      ${h1('Server API')}
+      ${lead('<code>createServer(specs, options)</code> starts an HTTP server with all guarantees active. Specs are validated before the server accepts connections. SSR, streaming, brotli compression, immutable asset caching, security headers, CSP nonces, and HSTS are all handled automatically.')}
+
+      ${section('signature', 'createServer(specs, options)')}
+      ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
+
+createServer(specs, options)`, 'js'))}
+      ${table(
+        ['Parameter', 'Type', 'Description'],
+        [
+          ['<code>specs</code>', '<code>Spec[]</code>', 'Array of page spec objects. Validated at startup — a bad spec throws before the server accepts connections.'],
+          ['<code>options</code>', '<code>object</code>', 'Server configuration options (see below).'],
+        ]
+      )}
+
+      ${section('options', 'Options')}
+      ${table(
+        ['Option', 'Type', 'Default', 'Description'],
+        [
+          ['<code>port</code>', '<code>number</code>', '<code>3000</code>', 'Port to listen on.'],
+          ['<code>stream</code>', '<code>boolean</code>', '<code>true</code>', 'Enable streaming SSR globally. Individual specs also declare a <code>stream</code> field to opt in.'],
+          ['<code>staticDir</code>', '<code>string</code>', '<code>undefined</code>', 'Path to a directory of static files to serve. Relative to the process working directory.'],
+          ['<code>manifest</code>', '<code>string | object</code>', '<code>null</code>', 'Explicit manifest path or object. Overrides auto-detection from <code>staticDir/dist/manifest.json</code>.'],
+          ['<code>trailingSlash</code>', '<code>"remove" | "add" | "allow"</code>', '<code>"remove"</code>', '<code>"remove"</code> — 301 redirect <code>/about/</code> → <code>/about</code>. <code>"add"</code> — 301 redirect <code>/about</code> → <code>/about/</code>. <code>"allow"</code> — serve both, no redirect.'],
+          ['<code>store</code>', '<code>object</code>', '<code>null</code>', 'Global store definition (default export from <code>pulse.store.js</code>). See <a href="/store">Global Store</a>.'],
+          ['<code>maxBody</code>', '<code>number</code>', '<code>1048576</code>', 'Maximum request body size in bytes (default 1 MB). Requests exceeding this limit receive a 413 response.'],
+          ['<code>defaultCache</code>', '<code>boolean | number | object</code>', '<code>null</code>', 'Default HTML cache TTL for all pages in production. <code>true</code> = 1 h + 24 h SWR. A number sets <code>max-age</code> in seconds. An object accepts <code>{ public, maxAge, staleWhileRevalidate }</code>. <code>spec.cache</code> overrides per-page.'],
+          ['<code>fetcherTimeout</code>', '<code>number</code>', '<code>null</code>', 'Global timeout in milliseconds for all server fetchers. A fetcher that does not resolve within this limit rejects with a timeout error (→ 500). Override per page with <code>spec.serverTimeout</code>.'],
+          ['<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>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>.'],
+        ]
+      )}
+
+      ${section('example', 'Full example')}
+      ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
+import home    from './src/pages/home.js'
+import contact from './src/pages/contact.js'
+
+createServer([home, contact], {
+  port:      3000,
+  stream:    true,
+  staticDir: 'public',
+  onRequest: (req, res) => {
+    // Add custom headers
+    res.setHeader('X-My-Header', 'my-value')
+    // Return false to block a request
+    if (req.url.startsWith('/admin') && !isAuthenticated(req)) {
+      res.writeHead(401)
+      res.end('Unauthorized')
+      return false
+    }
+    // Return undefined (or nothing) to let Pulse handle it
+  },
+  onError: (err, req, res) => {
+    console.error(err)
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'text/html' })
+      res.end('<h1>Internal Server Error</h1>')
+    }
+  },
+})`, 'js'))}
+
+      ${section('multi-brand', 'Multi-brand sites')}
+      <p>One Pulse server can serve multiple brands, using the request domain as the key. Pass <code>resolveBrand</code> to <code>createServer</code> — it receives the <code>host</code> header and returns a brand config object of any shape you choose. The result is cached per host for 60 seconds and attached to <code>ctx.brand</code>.</p>
+      ${codeBlock(highlight(`// server.js
+createServer(specs, {
+  resolveBrand: async (host) => {
+    const slug = host.split('.')[0]          // 'acme' from 'acme.myco.com'
+    return db.brands.findBySlug(slug)        // { slug, name, accent, logo, ... }
+  }
+})`, 'js'))}
+      <p><code>ctx.brand</code> is available in <code>guard</code>, <code>server</code> fetchers, and any <code>meta</code> field. Meta fields can be functions that receive <code>ctx</code> — Pulse calls them per request:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/',
+
+  meta: {
+    title:       (ctx) => \`\${ctx.brand.name} — Home\`,
+    description: (ctx) => ctx.brand.tagline,
+    styles:      (ctx) => ['/pulse-ui.css', \`/themes/\${ctx.brand.slug}.css\`],
+  },
+
+  // Expose brand config to the view via server state
+  server: {
+    brand: (ctx) => ctx.brand,
+  },
+
+  view: (state, { brand }) => \`
+    <header>
+      <img src="\${brand.logo}" alt="\${brand.name}">
+      <nav>...</nav>
+    </header>
+    <main>...</main>
+  \`,
+
+  guard: async (ctx) => {
+    if (!ctx.brand) return { redirect: '/not-found' }
+  },
+}`, 'js'))}
+      ${callout('tip', 'Keep brand theme differences in CSS custom properties. One <code>/pulse-ui.css</code> handles layout and components — each <code>/themes/brand.css</code> only overrides <code>:root</code> variables like <code>--color-accent</code> and <code>--font-heading</code>. Theme files are typically under 1 kB.')}
+
+      ${section('startup-validation', 'Startup validation')}
+      <p>All specs are validated against the Pulse schema at startup. An invalid spec throws before the server accepts any connections — misconfigured specs are caught immediately, not when a user first hits the route. There is no silent failure path.</p>
+
+      ${section('static-files', 'Static file serving')}
+      <p>When <code>staticDir</code> is set, Pulse serves all files in that directory at their relative path. For example, a file at <code>public/app.css</code> is served at <code>/app.css</code>.</p>
+      <p>If <code>staticDir/dist/manifest.json</code> exists, Pulse automatically loads it to resolve production hydration bundle paths. No additional configuration is needed.</p>
+      ${codeBlock(highlight(`createServer(specs, {
+  staticDir: 'public',   // serves public/* at /*
+  // manifest auto-detected from public/dist/manifest.json
+})`, 'js'))}
+
+      ${section('response-behaviour', 'Response behaviour')}
+      ${table(
+        ['Request type', 'Response'],
+        [
+          ['Full page request (GET/HEAD)', 'SSR HTML with doctype, head, body, and optional hydration script'],
+          ['<code>X-Pulse-Navigate: true</code> header', 'JSON: <code>{ html, title, hydrate, serverState }</code> for client-side navigation'],
+          ['POST/PUT/DELETE to a raw response spec', 'Handled by <code>spec.render</code> — used for webhooks and API endpoints'],
+          ['POST/PUT/DELETE to a page spec', '405 Method Not Allowed'],
+          ['Static file', 'File contents with appropriate Content-Type'],
+          ['No matching route', '404 response'],
+        ]
+      )}
+
+      ${section('body-parsing', 'Reading request bodies')}
+      <p>Body parsing is available in <code>guard</code>, <code>server.*</code> fetchers, and <code>render</code> (raw specs). All methods are lazy — the stream is consumed once and the result is memoised per request.</p>
+      ${table(
+        ['Method', 'Returns', 'Description'],
+        [
+          ['<code>await ctx.json()</code>', '<code>object | null</code>', 'Parse a JSON request body. Returns <code>null</code> for an empty body.'],
+          ['<code>await ctx.text()</code>', '<code>string</code>', 'Read the body as a plain string.'],
+          ['<code>await ctx.formData()</code>', '<code>object | null</code>', 'Parse a URL-encoded body into a plain object. Returns <code>null</code> for an empty body.'],
+          ['<code>await ctx.buffer()</code>', '<code>Buffer</code>', 'Read the raw body as a Node.js Buffer.'],
+        ]
+      )}
+      <p>Bodies larger than <code>maxBody</code> (default 1 MB) are rejected with a <strong>413</strong> before the handler runs. Set <code>maxBody</code> in <code>createServer</code> options to adjust.</p>
+      <p>Page specs only accept <strong>GET and HEAD</strong> by default — POST returns 405. To accept other methods, declare <code>spec.methods</code>:</p>
+      ${codeBlock(highlight(`export default {
+  route:   '/contact',
+  methods: ['GET', 'POST'],
+
+  guard: async (ctx) => {
+    if (ctx.method === 'POST') {
+      const data = await ctx.formData()
+      if (!data.email) return { status: 422, json: { error: 'Email required' } }
+      await db.leads.create(data)
+      return { redirect: '/contact?sent=1' }
+    }
+  },
+
+  state: {},
+  view: () => \`<form method="POST">...</form>\`,
+}`, 'js'))}
+      ${callout('note', 'Raw response specs (<code>contentType</code> set) accept any HTTP method without <code>spec.methods</code> — they are always method-agnostic.')}
+
+      ${section('escaping', 'Escaping user data')}
+      <p>Import <code>escHtml</code> from <code>@invisibleloop/pulse/html</code> to safely embed untrusted values in HTML view strings:</p>
+      ${codeBlock(highlight(`import { escHtml } from '@invisibleloop/pulse/html'
+
+view: (state) => \`
+  <p>Hello, \${escHtml(state.username)}</p>
+\``, 'js'))}
+      ${callout('warning', 'Always use <code>escHtml</code> around values that originate from user input, URL params, or external APIs. Omitting it is an XSS vulnerability.')}
+      <p>To use a nonce on a view-authored inline script, pass <code>ctx.nonce</code> through a server fetcher:</p>
+      ${codeBlock(highlight(`server: {
+  meta: async (ctx) => ({ nonce: ctx.nonce }),
+},
+
+view: (state, server) => \`
+  <script nonce="\${server.meta.nonce}">console.log('inline ok')</script>
+\``, 'js'))}
+      <p>Inline scripts without the matching nonce are blocked by the CSP.</p>
+
+      ${section('security-headers', 'Security headers')}
+      <p>Pulse sends the following headers on <strong>every</strong> response — including 404 and 500 errors. There is no configuration required and no way to accidentally omit them:</p>
+      ${codeBlock(highlight(`X-Content-Type-Options:       nosniff
+X-Frame-Options:              DENY
+Referrer-Policy:              strict-origin-when-cross-origin
+Permissions-Policy:           camera=(), microphone=(), geolocation=()
+Cross-Origin-Opener-Policy:   same-origin
+Cross-Origin-Resource-Policy: same-origin`, 'bash'))}
+
+      ${section('csp', 'Content Security Policy')}
+      <p>HTML page responses include a <code>Content-Security-Policy</code> header. Scripts require a per-request cryptographic nonce; stylesheets are restricted to same-origin; everything else defaults to <code>'none'</code>:</p>
+      ${codeBlock(highlight(`Content-Security-Policy:
+  default-src 'none';
+  script-src 'self' 'nonce-{random}';
+  style-src 'self';
+  style-src-attr 'unsafe-inline';
+  img-src 'self' data:;
+  font-src 'self';
+  connect-src 'self';
+  frame-ancestors 'none';
+  base-uri 'self';
+  form-action 'self'`, 'bash'))}
+      <p>All inline scripts injected by the framework carry a matching <code>nonce</code> attribute. The nonce is also available as <code>ctx.nonce</code> so view functions can attach it to their own inline scripts.</p>
+      <p>To load resources from external origins — Google Fonts, a CDN, an external API — pass a <code>csp</code> object to <code>createServer</code>. Sources are merged into the framework defaults; existing directives are not replaced:</p>
+      ${codeBlock(highlight(`createServer(specs, {
+  csp: {
+    'style-src': ['https://fonts.googleapis.com'],
+    'font-src':  ['https://fonts.gstatic.com'],
+    'connect-src': ['https://api.example.com'],
+    'img-src': ['https://images.unsplash.com'],
+  },
+})`, 'js'))}
+      ${callout('note', 'The <code>style-src-attr \'unsafe-inline\'</code> directive is required for inline <code>style="..."</code> attributes used by the UI component library to set CSS custom properties (e.g. spinner size, progress fill). It is scoped to attributes only — <code>&lt;style&gt;</code> blocks are fully nonce-controlled.')}
+
+      ${section('hsts', 'HSTS')}
+      <p>When a request arrives with <code>x-forwarded-proto: https</code> (or over a TLS socket), Pulse adds:</p>
+      ${codeBlock(highlight(`Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`, 'bash'))}
+      <p>This is automatic — no configuration required. On plain HTTP the header is omitted. The <code>preload</code> directive means you can submit the domain to <a href="https://hstspreload.org" target="_blank" rel="noopener">hstspreload.org</a> so browsers enforce HTTPS before the first connection — this is a separate manual step, not automatic.</p>
+
+      ${section('cookies', 'Cookie defaults')}
+      <p>Cookies set via <code>ctx.setCookie()</code> default to <code>SameSite=Lax</code>. CSRF protection is on by default — omitting a <code>sameSite</code> option does not weaken it.</p>
+
+      ${section('compression', 'Compression')}
+      <p>Pulse compresses all compressible responses using brotli (preferred) or gzip (fallback), based on the <code>Accept-Encoding</code> header. Streaming responses use transform streams so compression and delivery happen concurrently.</p>
+
+      ${section('nav-header', 'X-Pulse-Navigate header')}
+      <p>When a request includes <code>X-Pulse-Navigate: true</code>, Pulse returns a JSON response instead of full HTML. This is used by the client-side navigation system to swap page content without a full reload:</p>
+      ${codeBlock(highlight(`{
+  "html":        "<main>...rendered content...</main>",
+  "title":       "Page Title — Site",
+  "hydrate":     "/dist/page.boot-abc123.js",
+  "serverState": { "product": { "id": 1, "name": "..." } }
+}`, 'js'))}
+
+      ${section('health-check', 'Health check endpoint')}
+      <p>Pulse exposes a built-in health check at <code>/healthz</code> (configurable). It responds before <code>onRequest</code>, static file serving, and route matching — so load balancers and orchestration systems always get a response even if a hook is faulty.</p>
+      ${codeBlock(highlight(`GET /healthz → 200 OK
+{ "status": "ok", "uptime": 42.3 }`, 'json'))}
+      <p>Configure the path or disable it entirely:</p>
+      ${codeBlock(highlight(`createServer(specs, {
+  healthCheck: '/ping',   // custom path
+  // healthCheck: false,  // disable
+})`, 'js'))}
+      ${callout('note', '<code>HEAD /healthz</code> is also supported — returns the same status headers with no body. The endpoint sets <code>Cache-Control: no-store</code> so proxies never serve a stale health status.')}
+
+      ${section('graceful-shutdown', 'Graceful shutdown')}
+      <p>Pulse registers <code>SIGTERM</code> and <code>SIGINT</code> handlers automatically. When either signal arrives:</p>
+      <ol>
+        <li><code>server.close()</code> stops accepting new connections.</li>
+        <li>Idle keep-alive sockets are destroyed immediately.</li>
+        <li>In-flight requests are allowed to finish naturally.</li>
+        <li>After <code>shutdownTimeout</code> ms (default 30 000 ms), the process force-exits to prevent a stuck request from blocking a deploy indefinitely.</li>
+      </ol>
+      <p>The <code>shutdown()</code> function is also returned from <code>createServer</code> so you can trigger it programmatically:</p>
+      ${codeBlock(highlight(`const { server, shutdown } = createServer(specs, {
+  port:            3000,
+  shutdownTimeout: 10000,  // 10 s — override the 30 s default
+})
+
+// SIGTERM is already wired automatically.
+// Call manually when needed — idempotent, safe to call multiple times.
+shutdown()`, 'js'))}
+      ${callout('note', 'Idle keep-alive sockets are destroyed immediately on shutdown. In-flight streaming responses finish sending before the socket is closed — no partial responses are delivered to clients.')}
+    `,
+  }),
+}

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

@@ -0,0 +1,185 @@
+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('/server-data')
+
+export default {
+  route: '/server-data',
+  meta: {
+    title: 'Server Data — Pulse Docs',
+    description: 'Fetch, transform, and combine data on the server before rendering — external APIs, multiple fetchers, parallel requests.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/server-data',
+    prev,
+    next,
+    content: `
+      ${h1('Server Data')}
+      ${lead('The <code>server</code> field fetches data before the page renders. It runs exclusively on the server — credentials, database access, and API secrets stay there. The browser never receives the fetcher code, only its serialised output.')}
+
+      ${section('basic', 'Basic usage')}
+      <p>Declare a <code>data</code> async function inside the <code>server</code> object. It receives a <code>ctx</code> object with request context and returns a plain object:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/products/:id',
+  state: { quantity: 1 },
+  server: {
+    data: async (ctx) => {
+      const product = await db.products.findById(ctx.params.id)
+      const related = await db.products.findRelated(product.category)
+      return { product, related }
+    },
+  },
+  view: (state, server) => \`
+    <main>
+      <h1>\${server.product.name}</h1>
+      <p>\${server.product.description}</p>
+      <p>Price: £\${server.product.price}</p>
+      <div class="quantity">
+        <button data-event="decrement">-</button>
+        <span>\${state.quantity}</span>
+        <button data-event="increment">+</button>
+      </div>
+    </main>
+  \`,
+}`, 'js'))}
+
+      ${section('ctx', 'The ctx object')}
+      <p>The <code>ctx</code> argument passed to <code>server.data()</code> contains the full request context:</p>
+      ${table(
+        ['Property', 'Type', 'Description'],
+        [
+          ['<code>ctx.params</code>', '<code>object</code>', 'URL path parameters from dynamic route segments (e.g. <code>:id</code>).'],
+          ['<code>ctx.query</code>', '<code>object</code>', 'Parsed query string parameters (e.g. <code>?page=2&sort=asc</code>).'],
+          ['<code>ctx.headers</code>', '<code>object</code>', 'Incoming request headers (lowercase keys).'],
+          ['<code>ctx.cookies</code>', '<code>object</code>', 'Parsed cookies from the <code>Cookie</code> header.'],
+        ]
+      )}
+      ${codeBlock(highlight(`server: {
+  data: async (ctx) => {
+    // Dynamic route: /blog/:year/:slug
+    const { year, slug } = ctx.params
+
+    // Query string: ?page=2
+    const page = parseInt(ctx.query.page ?? '1', 10)
+
+    // Authentication via cookie
+    const session = ctx.cookies.sessionId
+      ? await sessions.find(ctx.cookies.sessionId)
+      : null
+
+    const post = await db.posts.findBySlug(year, slug)
+    return { post, page, session }
+  },
+}`, 'js'))}
+
+      ${section('view-arg', 'Server state in the view')}
+      <p>The resolved values from all server fetchers are merged into a single object and passed to the <code>view</code> function as its second argument, conventionally named <code>server</code>. Each fetcher key becomes a property:</p>
+      ${codeBlock(highlight(`// server: { post: async (ctx) => ... }
+
+view: (state, server) => \`
+  <article>
+    <h1>\${server.post.title}</h1>
+    <time>\${server.post.date}</time>
+    \${server.post.body}
+  </article>
+\``, 'js'))}
+      ${callout('note', 'If no <code>server</code> fetchers are declared, the second argument to <code>view</code> is an empty object <code>{}</code>.')}
+
+      ${section('ssr-only', 'SSR only — not available on the client')}
+      <p>Server data is resolved before the HTML is generated and is never re-fetched in the browser. After hydration, the serialised output is available to the view as <code>window.__PULSE_SERVER__</code> for client-side re-renders — it is the same value the server computed, not a new request.</p>
+      ${callout('warning', 'Server state is serialised into the page HTML as <code>window.__PULSE_SERVER__</code> and is visible to anyone who views source. Filter fetcher output to only what the view needs — never include credentials, internal IDs, or user data beyond what must be rendered.')}
+
+      ${section('errors', 'Error handling')}
+      <p>If <code>server.data()</code> throws, the server returns a 500 error response. Handle errors gracefully by catching inside the function and returning a safe fallback:</p>
+      ${codeBlock(highlight(`server: {
+  data: async (ctx) => {
+    try {
+      const product = await db.products.findById(ctx.params.id)
+      if (!product) return { product: null, notFound: true }
+      return { product, notFound: false }
+    } catch (err) {
+      console.error('Failed to load product', err)
+      return { product: null, notFound: true }
+    }
+  },
+},
+view: (state, server) => server.notFound
+  ? \`<p>Product not found.</p>\`
+  : \`<h1>\${server.product.name}</h1>\``, 'js'))}
+
+      ${section('multiple-fetchers', 'Multiple named fetchers')}
+      <p>The <code>server</code> object supports any number of named async functions. Each one receives <code>ctx</code> and its return value is available on <code>server</code> in the view under the same key. Fetchers run in parallel — the page renders once all have resolved:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/products/:id',
+  state: { quantity: 1 },
+  server: {
+    product: async (ctx) => db.products.findById(ctx.params.id),
+    reviews: async (ctx) => db.reviews.forProduct(ctx.params.id),
+    related: async (ctx) => db.products.related(ctx.params.id),
+  },
+  view: (state, server) => \`
+    <h1>\${server.product.name}</h1>
+    <p>\${server.reviews.length} reviews</p>
+    \${server.related.map(p => \`<a href="/products/\${p.id}">\${p.name}</a>\`).join('')}
+  \`,
+}`, 'js'))}
+
+      ${section('external-apis', 'External API fetching')}
+      <p>Server fetchers run in Node.js. API keys and credentials are read from environment variables and never leave the server — only the fetcher's return value is serialised into the page:</p>
+      ${codeBlock(highlight(`server: {
+  weather: async (ctx) => {
+    const res = await fetch(
+      \`https://api.weather.example.com/current?city=\${ctx.query.city}\`,
+      { headers: { Authorization: \`Bearer \${process.env.WEATHER_API_KEY}\` } }
+    )
+    if (!res.ok) return null
+    return res.json()
+  },
+}`, 'js'))}
+
+      ${section('transforming', 'Transforming API responses')}
+      <p>Fetchers are the right place to reshape external responses before they reach the view. Filter to only what the view needs — this reduces payload size and prevents internal fields from being serialised into the page HTML:</p>
+      ${codeBlock(highlight(`server: {
+  article: async (ctx) => {
+    const res  = await fetch(\`https://cms.example.com/articles/\${ctx.params.slug}\`)
+    const data = await res.json()
+
+    // Shape and filter before serialisation
+    return {
+      title:       data.fields.title,
+      body:        data.fields.bodyHtml,
+      publishedAt: new Date(data.sys.createdAt).toLocaleDateString('en-GB'),
+      author:      data.fields.author.name,
+      // data.sys.revision, internal IDs etc. are dropped here
+    }
+  },
+}`, 'js'))}
+
+      ${section('parallel', 'Parallel fetches within a single fetcher')}
+      <p>When multiple independent requests are needed inside a single fetcher, <code>Promise.all</code> runs them concurrently so the total wait time is the slowest request, not the sum:</p>
+      ${codeBlock(highlight(`server: {
+  page: async (ctx) => {
+    const [hero, featured, nav] = await Promise.all([
+      fetch('https://cms.example.com/hero').then(r => r.json()),
+      fetch('https://cms.example.com/featured').then(r => r.json()),
+      fetch('https://cms.example.com/nav').then(r => r.json()),
+    ])
+    return { hero, featured, nav }
+  },
+}`, 'js'))}
+
+      ${section('caching-link', 'Caching server data')}
+      <p>Use <a href="/caching"><code>serverTtl</code></a> to cache fetcher results in-process for a number of seconds. This avoids hitting external APIs or a database on every request for data that changes infrequently.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/homepage',
+  serverTtl: 60,  // cache all server fetchers for 60 seconds
+  server: {
+    featured: async () => fetch('https://api.example.com/featured').then(r => r.json()),
+  },
+}`, 'js'))}
+    `,
+  }),
+}

package/docs/src/pages/slash-commands.js

@@ -0,0 +1,55 @@
+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('/slash-commands')
+
+export default {
+  route: '/slash-commands',
+  meta: {
+    title: 'Slash Commands — Pulse Docs',
+    description: 'The built-in slash commands available in the Pulse AI agent session.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/slash-commands',
+    prev,
+    next,
+    content: `
+      ${h1('Slash Commands')}
+      ${lead('Slash commands close the development loop inside the agent session. Building, auditing, and verifying performance happen without leaving the conversation — and every audit is checked against the thresholds you have declared in config.')}
+
+      ${section('commands', 'Available commands')}
+      ${table(
+        ['Command', 'What it does'],
+        [
+          ['<code>/pulse-dev</code>',    'Starts (or restarts) the development server. The server watches for file changes and reloads automatically.'],
+          ['<code>/pulse-stop</code>',   'Stops the running development server.'],
+          ['<code>/pulse-build</code>',  'Runs a production build. Bundles all specs via esbuild into <code>public/dist/</code> with content-hashed filenames.'],
+          ['<code>/pulse-start</code>',  'Starts the production server against the built output. Used to verify production behaviour before deploying.'],
+          ['<code>/pulse-report</code>', 'Runs a Lighthouse audit against a production build and opens the performance report dashboard. Captures Performance score, web vitals, bundle sizes, and request counts.'],
+        ]
+      )}
+
+      ${section('usage', 'Using commands')}
+      <p>Commands are typed directly into the agent chat:</p>
+      ${codeBlock(highlight(`/pulse-dev
+/pulse-report`, 'bash'))}
+      <p>The agent executes the relevant CLI steps and reports back with results, including whether any Lighthouse score or Core Web Vitals metric failed a configured threshold.</p>
+
+      ${callout('note', '<code>/pulse-report</code> performs a full production build before auditing. This guarantees accurate scores and correct brotli-compressed bundle sizes — development builds are unminified and serve no production metrics.')}
+
+      ${section('plain-language', 'Plain language prompts')}
+      <p>Slash commands cover the most common operations. For everything else, describe the goal — the agent handles the implementation within Pulse's spec structure:</p>
+      ${codeBlock(highlight(`"Create a blog index page that fetches posts from an API"
+"Add email validation to the contact form"
+"Build a checkout flow with a Stripe payment step"
+"Add a guard to the dashboard so unauthenticated users are redirected to /login"`, 'bash'))}
+      <p>The agent produces spec files that conform to Pulse's structure — the framework enforces correctness, so there is no manual wiring to verify.</p>
+
+      ${section('report-dashboard', 'Performance report dashboard')}
+      <p>The report dashboard is available at <code>/_pulse/report</code> when the dev server is running. It shows a history of Lighthouse audits across all pages — Performance score, Core Web Vitals, bundle sizes, and request counts. Threshold failures are highlighted. Each audit is saved to <code>.pulse/reports/</code> as JSON.</p>
+    `,
+  }),
+}