@invisibleloop/pulse 0.1.21

package/docs/src/pages/accessibility.js

@@ -0,0 +1,157 @@
+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('/accessibility')
+
+export default {
+  route: '/accessibility',
+  meta: {
+    title: 'Accessibility — Pulse Docs',
+    description: 'Keyboard navigation, focus management, semantic HTML, and ARIA patterns in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/accessibility',
+    prev,
+    next,
+    content: `
+      ${h1('Accessibility')}
+      ${lead('Pulse enforces a 100 Lighthouse Accessibility score as the baseline. The foundations — skip link, focus styles, and focus management on navigation — are provided by the framework on every page. There is nothing to configure and nothing to forget.')}
+
+      ${section('built-in', 'What the framework provides')}
+      ${table(
+        ['Feature', 'How'],
+        [
+          ['Skip link', 'Injected on every page as the first focusable element. Targets <code>#main-content</code>. Visible only on focus.'],
+          ['Focus styles', '<code>:focus-visible</code> outline applied globally — purple, 3px, offset 2px. Suppressed for mouse users via <code>:focus:not(:focus-visible)</code>.'],
+          ['Navigation focus', 'After client-side navigation, focus moves to <code>#main-content</code>, <code>&lt;main&gt;</code>, or <code>&lt;h1&gt;</code> — whichever is found first. Screen reader users hear the new page heading without a full reload.'],
+        ]
+      )}
+      ${callout('note', 'The skip link targets <code>#main-content</code>. Pages use <code>&lt;main id="main-content"&gt;</code> as the content wrapper so the link resolves correctly.')}
+
+      ${section('structure', 'Page structure')}
+      <p>Each page view is wrapped in <code>&lt;main id="main-content"&gt;</code> with a single <code>&lt;h1&gt;</code> that describes the current page. Landmark elements communicate structure to assistive technology:</p>
+      ${codeBlock(highlight(`view: (state) => \`
+  <main id="main-content">
+    <h1>Page title</h1>
+    <!-- page content -->
+  </main>
+\``, 'js'))}
+      ${table(
+        ['Element', 'Purpose'],
+        [
+          ['<code>&lt;header&gt;</code>', 'Site header, logo, primary nav'],
+          ['<code>&lt;nav&gt;</code>', 'Navigation links — <code>aria-label</code> distinguishes multiple navs'],
+          ['<code>&lt;main id="main-content"&gt;</code>', 'Primary page content — one per page'],
+          ['<code>&lt;aside&gt;</code>', 'Supplementary content (sidebars, related links)'],
+          ['<code>&lt;footer&gt;</code>', 'Site footer'],
+        ]
+      )}
+
+      ${section('interactive', 'Interactive elements')}
+      <p>Actions are expressed as <code>&lt;button&gt;</code> elements, navigation as <code>&lt;a href&gt;</code> links. Both are keyboard-accessible by default. <code>&lt;div&gt;</code> and <code>&lt;span&gt;</code> elements with click handlers are not reachable by keyboard:</p>
+      ${codeBlock(highlight(`<!-- Keyboard accessible -->
+<button data-event="toggle">Open menu</button>
+<a href="/about">About</a>
+
+<!-- Not keyboard accessible — avoid -->
+<div data-event="toggle">Open menu</div>
+<span onclick="...">About</span>`, 'html'))}
+      <p>Buttons that toggle state carry <code>aria-expanded</code> or <code>aria-pressed</code> to communicate the current state to screen readers:</p>
+      ${codeBlock(highlight(`view: (state) => \`
+  <button data-event="toggleMenu" aria-expanded="\${state.menuOpen}">
+    Menu
+  </button>
+  \${state.menuOpen ? \`<nav>...</nav>\` : ''}
+\``, 'js'))}
+
+      ${section('focus', 'Focus management')}
+      <p>When a modal or dialog opens, focus moves inside it. When it closes, focus returns to the element that opened it. Since Pulse updates the DOM via morphing rather than a full replacement, the triggering element stays in the DOM and receives focus back naturally.</p>
+      <p>The <code>autofocus</code> attribute on the first interactive element inside newly revealed content moves focus there after the DOM update — no JavaScript required:</p>
+      ${codeBlock(highlight(`view: (state) => \`
+  <button data-event="openDialog">Delete item</button>
+
+  \${state.dialogOpen ? \`
+    <div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
+      <h2 id="dialog-title">Confirm deletion</h2>
+      <p>This cannot be undone.</p>
+      <button autofocus data-event="confirmDelete">Delete</button>
+      <button data-event="closeDialog">Cancel</button>
+    </div>
+  \` : ''}
+\``, 'js'))}
+
+      ${section('live-regions', 'Dynamic content announcements')}
+      <p>State changes that produce status messages — loading indicators, confirmations, validation errors — are wrapped in live regions so screen readers announce them without a page reload:</p>
+      ${table(
+        ['Role', 'Politeness', 'Used for'],
+        [
+          ['<code>role="status"</code>', 'Polite — waits for the user to finish', 'Loading states, success messages, counts'],
+          ['<code>role="alert"</code>', 'Assertive — interrupts immediately', 'Validation errors, destructive confirmations'],
+        ]
+      )}
+      ${codeBlock(highlight(`view: (state) => \`
+  <form data-action="submit">
+    <!-- fields -->
+    <button type="submit" \${state.status === 'loading' ? 'disabled' : ''}>
+      \${state.status === 'loading' ? 'Saving…' : 'Save'}
+    </button>
+  </form>
+
+  \${state.status === 'loading' ? \`
+    <p role="status">Saving…</p>
+  \` : ''}
+
+  \${state.errors.length ? \`
+    <div role="alert">
+      \${state.errors.map(e => \`<p>\${e.message}</p>\`).join('')}
+    </div>
+  \` : ''}
+\``, 'js'))}
+
+      ${section('forms', 'Forms')}
+      <p>Form controls are paired with <code>&lt;label&gt;</code> elements. Error messages are linked to their input via <code>aria-describedby</code> so screen readers announce them when the field receives focus:</p>
+      ${codeBlock(highlight(`<form data-action="submit">
+  <div class="field">
+    <label for="email">Email</label>
+    <input
+      id="email"
+      name="email"
+      type="email"
+      required
+      aria-describedby="\${state.emailError ? 'email-error' : ''}"
+    >
+    \${state.emailError
+      ? \`<p id="email-error" role="alert">\${state.emailError}</p>\`
+      : ''}
+  </div>
+
+  <fieldset>
+    <legend>Notification preferences</legend>
+    <label><input type="checkbox" name="email-notifs"> Email</label>
+    <label><input type="checkbox" name="sms-notifs"> SMS</label>
+  </fieldset>
+
+  <button type="submit">Submit</button>
+</form>`, 'html'))}
+
+      ${section('images', 'Images')}
+      <p>Decorative images carry <code>alt=""</code> so screen readers skip them. Informative images have descriptive alt text. Icon-only buttons are labelled with <code>aria-label</code>, with the icon marked <code>aria-hidden="true"</code>:</p>
+      ${codeBlock(highlight(`<!-- Informative image -->
+<img src="/team.jpg" alt="The Pulse team at the 2025 offsite" width="800" height="450">
+
+<!-- Decorative image -->
+<img src="/divider.svg" alt="" width="600" height="4">
+
+<!-- Icon-only button -->
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">...</svg>
+</button>`, 'html'))}
+
+      ${section('lighthouse', 'Lighthouse score')}
+      <p>Every page is expected to score 100 on Lighthouse Accessibility. Run <code>/pulse-report</code> after every new page or significant change. Regressions — contrast failures, missing labels, unreachable controls — are caught before they reach users.</p>
+    `,
+  }),
+}

package/docs/src/pages/actions.js

@@ -0,0 +1,191 @@
+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('/actions')
+
+export default {
+  route: '/actions',
+  meta: {
+    title: 'Actions — Pulse Docs',
+    description: 'Async operations in Pulse — lifecycle, FormData, error handling.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/actions',
+    prev,
+    next,
+    content: `
+      ${h1('Actions')}
+      ${lead('Actions handle async operations with an enforced lifecycle. The order of steps — capture inputs, validate, run, succeed or fail — is fixed. Skipping validation or running async work before showing a loading state is not possible within the action structure.')}
+
+      ${section('lifecycle', 'The action lifecycle')}
+      <p>When a form with <code>data-action</code> is submitted, Pulse runs the action through a fixed sequence of steps:</p>
+      ${codeBlock(highlight(`onStart(state, formData)
+  ↓  (optional) validate — checks spec.validation rules
+run(state, serverState, formData)
+  ↓  success           ↓  error
+onSuccess(state, payload)   onError(state, err)`, 'bash'))}
+      <p>Each step triggers a view re-render, so the UI always reflects the current state — loading, validated, succeeded, or failed. The sequence cannot be reordered.</p>
+
+      ${section('defining', 'Defining an action')}
+      ${codeBlock(highlight(`export default {
+  route: '/contact',
+  state: {
+    status: 'idle',   // 'idle' | 'loading' | 'success' | 'error'
+    errors: [],
+  },
+  validation: {
+    'fields.name':  { required: true, minLength: 2 },
+    'fields.email': { required: true, format: 'email' },
+    'fields.message': { required: true, minLength: 10 },
+  },
+  actions: {
+    submit: {
+      // 1. Immediately update state — show loading indicator
+      onStart: (state, formData) => ({
+        status: 'loading',
+        errors: [],
+        // Capture form values into state before validation runs
+        fields: {
+          name:    formData.get('name'),
+          email:   formData.get('email'),
+          message: formData.get('message'),
+        },
+      }),
+
+      // 2. Run spec.validation before proceeding to run()
+      validate: true,
+
+      // 3. Perform the async work
+      run: async (state, serverState, formData) => {
+        const res = await fetch('/api/contact', {
+          method:  'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body:    JSON.stringify(Object.fromEntries(formData)),
+        })
+        if (!res.ok) throw new Error('Request failed')
+        return res.json()
+      },
+
+      // 4a. Success
+      onSuccess: (state, payload) => ({
+        status: 'success',
+        errors: [],
+      }),
+
+      // 4b. Error — payload may have validation errors
+      onError: (state, err) => ({
+        status: 'error',
+        errors: err?.validation ?? [{ message: err.message }],
+      }),
+    },
+  },
+}`, 'js'))}
+
+      ${section('binding', 'Binding actions to forms')}
+      <p>A <code>data-action</code> attribute on a <code>&lt;form&gt;</code> element binds it to an action. When the form is submitted, Pulse creates a <code>FormData</code> object from the form's inputs and passes it through the action lifecycle:</p>
+      ${codeBlock(highlight(`<form data-action="submit">
+  <input name="name"    type="text"  placeholder="Your name">
+  <input name="email"   type="email" placeholder="Email">
+  <textarea name="message" placeholder="Message"></textarea>
+  <button type="submit">Send</button>
+</form>`, 'html'))}
+      ${callout('note', 'Pulse intercepts and prevents the default form submission. The action lifecycle is fully in control of what happens with the data — no manual <code>event.preventDefault()</code> needed.')}
+
+      ${section('on-start', 'onStart')}
+      <p><code>onStart(state, formData)</code> runs synchronously as soon as the form is submitted, before any async work begins. It sets a loading state, captures form values into state so validation can check them, and clears previous errors.</p>
+      ${callout('warning', '<code>onStart</code> runs <strong>before</strong> validation. <code>FormData</code> values are captured into state first, because the HTML re-renders (destroying the form inputs) once validation runs. All form values are captured here so validation can read them from state via dot-paths.')}
+
+      ${section('validate', 'validate')}
+      <p>Set <code>validate: true</code> to run the spec's <a href="/validation">validation rules</a> after <code>onStart</code>. If validation fails, <code>onError</code> is called immediately — <code>run</code> is never reached. Async work cannot execute against invalid input.</p>
+      ${codeBlock(highlight(`// Validation error structure
+{
+  message:    'Validation failed',
+  validation: [
+    { field: 'fields.email', rule: 'format', message: 'Must be a valid email' },
+    { field: 'fields.name',  rule: 'required', message: 'Required' },
+  ]
+}`, 'js'))}
+      <p>Access the errors in <code>onError</code>:</p>
+      ${codeBlock(highlight(`onError: (state, err) => ({
+  status: 'error',
+  errors: err?.validation ?? [{ message: err.message }],
+})`, 'js'))}
+
+      ${section('run', 'run')}
+      <p><code>run(state, serverState, formData)</code> is where the async work happens. Throw or reject to trigger <code>onError</code>. The return value is passed to <code>onSuccess</code> as <code>payload</code>.</p>
+      ${codeBlock(highlight(`run: async (state, serverState, formData) => {
+  const res = await fetch('/api/submit', {
+    method: 'POST',
+    body:   formData,
+  })
+  if (!res.ok) {
+    const err = await res.json()
+    throw Object.assign(new Error('Server error'), err)
+  }
+  return res.json()   // → onSuccess payload
+},`, 'js'))}
+
+      ${section('on-success', 'onSuccess')}
+      <p><code>onSuccess(state, payload)</code> receives the current state and whatever <code>run</code> returned. Return a partial state update:</p>
+      ${codeBlock(highlight(`onSuccess: (state, payload) => ({
+  status: 'success',
+  userId: payload.id,
+})`, 'js'))}
+
+      ${section('on-error', 'onError')}
+      <p><code>onError(state, err)</code> receives the current state and the thrown error. Return a partial state update to surface the error in the view:</p>
+      ${codeBlock(highlight(`onError: (state, err) => ({
+  status: 'error',
+  errors: err?.validation ?? [{ message: err.message }],
+})`, 'js'))}
+
+      ${section('toast', 'Toast notifications')}
+      <p>Return <code>_toast</code> from any action hook to show a notification. It is stripped from spec state automatically — it never appears in <code>getState()</code> or the view.</p>
+      ${codeBlock(highlight(`onSuccess: (state, payload) => ({
+  status:  'success',
+  _toast:  { message: 'Saved successfully', variant: 'success' },
+}),
+
+onError: (state, err) => ({
+  status:  'error',
+  errors:  err?.validation ?? [{ message: err.message }],
+  _toast:  { message: 'Something went wrong', variant: 'error' },
+}),`, 'js'))}
+      <p><code>_toast</code> works in <code>onStart</code>, <code>onSuccess</code>, and <code>onError</code>, and also in mutations. The toast container is injected into <code>document.body</code> once and survives client-side navigations.</p>
+      ${table(
+        ['Option', 'Type', 'Default', ''],
+        [
+          ['<code>message</code>', 'string', '—', 'Required. The notification text.'],
+          ['<code>variant</code>', '<code>success | error | warning | info</code>', '<code>info</code>', ''],
+          ['<code>duration</code>', 'number (ms)', '<code>4000</code>', 'Auto-dismiss delay. <code>0</code> = sticky until dismissed.'],
+        ]
+      )}
+
+      ${section('store-update', 'Pushing to the global store')}
+      <p>Return <code>_storeUpdate</code> from <code>onSuccess</code> to push a partial update into the <a href="/store">global store</a>. Every mounted page that subscribes to the updated keys re-renders immediately — no navigation, no polling.</p>
+      ${codeBlock(highlight(`onSuccess: (state, theme) => ({
+  saved:        true,
+  _storeUpdate: { settings: { theme } },   // ← merged into global store state
+}),`, 'js'))}
+      <p><code>_storeUpdate</code> is stripped from the page's own state — only the rest of the return object is merged into local state as usual. See <a href="/store">Global Store</a> for the full store API.</p>
+
+      ${section('rendering-errors', 'Rendering errors in the view')}
+      ${codeBlock(highlight(`view: (state) => \`
+  <form data-action="submit">
+    \${state.errors.map(e => \`
+      <p class="error">
+        \${e.field ? \`<strong>\${e.field}:</strong> \` : ''}\${e.message}
+      </p>
+    \`).join('')}
+    <!-- ... form fields ... -->
+    <button \${state.status === 'loading' ? 'disabled' : ''}>
+      \${state.status === 'loading' ? 'Sending…' : 'Send'}
+    </button>
+  </form>
+\``, 'js'))}
+    `,
+  }),
+}

package/docs/src/pages/auth.js

@@ -0,0 +1,177 @@
+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('/auth')
+
+export default {
+  route: '/auth',
+  meta: {
+    title: 'Auth (Auth0) — Pulse Docs',
+    description: 'Integrating Auth0 OAuth authentication with Pulse using guard functions, ctx.setCookie, and raw response specs.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/auth',
+    prev,
+    next,
+    content: `
+      ${h1('Auth (Auth0)')}
+      ${lead('Pulse integrates with Auth0 — and any OAuth 2.0 provider — using plain HTTP redirects and a token exchange. No client-side auth SDK is required. Protected routes enforce access through <code>guard</code>, which runs before any data fetcher can execute.')}
+
+      ${callout('info', 'No Auth0 SDK required. The OAuth flow is plain HTTP redirects and a token exchange fetch — no client-side library needed.')}
+
+      ${section('setup', 'Setup')}
+      <p>Register your application in Auth0 and note your credentials. Store them in environment variables — never hardcode them in specs.</p>
+      ${codeBlock(highlight(`# .env
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_CALLBACK_URL=http://localhost:3000/auth/callback`, 'bash'))}
+
+      ${section('login', 'Login route')}
+      <p>The login route is a raw response spec that redirects the browser to Auth0's authorization endpoint.</p>
+      ${codeBlock(highlight(`// src/pages/auth/login.js
+const {
+  AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CALLBACK_URL
+} = process.env
+
+export default {
+  route: '/auth/login',
+  contentType: 'text/html',
+
+  render: (ctx) => {
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id:     AUTH0_CLIENT_ID,
+      redirect_uri:  AUTH0_CALLBACK_URL,
+      scope:         'openid profile email',
+      state:         crypto.randomUUID(),
+    })
+    ctx.setHeader('Location', \`https://\${AUTH0_DOMAIN}/authorize?\${params}\`)
+    return { redirect: \`https://\${AUTH0_DOMAIN}/authorize?\${params}\` }
+  },
+}`, 'js'))}
+
+      ${section('callback', 'Callback route')}
+      <p>Auth0 redirects back to <code>/auth/callback</code> with a <code>code</code> query parameter. The server exchanges it for tokens, sets a session cookie, and redirects to the app.</p>
+      ${codeBlock(highlight(`// src/pages/auth/callback.js
+const {
+  AUTH0_DOMAIN, AUTH0_CLIENT_ID,
+  AUTH0_CLIENT_SECRET, AUTH0_CALLBACK_URL
+} = process.env
+
+export default {
+  route: '/auth/callback',
+  contentType: 'text/html',
+
+  server: {
+    session: async (ctx) => {
+      const { code } = ctx.query
+      if (!code) return null
+
+      // Exchange auth code for tokens
+      const res = await fetch(\`https://\${AUTH0_DOMAIN}/oauth/token\`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          grant_type:    'authorization_code',
+          client_id:     AUTH0_CLIENT_ID,
+          client_secret: AUTH0_CLIENT_SECRET,
+          redirect_uri:  AUTH0_CALLBACK_URL,
+          code,
+        }),
+      })
+
+      if (!res.ok) return null
+      const { access_token, id_token } = await res.json()
+
+      // Set a secure session cookie with the access token
+      ctx.setCookie('session', access_token, {
+        httpOnly: true,
+        secure:   process.env.NODE_ENV === 'production',
+        sameSite: 'Lax',
+        maxAge:   86400, // 24 hours
+      })
+
+      return access_token
+    },
+  },
+
+  render: (ctx, server) => {
+    if (!server.session) return { redirect: '/auth/login' }
+    return { redirect: '/' }
+  },
+}`, 'js'))}
+
+      ${section('logout', 'Logout route')}
+      <p>Clear the session cookie and redirect to Auth0's logout endpoint to invalidate the session there too.</p>
+      ${codeBlock(highlight(`// src/pages/auth/logout.js
+const { AUTH0_DOMAIN, AUTH0_CLIENT_ID } = process.env
+
+export default {
+  route: '/auth/logout',
+  contentType: 'text/html',
+
+  render: (ctx) => {
+    // Expire the session cookie
+    ctx.setCookie('session', '', { maxAge: 0 })
+
+    const returnTo = encodeURIComponent('http://localhost:3000')
+    return { redirect: \`https://\${AUTH0_DOMAIN}/v2/logout?client_id=\${AUTH0_CLIENT_ID}&returnTo=\${returnTo}\` }
+  },
+}`, 'js'))}
+
+      ${section('guard', 'Protecting routes')}
+      <p>Use <code>guard</code> to verify the session token before any server data is fetched. For production, verify the JWT signature locally rather than calling Auth0 on every request.</p>
+      ${codeBlock(highlight(`// src/pages/dashboard.js
+export default {
+  route: '/dashboard',
+
+  guard: async (ctx) => {
+    if (!ctx.cookies.session) return { redirect: '/auth/login' }
+
+    // Optional: verify JWT signature for production
+    // const user = await verifyJwt(ctx.cookies.session)
+    // if (!user) return { redirect: '/auth/login' }
+  },
+
+  server: {
+    profile: async (ctx) => fetchUserProfile(ctx.cookies.session),
+  },
+
+  state: {},
+  view: (state, server) => \`
+    <main id="main-content">
+      <h1>Welcome, \${server.profile.name}</h1>
+    </main>
+  \`,
+}`, 'js'))}
+
+      ${callout('info', 'Guard runs before server data fetchers — if the session is invalid the profile fetch never happens.')}
+
+      ${section('ctx-reference', 'ctx reference')}
+      ${table(
+        ['Method', 'Description'],
+        [
+          ['<code>ctx.cookies.session</code>', 'Read the session cookie set during OAuth callback'],
+          ['<code>ctx.setCookie(name, value, opts)</code>', 'Set a response cookie — used in callback and logout routes'],
+          ['<code>ctx.setHeader(name, value)</code>', 'Set an arbitrary response header'],
+        ]
+      )}
+
+      ${table(
+        ['setCookie option', 'Type', 'Description'],
+        [
+          ['<code>httpOnly</code>', 'boolean', 'Prevents JS access — always use for session cookies'],
+          ['<code>secure</code>',   'boolean', 'HTTPS only — set <code>true</code> in production'],
+          ['<code>sameSite</code>', '<code>"Lax" | "Strict" | "None"</code>', '<code>Lax</code> works for most OAuth flows'],
+          ['<code>maxAge</code>',  'number',  'Lifetime in seconds — omit for session cookie'],
+          ['<code>path</code>',    'string',  'Defaults to <code>/</code>'],
+          ['<code>domain</code>',  'string',  'Scope to a domain — omit for current host'],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/caching.js

@@ -0,0 +1,95 @@
+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('/caching')
+
+export default {
+  route: '/caching',
+  meta: {
+    title: 'Caching — Pulse Docs',
+    description: 'HTTP cache headers, in-process server data caching, and asset caching in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/caching',
+    prev,
+    next,
+    content: `
+      ${h1('Caching')}
+      ${lead('Pulse handles asset caching automatically — production bundles are content-hashed and served with immutable cache headers. Page caching is controlled declaratively in the spec: <code>serverTtl</code> for in-process data, <code>cache</code> for HTTP headers. Nothing is cached by default unless you declare it.')}
+
+      ${section('server-ttl', 'serverTtl — in-process data cache')}
+      <p><code>serverTtl</code> is a number of seconds to cache the result of <code>server.data()</code> in memory. Subsequent requests within the TTL window skip the async data fetch entirely and serve the cached result.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/homepage',
+  serverTtl: 60,   // cache server data for 60 seconds
+  server: {
+    data: async () => ({
+      featured: await db.products.getFeatured(),
+      stats:    await analytics.getGlobalStats(),
+    }),
+  },
+}`, 'js'))}
+      ${table(
+        ['Value', 'Behaviour'],
+        [
+          ['<code>undefined</code> (default)', 'No caching — <code>server.data()</code> runs on every request'],
+          ['<code>0</code>', 'No caching (same as undefined)'],
+          ['<code>60</code>', 'Cache for 60 seconds — at most one database hit per minute'],
+          ['<code>3600</code>', 'Cache for 1 hour'],
+        ]
+      )}
+      ${callout('note', 'The in-process cache is per-process and per-route. It is not shared across multiple server instances. Use a distributed cache (Redis, etc.) for cross-instance consistency.')}
+      ${callout('warning', 'In development, setting a long <code>serverTtl</code> can mask stale data. Set it to <code>0</code> or omit it during development, and add it when deploying to production.')}
+
+      ${section('http-cache', 'cache — HTTP response headers')}
+      <p>The <code>cache</code> field controls the <code>Cache-Control</code> header sent with the page HTML response. This tells browsers and CDNs how to cache the response.</p>
+      ${codeBlock(highlight(`export default {
+  route: '/blog/:slug',
+  cache: {
+    public:               true,    // allow CDN/proxy caching
+    maxAge:               300,     // cache for 5 minutes
+    staleWhileRevalidate: 86400,   // serve stale for up to 24 hours while revalidating
+  },
+  // ...
+}`, 'js'))}
+
+      ${section('cache-fields', 'Cache field reference')}
+      ${table(
+        ['Field', 'Type', 'Description'],
+        [
+          ['<code>public</code>', '<code>boolean</code>', 'If true, emits <code>public</code> — allows CDN/proxy caching. Default: <code>private</code>.'],
+          ['<code>maxAge</code>', '<code>number</code>', 'Seconds before the response is considered stale. Emits <code>max-age=N</code>.'],
+          ['<code>staleWhileRevalidate</code>', '<code>number</code>', 'Seconds to serve stale content while revalidating in the background. Emits <code>stale-while-revalidate=N</code>.'],
+        ]
+      )}
+      ${codeBlock(highlight(`// private page — user-specific content
+cache: { public: false, maxAge: 0 }
+// → Cache-Control: private, no-store
+
+// public marketing page — cached at CDN
+cache: { public: true, maxAge: 3600, staleWhileRevalidate: 86400 }
+// → Cache-Control: public, max-age=3600, stale-while-revalidate=86400`, 'js'))}
+
+      ${section('html-default', 'Default HTML caching')}
+      <p>By default, Pulse sends <code>Cache-Control: no-store</code> for all HTML responses. Users always see fresh content — stale HTML is never served from browser or proxy caches unless you explicitly declare a <code>cache</code> policy in the spec.</p>
+
+      ${section('asset-caching', 'Asset caching')}
+      <p>Static assets in <code>public/</code> receive <code>Cache-Control: max-age=3600</code> (one hour).</p>
+      <p>Production bundles in <code>public/dist/</code> receive <code>Cache-Control: public, max-age=31536000, immutable</code> (one year, immutable). This is guaranteed safe because bundle filenames include a content hash — code changes produce a new hash, and browsers fetch the updated file automatically. There is nothing to configure.</p>
+
+      ${section('dev-vs-prod', 'Development vs production')}
+      ${table(
+        ['Resource', 'Development', 'Production'],
+        [
+          ['HTML pages', '<code>no-store</code>', '<code>no-store</code> (or your <code>cache</code> config)'],
+          ['Static assets (<code>/public/*</code>)', '<code>max-age=3600</code>', '<code>max-age=3600</code>'],
+          ['JS bundles (<code>/dist/*</code>)', 'N/A (source files served directly)', '<code>immutable, max-age=31536000</code>'],
+        ]
+      )}
+      ${callout('tip', 'For maximum performance, combine <code>serverTtl</code> for expensive database queries with a short <code>cache.maxAge</code> and a generous <code>cache.staleWhileRevalidate</code>. Users get fast responses; data stays reasonably fresh.')}
+    `,
+  }),
+}