@invisibleloop/pulse 0.20.10 → 0.20.19

package/docs/src/lib/stats.js

@@ -1,81 +0,0 @@
-/**
- * Performance metrics — computed once at server start from real build output.
- * Bundle sizes are measured by compressing the actual dist files with brotli.
- */
-
-import fs   from 'fs'
-import path  from 'path'
-import zlib  from 'zlib'
-import { fileURLToPath } from 'url'
-
-const ROOT = path.resolve(fileURLToPath(import.meta.url), '../../../../..')
-const DIST = path.join(ROOT, 'benchmark', 'public', 'dist')
-
-function brotliKb(filepath) {
-  try {
-    const buf = fs.readFileSync(filepath)
-    return zlib.brotliCompressSync(buf).length / 1024
-  } catch {
-    return null
-  }
-}
-
-function measureBundles() {
-  if (!fs.existsSync(DIST)) return null
-  const files = fs.readdirSync(DIST).filter(f => f.endsWith('.js'))
-
-  // Main runtime = largest runtime-*.js file
-  const runtimes = files
-    .filter(f => f.startsWith('runtime-'))
-    .map(f => ({ f, kb: brotliKb(path.join(DIST, f)) }))
-    .filter(x => x.kb !== null)
-    .sort((a, b) => b.kb - a.kb)
-
-  const counterBoot = files.find(f => f.startsWith('counter.boot-'))
-  const staticBoot  = files.find(f => f.startsWith('home.boot-'))
-
-  const runtimeKb    = runtimes[0]?.kb ?? null
-  const pageBootKb   = counterBoot ? brotliKb(path.join(DIST, counterBoot)) : null
-  const staticBootKb = staticBoot  ? brotliKb(path.join(DIST, staticBoot))  : null
-
-  return { runtimeKb, pageBootKb, staticBootKb }
-}
-
-const bundles = measureBundles()
-
-function fmt(kb, fallback) {
-  return (kb != null) ? kb.toFixed(kb < 1 ? 2 : 1) : fallback
-}
-
-const runtimeKb  = fmt(bundles?.runtimeKb,  '3.8')
-const firstVisit = bundles?.runtimeKb && bundles?.pageBootKb
-  ? (bundles.runtimeKb + bundles.pageBootKb).toFixed(1)
-  : '4.2'
-const pageNavKb  = fmt(bundles?.pageBootKb,  '0.4')
-
-export const metrics = {
-  generatedAt: new Date().toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' }),
-
-  lighthouse: [
-    { value: '100', label: 'Accessibility' },
-    { value: '100', label: 'Best Practices' },
-    { value: '100',  label: 'SEO' },
-  ],
-
-  bundles: [
-    { value: '0 kB',              label: 'Static page — no JS shipped' },
-    { value: `${firstVisit} kB`,  label: 'Single page app — runtime + page (brotli)' },
-    { value: `${runtimeKb} kB`,   label: 'Multi-page — shared runtime, cached (brotli)' },
-    { value: `${pageNavKb} kB`,   label: 'Multi-page — per-page JS bundle (brotli)' },
-  ],
-
-  vitals: [
-    { id: 'cls', value: '0.00', label: 'Cumulative Layout Shift' },
-  ],
-
-  architecture: [
-    { value: '0', label: 'Runtime dependencies' },
-    { value: 'None', label: 'Production build step' },
-    { value: 'Brotli', label: 'Automatic compression' },
-  ],
-}

package/docs/src/pages/accessibility.js

@@ -1,157 +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('/accessibility')
-
-export default {
-  route: '/accessibility',
-  meta: {
-    theme:       'light',
-    title: 'Accessibility — Pulse Docs',
-    description: 'Keyboard navigation, focus management, semantic HTML, and ARIA patterns in Pulse.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  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

@@ -1,194 +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('/actions')
-
-export default {
-  route: '/actions',
-  meta: {
-    theme:       'light',
-    title: 'Actions — Pulse Docs',
-    description: 'Async operations in Pulse — lifecycle, FormData, error handling.',
-    styles: ['/theme.css', '/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.')}
-
-      ${callout('tip', 'Actions run client-side and need hydration. For forms that must also work with JavaScript disabled, pair the action with a server-side <a href="/forms"><code>submit</code> handler</a> — the same form serves both paths.')}
-
-      ${section('lifecycle', 'The action lifecycle')}
-      <p>When a form with <code>data-action</code> is submitted, Pulse runs the action through a fixed sequence of steps:</p>
-      ${codeBlock(highlight(`onStart(state, formData)
-  ↓  (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', 'Description'],
-        [
-          ['<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

@@ -1,176 +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('/auth')
-
-export default {
-  route: '/auth',
-  meta: {
-    theme:       'light',
-    title: 'Auth (Auth0) — Pulse Docs',
-    description: 'Integrating Auth0 OAuth authentication with Pulse using guard functions, ctx.setCookie, and raw response specs.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  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),
-  },
-
-  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'],
-        ]
-      )}
-    `,
-  }),
-}