@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/deploy.js

@@ -1,233 +0,0 @@
-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('/deploy')
-
-export default {
-  route: '/deploy',
-  meta: {
-    theme:       'light',
-    title: 'Deployment — Pulse Docs',
-    description: 'Deploy a Pulse app to a VPS, Docker, Fly.io, Railway, or Render.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/deploy',
-    prev,
-    next,
-    content: `
-      ${h1('Deployment')}
-      ${lead('Pulse deploys as a single Node.js process. No adapters, no serverless wrapping, no separate static file server required. Build once, run anywhere Node 22+ runs. All guarantees — security headers, brotli compression, immutable asset caching — are active in production automatically.')}
-
-      ${section('build', 'Build')}
-      <p>Run the production build before deploying:</p>
-      ${codeBlock(highlight(`npm run build`, 'bash'))}
-      <p>This generates content-hashed bundles in <code>public/dist/</code> and writes <code>public/dist/manifest.json</code>. The server reads the manifest at startup to resolve hydration script paths.</p>
-      ${callout('warning', 'Without a manifest, the server falls back to serving source files directly — no compression, no content-hashed filenames, and no <code>immutable</code> cache headers. Always run <code>npm run build</code> before deploying to production.')}
-
-      ${section('files', 'What to deploy')}
-      ${table(
-        ['Include', 'Reason'],
-        [
-          ['<code>src/</code>',                            'Page specs — imported by the server at runtime'],
-          ['<code>public/</code>',                         'Static assets and built bundles (<code>public/dist/</code>)'],
-          ['<code>server.js</code>',                       'Entry point'],
-          ['<code>pulse.config.js</code>',                 'Server config'],
-          ['<code>package.json</code> + <code>node_modules/</code>', 'Runtime dependencies'],
-        ]
-      )}
-      ${table(
-        ['Exclude', 'Reason'],
-        [
-          ['<code>.claude/</code>',  'AI agent config — not needed at runtime'],
-          ['<code>.pulse/</code>',   'Local report data — not needed at runtime'],
-        ]
-      )}
-
-      ${section('env-vars', 'Environment variables')}
-      ${table(
-        ['Variable', 'Default', 'Description'],
-        [
-          ['<code>NODE_ENV</code>', '<code>development</code>', 'Set to <code>production</code> to enable HSTS headers and production cache behaviour.'],
-          ['<code>PORT</code>',     'Value in <code>pulse.config.js</code> (default <code>3000</code>)', 'Override the listening port. Most PaaS platforms set this automatically.'],
-        ]
-      )}
-      ${codeBlock(highlight(`NODE_ENV=production pulse start`, 'bash'))}
-
-      ${section('pm2', 'VPS with PM2')}
-      <p>PM2 keeps the process alive, restarts it on crash, and manages logs.</p>
-      ${codeBlock(highlight(`# Install PM2 globally
-npm install -g pm2
-
-# Start the app
-NODE_ENV=production pm2 start server.js --name myapp
-
-# Persist across reboots
-pm2 save
-pm2 startup
-
-# Zero-downtime reload after a deploy
-pm2 reload myapp`, 'bash'))}
-      <p>For repeatable deployments, check an <code>ecosystem.config.cjs</code> into version control:</p>
-      ${codeBlock(highlight(`// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name:   'myapp',
-    script: 'server.js',
-    env_production: {
-      NODE_ENV: 'production',
-      PORT:     3000,
-    },
-  }],
-}`, 'js'))}
-      ${codeBlock(highlight(`pm2 start ecosystem.config.cjs --env production`, 'bash'))}
-
-      ${section('docker', 'Docker')}
-      <p>A two-stage build keeps the image small — build tools stay in the first stage.</p>
-      ${codeBlock(highlight(`# ---- build stage ----
-FROM node:22-alpine AS build
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npx pulse build
-
-# ---- runtime stage ----
-FROM node:22-alpine
-WORKDIR /app
-ENV NODE_ENV=production
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY --from=build /app/src         ./src
-COPY --from=build /app/public      ./public
-COPY --from=build /app/server.js   ./server.js
-COPY pulse.config.js ./
-EXPOSE 3000
-CMD ["node", "server.js"]`, 'bash'))}
-      ${codeBlock(highlight(`docker build -t myapp .
-docker run -p 3000:3000 --env NODE_ENV=production myapp`, 'bash'))}
-
-      ${section('fly', 'Fly.io')}
-      ${codeBlock(highlight(`# fly.toml
-app            = 'myapp'
-primary_region = 'lhr'
-
-[env]
-  NODE_ENV = 'production'
-
-[build]
-  [build.args]
-    NODE_VERSION = '22'
-
-[deploy]
-  release_command = 'npx pulse build'
-
-[http_service]
-  internal_port       = 3000
-  force_https         = true
-  auto_stop_machines  = 'stop'
-  auto_start_machines = true
-
-[[vm]]
-  memory   = '256mb'
-  cpu_kind = 'shared'
-  cpus     = 1`, 'bash'))}
-      ${codeBlock(highlight(`# First deploy
-fly launch
-
-# Subsequent deploys
-fly deploy`, 'bash'))}
-
-      ${section('railway', 'Railway')}
-      <p>Railway auto-detects Node apps. Add a <code>railway.json</code> to set the build and start commands:</p>
-      ${codeBlock(highlight(`{
-  "$schema": "https://railway.app/railway.schema.json",
-  "build": {
-    "builder": "NIXPACKS",
-    "buildCommand": "npm run build"
-  },
-  "deploy": {
-    "startCommand": "NODE_ENV=production node server.js",
-    "healthcheckPath": "/",
-    "restartPolicyType": "ON_FAILURE"
-  }
-}`, 'js'))}
-
-      ${section('render', 'Render')}
-      ${table(
-        ['Setting', 'Value'],
-        [
-          ['Environment',   'Node'],
-          ['Build command', '<code>npm install &amp;&amp; npm run build</code>'],
-          ['Start command', '<code>NODE_ENV=production node server.js</code>'],
-          ['Node version',  '<code>22.x</code>'],
-        ]
-      )}
-      <p>Set <code>NODE_ENV=production</code> in the Render environment variables dashboard.</p>
-
-      ${section('serverless', 'Vercel, Cloudflare, and edge platforms')}
-      <p>These platforms each have multiple products with very different runtimes — the compatibility story varies significantly between them.</p>
-
-      ${section('vercel', 'Vercel')}
-      <p>Vercel has two distinct runtimes:</p>
-      ${table(
-        ['Product', 'Runtime', 'Pulse compatible?'],
-        [
-          ['<strong>Functions</strong> (Node.js)', 'Full Node.js — same built-ins as a VPS', 'Partially — see below'],
-          ['<strong>Edge Functions</strong>', 'V8 isolates (no Node built-ins)', 'No'],
-        ]
-      )}
-      <p><strong>Vercel Functions (Node.js)</strong> can run Pulse with some differences in behaviour:</p>
-      ${table(
-        ['Feature', 'Behaviour on Vercel Functions'],
-        [
-          ['<code>serverTtl</code> cache', 'Works within a warm instance, but cold starts reset it. Not reliable for expensive queries.'],
-          ['Streaming SSR', 'Vercel Functions support streaming responses, but require explicit configuration via <code>supportsResponseStreaming</code>.'],
-          ['Static files', 'Vercel serves <code>public/</code> automatically via its CDN — Pulse\'s static file serving is bypassed.'],
-          ['Security headers', 'Work as normal — Pulse adds them to every response.'],
-        ]
-      )}
-      ${callout('warning', 'Vercel Functions are not a tested or officially supported deployment target for Pulse. The adapter pattern (exporting a request handler rather than starting a server) is not yet documented. Railway, Render, or Fly.io are simpler choices with no adaptation required.')}
-
-      ${section('cloudflare', 'Cloudflare')}
-      ${table(
-        ['Product', 'Runtime', 'Pulse compatible?'],
-        [
-          ['<strong>Workers</strong>', 'V8 isolates — no <code>node:http</code>, <code>node:fs</code>, <code>node:zlib</code>', 'No'],
-          ['<strong>Pages Functions</strong>', 'Same V8 isolate runtime as Workers', 'No'],
-          ['<strong>CDN / proxy</strong>', 'Sits in front of your origin server', 'Yes — works great with Fly.io or a VPS behind it'],
-        ]
-      )}
-      ${callout('tip', 'The recommended pattern for edge performance: deploy Pulse to <strong>Fly.io</strong> (which runs real VMs in many regions) and put <strong>Cloudflare as a CDN/proxy</strong> in front of it. Static assets and cached HTML are served from Cloudflare\'s edge; dynamic requests are proxied to the nearest Fly VM.')}
-
-      ${section('https', 'HTTPS and reverse proxy')}
-      <p>Pulse detects TLS automatically. When a request arrives with an <code>x-forwarded-proto: https</code> header or over a direct TLS socket, <code>Strict-Transport-Security: max-age=31536000; includeSubDomains</code> is added to the response. All four platforms above forward this header — no Pulse config is needed.</p>
-      <p>If running behind nginx for TLS termination:</p>
-      ${codeBlock(highlight(`# nginx — TLS termination, proxy to Pulse
-server {
-  listen 443 ssl;
-  server_name myapp.com;
-
-  ssl_certificate     /etc/letsencrypt/live/myapp.com/fullchain.pem;
-  ssl_certificate_key /etc/letsencrypt/live/myapp.com/privkey.pem;
-
-  location / {
-    proxy_pass         http://localhost:3000;
-    proxy_http_version 1.1;
-    proxy_set_header   Host              $host;
-    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
-    proxy_set_header   X-Forwarded-Proto $scheme;
-  }
-}
-
-# Redirect HTTP to HTTPS
-server {
-  listen 80;
-  server_name myapp.com;
-  return 301 https://$host$request_uri;
-}`, 'bash'))}
-      ${callout('tip', 'Use <a href="https://certbot.eff.org">Certbot</a> to obtain and auto-renew a free Let\'s Encrypt certificate: <code>certbot --nginx -d myapp.com</code>.')}
-    `,
-  }),
-}

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

@@ -1,99 +0,0 @@
-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: {
-    theme:       'light',
-    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: ['/theme.css', '/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/extending.js

@@ -1,198 +0,0 @@
-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('/extending')
-
-export default {
-  route: '/extending',
-  meta: {
-    theme:       'light',
-    title: 'Extending Pulse — Pulse Docs',
-    description: 'Escape hatches for features outside the Pulse spec — onRequest middleware, raw server access, WebSockets, SSE, and custom error handling.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/extending',
-    prev,
-    next,
-    content: `
-      ${h1('Extending Pulse')}
-      ${lead('Pulse handles the standard request-response lifecycle through specs. For requirements outside that model — middleware, WebSockets, SSE, custom error pages — Pulse exposes deliberate integration points directly on the underlying Node.js server. There is no abstraction layer to fight through.')}
-
-      ${section('onrequest', 'Request interception with onRequest')}
-      <p><code>onRequest</code> is a hook on <code>createServer</code> that fires on every incoming request before Pulse handles it. Return <code>false</code> to short-circuit Pulse entirely and handle the response yourself.</p>
-      ${codeBlock(highlight(`// server.js
-import { createServer } from '@invisibleloop/pulse'
-import home from './src/pages/home.js'
-
-createServer([home], {
-  port: 3000,
-  onRequest(req, res) {
-    // Logging
-    console.log(req.method, req.url)
-
-    // Block a path entirely
-    if (req.url === '/internal') {
-      res.writeHead(403)
-      res.end('Forbidden')
-      return false  // stops Pulse processing this request
-    }
-
-    // Custom header on every response
-    res.setHeader('X-App-Version', '1.0.0')
-    // returning nothing (or undefined) lets Pulse continue normally
-  },
-})`, 'js'))}
-      ${callout('note', '<code>onRequest</code> runs before routing, guard, and all server fetchers. Returning <code>false</code> gives full control of the response — Pulse steps aside entirely for that request.')}
-      <p>Common uses:</p>
-      ${table(
-        ['Use case', 'Approach'],
-        [
-          ['Request logging',         'Log <code>req.method</code>, <code>req.url</code>, timing'],
-          ['IP allowlisting',         'Check <code>req.socket.remoteAddress</code>, return <code>false</code> with 403 if blocked'],
-          ['Rate limiting',           'Track request counts in a <code>Map</code>, return <code>false</code> with 429 when exceeded'],
-          ['Custom response headers', 'Call <code>res.setHeader()</code> before returning'],
-          ['Health check endpoint',   'Match <code>/healthz</code>, write <code>200 ok</code>, return <code>false</code>'],
-        ]
-      )}
-
-      ${section('raw-server', 'Accessing the raw server')}
-      <p><code>createServer</code> returns a <code>{ server }</code> object where <code>server</code> is a plain Node.js <code>http.Server</code>. You can attach any listener to it directly.</p>
-      ${codeBlock(highlight(`const { server } = createServer([home], { port: 3000 })
-
-// The server instance is available immediately after createServer() returns.
-// It starts listening automatically — no need to call server.listen().
-server.on('listening', () => {
-  console.log('ready')
-})`, 'js'))}
-
-      ${section('websockets', 'WebSockets')}
-      <p>Use the <code>upgrade</code> event on the server instance. The <code>ws</code> package handles the WebSocket handshake and framing.</p>
-      ${codeBlock(highlight(`npm install ws`, 'bash'))}
-      ${codeBlock(highlight(`// server.js
-import { WebSocketServer } from 'ws'
-import { createServer } from '@invisibleloop/pulse'
-import home from './src/pages/home.js'
-
-const { server } = createServer([home], { port: 3000 })
-
-const wss = new WebSocketServer({ noServer: true })
-
-server.on('upgrade', (req, socket, head) => {
-  if (req.url === '/ws') {
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      wss.emit('connection', ws, req)
-    })
-  } else {
-    socket.destroy()
-  }
-})
-
-wss.on('connection', (ws) => {
-  ws.send('connected')
-  ws.on('message', (msg) => ws.send(\`echo: \${msg}\`))
-})`, 'js'))}
-      <p>The Pulse-rendered page can connect to the WebSocket using an inline script. Pass <code>ctx.nonce</code> through a server fetcher so the script is allowed by the CSP:</p>
-      ${codeBlock(highlight(`server: {
-  meta: async (ctx) => ({ nonce: ctx.nonce }),
-},
-
-view: (_state, server) => \`
-  <main id="main-content">
-    <p id="status">Connecting…</p>
-    <script nonce="\${server.meta.nonce}">
-      const ws = new WebSocket('ws://' + location.host + '/ws')
-      ws.onmessage = (e) => {
-        document.getElementById('status').textContent = e.data
-      }
-    </script>
-  </main>
-\`,`, 'js'))}
-
-      ${section('sse', 'Server-Sent Events')}
-      <p>SSE keeps an HTTP connection open and streams events to the browser. Use <code>onRequest</code> to intercept the SSE path and write to the response directly.</p>
-      ${codeBlock(highlight(`onRequest(req, res) {
-  if (req.url !== '/events') return  // let Pulse handle everything else
-
-  res.writeHead(200, {
-    'Content-Type':  'text/event-stream',
-    'Cache-Control': 'no-cache',
-    'Connection':    'keep-alive',
-  })
-
-  // Send a keepalive comment every 15 seconds
-  const keepalive = setInterval(() => res.write(': keepalive\\n\\n'), 15000)
-
-  // Send an event
-  function send(event, data) {
-    res.write(\`event: \${event}\\ndata: \${JSON.stringify(data)}\\n\\n\`)
-  }
-
-  send('connected', { time: Date.now() })
-
-  req.on('close', () => clearInterval(keepalive))
-
-  return false
-},`, 'js'))}
-
-      ${section('error', 'Custom error handling')}
-      <p><code>onError</code> in <code>createServer</code> receives unhandled errors from server fetchers and guard functions. Use it to log errors to an external service or render a custom error page.</p>
-      ${codeBlock(highlight(`createServer([home], {
-  port: 3000,
-
-  onError(err, req, res) {
-    // Log to your error tracking service
-    console.error(err)
-
-    // Respond with a custom error page
-    res.writeHead(500, { 'Content-Type': 'text/html' })
-    res.end(\`
-      <!doctype html>
-      <html lang="en">
-        <head><title>Error</title></head>
-        <body>
-          <main id="main-content">
-            <h1>Something went wrong</h1>
-            <p>We've been notified and are looking into it.</p>
-          </main>
-        </body>
-      </html>
-    \`)
-  },
-})`, 'js'))}
-
-      ${section('client-js', 'Custom client-side JavaScript')}
-      <p>Pulse has no client-side JS of its own beyond the hydration runtime. For behaviour that genuinely needs to run in the browser — third-party widgets, analytics, canvas — use an inline script in the view with the request nonce. The nonce is unique per request and is required for the script to pass the CSP.</p>
-      ${codeBlock(highlight(`server: {
-  meta: async (ctx) => ({ nonce: ctx.nonce }),
-},
-
-view: (_state, server) => \`
-  <main id="main-content">
-    <canvas id="chart" width="600" height="300"></canvas>
-    <script nonce="\${server.meta.nonce}">
-      const ctx = document.getElementById('chart').getContext('2d')
-      // draw directly with Canvas API — no library needed for simple charts
-      ctx.fillStyle = '#9b8dff'
-      ctx.fillRect(10, 10, 100, 80)
-    </script>
-  </main>
-\`,`, 'js'))}
-      ${callout('note', 'External scripts loaded via <code>src</code> also need the nonce attribute, or their domain must be added to the <code>script-src</code> directive in the CSP. The nonce approach is simpler and does not require config changes.')}
-
-      ${section('when', 'Choosing the right approach')}
-      ${table(
-        ['What you need', 'Reach for'],
-        [
-          ['Middleware — logging, rate limiting, custom headers', '<code>onRequest</code>'],
-          ['Non-HTML responses — JSON APIs, webhooks, RSS, sitemaps', 'Raw response spec (<code>contentType</code> + <code>render</code>)'],
-          ['Real-time bidirectional communication', 'WebSockets via <code>server.on(\'upgrade\')</code>'],
-          ['Server-pushed updates (read-only stream)', 'SSE via <code>onRequest</code>'],
-          ['Custom error pages', '<code>onError</code>'],
-          ['Browser-only behaviour', 'Inline <code>&lt;script nonce&gt;</code> in the view'],
-        ]
-      )}
-    `,
-  }),
-}

package/docs/src/pages/faq.js

@@ -1,99 +0,0 @@
-import { renderLayout, h1, lead } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import pkg from '../../../package.json' with { type: 'json' }
-
-const { version } = pkg
-
-const { prev, next } = prevNext('/faq')
-
-function q(question, answer) {
-  return `
-    <div class="faq-item">
-      <h2 class="faq-q">${question}</h2>
-      <div class="faq-a">${answer}</div>
-    </div>`
-}
-
-export default {
-  route: '/faq',
-  meta: {
-    theme:       'light',
-    title:       'FAQ — Pulse Docs',
-    description: 'Frequently asked questions about the Pulse framework.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/faq',
-    prev,
-    next,
-    content: `
-      ${h1('FAQ')}
-      ${lead('Common questions about Pulse — what it is, what it isn\'t, and whether it\'s right for your project.')}
-
-      ${q(
-        'Is Pulse ready for production?',
-        `<p>The architecture is production-quality — streaming SSR, security headers, immutable caching, and zero runtime dependencies are built in and have been running reliably in real deployments. The framework itself targets Lighthouse 100 on every scaffolded page.</p>
-        <p>That said, Pulse is v${version} early access. The core spec format is stable, but some APIs may change before v1. It is best suited to new projects where you control the stack, and to teams who are comfortable building on something that is still evolving. If you need a framework with a five-year stability guarantee, wait for v1.</p>`
-      )}
-
-      ${q(
-        'Why plain JS objects instead of JSX or components?',
-        `<p>JSX and component trees are designed for incremental DOM updates — the virtual DOM needs a tree to diff. Pulse does not have a virtual DOM. Views are pure functions that return an HTML string; the framework re-renders the whole page segment on state change.</p>
-        <p>Plain JS objects are also unambiguous for AI agents. There is no syntax to learn, no component abstraction to navigate — just a JS object with well-defined keys. An agent can read, write, and validate a spec without understanding any framework-specific idioms.</p>`
-      )}
-
-      ${q(
-        'Why no virtual DOM?',
-        `<p>A virtual DOM solves the problem of efficient incremental updates to a large, complex component tree. Pulse pages are server-rendered HTML strings — the client runtime re-renders a bounded section of the page when state changes, which is fast enough for the kinds of interactions Pulse is designed for.</p>
-        <p>Eliminating the virtual DOM means eliminating the ~40–100 kB runtime that comes with it. Pulse ships ~4 kB brotli to the browser on first visit (shared runtime + page bundle). That is not a compression trick — there is genuinely no framework runtime on the client.</p>`
-      )}
-
-      ${q(
-        'Can I use npm packages in my specs?',
-        `<p>Yes, on the server side. Server fetchers run in Node.js and can import any npm package — database clients, API SDKs, utility libraries. These never reach the browser.</p>
-        <p>Client-side code (mutations and actions) runs in the browser and is bundled by esbuild. You can import pure JS utilities here, but avoid packages that depend on Node.js built-ins or that are large — the goal is to keep the client bundle small. UI components come from the built-in component library, which covers most cases without external dependencies.</p>`
-      )}
-
-      ${q(
-        'Does Pulse work with TypeScript?',
-        `<p>Type definitions are included for all public APIs — <code>createServer</code>, the spec shape, UI components, and the testing utilities. You can write specs in TypeScript and import the <code>Spec</code> type to get full autocompletion and type checking.</p>
-        <p>The examples and docs are in plain JS for readability, but TypeScript is a first-class option.</p>`
-      )}
-
-      ${q(
-        'Can I use a database directly in Pulse?',
-        `<p>Yes. Server fetchers are plain async functions — you can query a database, call an ORM, or use any server-side library directly. There is no data layer abstraction to work around.</p>
-        <pre class="code-block"><code>server: {
-  posts: async (ctx) => {
-    return db.posts.findMany({ where: { published: true } })
-  },
-}</code></pre>
-        <p>The result is passed to your view as <code>server.posts</code>. See the <a href="/server-data">Server Data</a> and <a href="/supabase">Supabase</a> docs for worked examples.</p>`
-      )}
-
-      ${q(
-        'How does Pulse compare to Next.js?',
-        `<p>Next.js is a full-featured React framework designed for large teams building complex applications. It ships React to the browser on every page, supports many rendering strategies, and has a large ecosystem.</p>
-        <p>Pulse is opinionated in the other direction: one spec format, one rendering model, no client framework, no configuration. It is smaller, simpler, and faster to get a Lighthouse 100 result — but it does not have the ecosystem breadth or the component model that React provides. If your project needs React, use Next.js. If you want to ship fast, simple, server-rendered pages with minimal JS, Pulse is worth trying.</p>`
-      )}
-
-      ${q(
-        'Can I build a multi-page app with client-side navigation?',
-        `<p>Yes. <code>initNavigation</code> intercepts same-origin link clicks, fetches the new page, swaps the DOM, and re-mounts the spec — all without a full page reload. From the user's perspective it feels like an SPA; from the server's perspective every navigation is a standard HTTP request.</p>
-        <p>See the <a href="/navigation">Navigation</a> docs for details.</p>`
-      )}
-
-      ${q(
-        'Does Pulse handle authentication?',
-        `<p>Pulse has a <code>guard</code> function that runs before any server fetcher executes. It receives the request context (cookies, headers, params) and can redirect or return an error if the user is not authenticated. This makes it impossible to accidentally skip an auth check — the guard runs before data is fetched.</p>
-        <p>For a complete auth integration, see the <a href="/auth">Auth0 guide</a>. The pattern works the same with any auth provider.</p>`
-      )}
-
-      ${q(
-        'What is the AI-native claim actually about?',
-        `<p>Two things. First, the spec format was designed to be easy for an AI agent to generate correctly — one JS object per page, a validated schema, no ambiguous patterns. An agent that writes a Pulse spec either produces a valid spec or gets a schema error it can fix. There is no grey area.</p>
-        <p>Second, the CLI starts an MCP server alongside the dev server, giving the agent tools to create pages, validate specs, screenshot routes, and run Lighthouse audits — without leaving the editor. The agent can build and verify a page end-to-end without human intervention on the tooling side.</p>`
-      )}
-    `,
-  }),
-}