@invisibleloop/pulse 0.1.21

package/docs/src/pages/hydration.js

@@ -0,0 +1,98 @@
+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('/hydration')
+
+export default {
+  route: '/hydration',
+  meta: {
+    title: 'Hydration — Pulse Docs',
+    description: 'How Pulse hydrates server-rendered HTML on the client — the hydrate field, mount(), and production bundles.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/hydration',
+    prev,
+    next,
+    content: `
+      ${h1('Hydration')}
+      ${lead('Hydration in Pulse is opt-in and minimal. Omit <code>hydrate</code> and zero JavaScript is sent to the browser. Add it and Pulse binds events to the server-rendered HTML without re-rendering it — the SSR-painted content is preserved exactly as the server sent it.')}
+
+      ${section('enabling', 'Enabling hydration')}
+      <p>Set the <code>hydrate</code> field to a browser-importable path to your spec file. Pulse uses this to generate the bootstrap script that mounts the client runtime:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/counter',
+  hydrate: '/src/pages/counter.js',   // browser path to this file
+  state: { count: 0 },
+  mutations: {
+    increment: (state) => ({ count: state.count + 1 }),
+    decrement: (state) => ({ count: state.count - 1 }),
+  },
+  view: (state) => \`
+    <div>
+      <button data-event="decrement">-</button>
+      <span>\${state.count}</span>
+      <button data-event="increment">+</button>
+    </div>
+  \`,
+}`, 'js'))}
+
+      ${section('dev-bootstrap', 'Development bootstrap')}
+      <p>In development (when <code>hydrate</code> is a source file path, not a <code>/dist/</code> bundle), Pulse emits an inline bootstrap script:</p>
+      ${codeBlock(highlight(`<script type="module">
+  import spec from '/src/pages/counter.js'
+  import { mount } from '/src/runtime/index.js'
+  import { initNavigation } from '/src/runtime/navigate.js'
+  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+  initNavigation(root, mount)
+</script>`, 'html'))}
+      <p>This imports the spec and runtime source files directly — no build step required for development.</p>
+
+      ${section('production', 'Production bundles')}
+      <p>Run <code>npm run build</code> to generate production bundles. This creates content-hashed files in <code>public/dist/</code> and a <code>manifest.json</code> mapping spec hydrate paths to bundle paths.</p>
+      ${codeBlock(highlight(`# Generated by npm run build
+public/dist/
+  runtime-abc123.js          # shared runtime (~2.1 kB brotli)
+  counter.boot-def456.js     # per-page spec bundle (~0.5 kB brotli)
+  manifest.json              # { '/src/pages/counter.js': '/dist/counter.boot-def456.js' }`, 'bash'))}
+      <p>When Pulse detects a manifest (via <code>staticDir</code> auto-detection or explicit <code>manifest</code> option), it resolves the <code>hydrate</code> path to the bundle path and emits a single <code>&lt;script src&gt;</code> tag instead of the inline bootstrap:</p>
+      ${codeBlock(highlight(`<script type="module" src="/dist/counter.boot-def456.js"></script>`, 'html'))}
+
+      ${section('ssr-true', 'The { ssr: true } option')}
+      <p>The bootstrap script calls <code>mount(spec, root, serverState, { ssr: true })</code>. This tells the runtime to skip the initial re-render and bind event listeners to the existing DOM only.</p>
+      <p>This is what keeps LCP fast. The server-painted HTML is the LCP element. The JavaScript binds events without touching the DOM — no flash, no layout shift, no JS-rendered replacement.</p>
+      ${callout('warning', 'Never set <code>{ ssr: false }</code> on a server-rendered page. It re-renders the entire DOM on mount, replacing the server-painted HTML — causing a visible flash and pushing LCP to 400–600ms.')}
+
+      ${section('mount', 'mount()')}
+      <p>The <code>mount</code> function attaches the Pulse runtime to a DOM element:</p>
+      ${codeBlock(highlight(`import { mount } from '@invisibleloop/pulse/runtime'
+
+mount(
+  spec,          // the page spec
+  rootEl,        // the DOM element to mount into
+  serverState,   // window.__PULSE_SERVER__ (server data from SSR)
+  { ssr: true }  // skip re-render on first mount
+)`, 'js'))}
+      <p>After mount, all <code>data-event</code> and <code>data-action</code> attributes in the DOM are wired to the spec's mutations and actions. State updates trigger a full view re-render via <code>innerHTML</code> replacement.</p>
+
+      ${section('no-hydrate', 'Pages without hydration')}
+      <p>Omit <code>hydrate</code> and Pulse sends zero JavaScript to the browser — no runtime overhead, no hydration cost. This is the correct default for:</p>
+      <ul>
+        <li>Documentation pages</li>
+        <li>Marketing/landing pages</li>
+        <li>Blog posts and articles</li>
+        <li>Any page with no client-side interactivity</li>
+      </ul>
+      ${callout('tip', 'Start without <code>hydrate</code> and only add it when actual client interactivity is needed. Many pages that appear to need JavaScript can be handled server-side with <a href="/routing">routing</a> and <a href="/server-data">server data</a>.')}
+
+      ${section('server-state', 'Passing server state to the client')}
+      <p>Server data fetched via <code>server.data()</code> is serialised into the page HTML as <code>window.__PULSE_SERVER__</code>. The client runtime reads this on mount, making server data available to the view during client re-renders without an additional network request.</p>
+      ${codeBlock(highlight(`// Emitted in the page HTML
+<script id="__PULSE_SERVER__" type="application/json">
+  {"product":{"id":1,"name":"Widget","price":9.99}}
+</script>`, 'html'))}
+    `,
+  }),
+}

package/docs/src/pages/images.js

@@ -0,0 +1,121 @@
+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('/images')
+
+export default {
+  route: '/images',
+  meta: {
+    title: 'Images — Pulse Docs',
+    description: 'The img() and picture() helpers for optimised, CLS-free image markup.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/images',
+    prev,
+    next,
+    content: `
+      ${h1('Images')}
+      ${lead('The <code>img()</code> and <code>picture()</code> helpers generate image markup that prevents CLS by requiring dimensions and handles loading priority correctly. Pulse targets 0.00 CLS — these helpers enforce the attributes that make that possible.')}
+
+      ${section('import', 'Importing')}
+      ${codeBlock(highlight(`// In your page spec or component
+import { img, picture } from '@invisibleloop/pulse/image'`, 'js'))}
+
+      ${section('img', 'img(options)')}
+      <p>Generates an optimised <code>&lt;img&gt;</code> element:</p>
+      ${codeBlock(highlight(`img({
+  src:      '/images/hero.jpg',
+  alt:      'A hero image showing our product',
+  width:    1200,
+  height:   630,
+  priority: true,    // → eager loading + high fetchpriority
+})`, 'js'))}
+      <p>Output:</p>
+      ${codeBlock(highlight(`<img src="/images/hero.jpg" alt="A hero image showing our product" width="1200" height="630" loading="eager" decoding="async" fetchpriority="high">`, 'html'))}
+
+      ${section('img-options', 'img() options')}
+      ${table(
+        ['Option', 'Type', 'Required', 'Description'],
+        [
+          ['<code>src</code>', '<code>string</code>', 'Yes', 'Image URL.'],
+          ['<code>alt</code>', '<code>string</code>', 'Yes', 'Alt text. Required for accessibility. Use an empty string for decorative images.'],
+          ['<code>width</code>', '<code>number</code>', 'Recommended', 'Intrinsic width in pixels. Prevents CLS by reserving layout space.'],
+          ['<code>height</code>', '<code>number</code>', 'Recommended', 'Intrinsic height in pixels. Prevents CLS.'],
+          ['<code>priority</code>', '<code>boolean</code>', 'No', 'If true: <code>loading="eager"</code> + <code>fetchpriority="high"</code>. Use for LCP images. Default: <code>false</code>.'],
+          ['<code>class</code>', '<code>string</code>', 'No', 'CSS class applied to the <code>&lt;img&gt;</code> element.'],
+        ]
+      )}
+
+      ${callout('warning', '<code>width</code> and <code>height</code> are required to prevent Cumulative Layout Shift. Without them the browser cannot reserve layout space before the image loads. Pulse targets 0.00 CLS — omitting these attributes breaks that guarantee.')}
+
+      ${section('picture', 'picture(options)')}
+      <p>Generates a <code>&lt;picture&gt;</code> element with modern format sources and a fallback <code>&lt;img&gt;</code>. Use this to serve AVIF or WebP to browsers that support them, with JPEG/PNG as the fallback:</p>
+      ${codeBlock(highlight(`picture({
+  src:      '/images/hero.jpg',      // fallback
+  alt:      'Hero image',
+  width:    1200,
+  height:   630,
+  priority: true,
+  sources: [
+    { src: '/images/hero.avif', type: 'image/avif' },
+    { src: '/images/hero.webp', type: 'image/webp' },
+  ],
+})`, 'js'))}
+      <p>Output:</p>
+      ${codeBlock(highlight(`<picture>
+  <source srcset="/images/hero.avif" type="image/avif">
+  <source srcset="/images/hero.webp" type="image/webp">
+  <img src="/images/hero.jpg" alt="Hero image" width="1200" height="630" loading="eager" decoding="async" fetchpriority="high">
+</picture>`, 'html'))}
+
+      ${section('picture-options', 'picture() options')}
+      ${table(
+        ['Option', 'Type', 'Description'],
+        [
+          ['<code>src</code>', '<code>string</code>', 'Fallback image URL (JPEG/PNG for universal compatibility).'],
+          ['<code>alt</code>', '<code>string</code>', 'Alt text — shared by the inner <code>&lt;img&gt;</code>.'],
+          ['<code>width</code>', '<code>number</code>', 'Intrinsic width — applied to inner <code>&lt;img&gt;</code>.'],
+          ['<code>height</code>', '<code>number</code>', 'Intrinsic height — applied to inner <code>&lt;img&gt;</code>.'],
+          ['<code>priority</code>', '<code>boolean</code>', 'If true: eager loading + high priority.'],
+          ['<code>class</code>', '<code>string</code>', 'CSS class on the inner <code>&lt;img&gt;</code>.'],
+          ['<code>sources</code>', '<code>{src, type}[]</code>', 'Modern format sources in preference order (AVIF first, WebP second).'],
+        ]
+      )}
+
+      ${section('priority', 'When to use priority')}
+      <p>Set <code>priority: true</code> on the <strong>Largest Contentful Paint (LCP) element</strong> — typically the hero image above the fold. This tells the browser to load it with high priority, improving LCP.</p>
+      <p>Every other image should omit <code>priority</code> (defaults to lazy loading with <code>loading="lazy"</code>). Lazy images are not fetched until they approach the viewport — reducing initial page weight and speeding up load time.</p>
+      ${callout('tip', 'Only one image per page should have <code>priority: true</code>. Using it on multiple images defeats the purpose — every image becomes "high priority" which is the same as no image being prioritised.')}
+
+      ${section('in-view', 'Using in a view')}
+      ${codeBlock(highlight(`import { img, picture } from '@invisibleloop/pulse/image'
+
+export default {
+  route: '/blog/:slug',
+  state: {},
+  server: {
+    data: async (ctx) => ({ post: await db.posts.findBySlug(ctx.params.slug) }),
+  },
+  view: (state, server) => \`
+    <article>
+      \${picture({
+        src:      server.post.heroImage,
+        alt:      server.post.heroAlt,
+        width:    1200,
+        height:   630,
+        priority: true,
+        sources:  [
+          { src: server.post.heroImage.replace('.jpg', '.avif'), type: 'image/avif' },
+          { src: server.post.heroImage.replace('.jpg', '.webp'), type: 'image/webp' },
+        ],
+      })}
+      <h1>\${server.post.title}</h1>
+    </article>
+  \`,
+}`, 'js'))}
+    `,
+  }),
+}

package/docs/src/pages/meta.js

@@ -0,0 +1,120 @@
+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('/meta')
+
+export default {
+  route: '/meta',
+  meta: {
+    title: 'Metadata & SEO — Pulse Docs',
+    description: 'How to configure page metadata, Open Graph tags, and structured data in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/meta',
+    prev,
+    next,
+    content: `
+      ${h1('Metadata & SEO')}
+      ${lead('The <code>meta</code> field declares everything that appears in the <code>&lt;head&gt;</code> — title, description, stylesheets, Open Graph tags, and structured data. All metadata is rendered server-side, so crawlers and social media scrapers see the final HTML without executing JavaScript.')}
+
+      ${section('basics', 'Basic metadata')}
+      ${codeBlock(highlight(`export default {
+  route: '/about',
+  meta: {
+    title:       'About Us — Acme Corp',
+    description: 'Learn about the team behind Acme Corp.',
+    styles:      ['/app.css'],
+  },
+  state: {},
+  view: () => \`<h1>About Us</h1>\`,
+}`, 'js'))}
+      <p>This generates:</p>
+      ${codeBlock(highlight(`<title>About Us — Acme Corp</title>
+<meta name="description" content="Learn about the team behind Acme Corp.">
+<link rel="stylesheet" href="/app.css">`, 'html'))}
+
+      ${section('all-fields', 'All meta fields')}
+      ${table(
+        ['Field', 'Type', 'Description'],
+        [
+          ['<code>title</code>', '<code>string</code>', 'Page title — appears in the browser tab and search results.'],
+          ['<code>description</code>', '<code>string</code>', 'Meta description — appears in search engine snippets. Keep under 160 characters.'],
+          ['<code>styles</code>', '<code>string[]</code>', 'Array of stylesheet URLs — each emits a <code>&lt;link rel="stylesheet"&gt;</code> tag.'],
+          ['<code>ogTitle</code>', '<code>string</code>', 'Open Graph title. If omitted, falls back to <code>title</code>.'],
+          ['<code>ogImage</code>', '<code>string</code>', 'Open Graph image URL — shown when the page is shared on social media.'],
+          ['<code>schema</code>', '<code>object</code>', 'JSON-LD structured data object — emitted as a <code>&lt;script type="application/ld+json"&gt;</code> tag.'],
+        ]
+      )}
+
+      ${section('open-graph', 'Open Graph')}
+      <p>Open Graph tags control how the page appears when shared on social media (Twitter/X, Facebook, LinkedIn, Slack, etc.):</p>
+      ${codeBlock(highlight(`meta: {
+  title:       'My Product — Acme Corp',
+  description: 'The best product ever made.',
+  ogTitle:     'My Product',                         // shorter for social
+  ogImage:     'https://acme.com/og/my-product.jpg', // 1200×630 recommended
+}`, 'js'))}
+      <p>Generated tags:</p>
+      ${codeBlock(highlight(`<meta property="og:title" content="My Product">
+<meta property="og:description" content="The best product ever made.">
+<meta property="og:image" content="https://acme.com/og/my-product.jpg">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="My Product">
+<meta name="twitter:image" content="https://acme.com/og/my-product.jpg">`, 'html'))}
+      ${callout('tip', 'Use an absolute URL for <code>ogImage</code> — social media crawlers need the full URL to fetch the image. Recommended size: 1200×630 pixels.')}
+
+      ${section('structured-data', 'Structured data (ld+json)')}
+      <p>The <code>schema</code> field accepts a plain object conforming to <a href="https://schema.org" target="_blank" rel="noopener">schema.org</a> vocabulary. Pulse serialises it as a <code>&lt;script type="application/ld+json"&gt;</code> tag in the head:</p>
+      ${codeBlock(highlight(`meta: {
+  title: 'How to make sourdough — My Blog',
+  schema: {
+    '@context': 'https://schema.org',
+    '@type':    'Article',
+    headline:   'How to make sourdough',
+    author: {
+      '@type': 'Person',
+      name:    'Jane Smith',
+    },
+    datePublished: '2025-01-15',
+    image:         'https://myblog.com/sourdough.jpg',
+  },
+}`, 'js'))}
+      <p>Common schema types:</p>
+      ${table(
+        ['@type', 'Use for'],
+        [
+          ['<code>WebSite</code>', 'The homepage or site root'],
+          ['<code>WebPage</code>', 'General pages'],
+          ['<code>Article</code>', 'Blog posts, news articles'],
+          ['<code>Product</code>', 'E-commerce product pages'],
+          ['<code>FAQPage</code>', 'FAQ pages (enables rich results in Google)'],
+          ['<code>BreadcrumbList</code>', 'Breadcrumb navigation'],
+          ['<code>Organization</code>', 'Company/brand information'],
+        ]
+      )}
+
+      ${section('styles', 'Stylesheets')}
+      <p>The <code>styles</code> array accepts any number of stylesheet URLs. They are emitted as <code>&lt;link rel="stylesheet"&gt;</code> tags in the <code>&lt;head&gt;</code> in the order declared:</p>
+      ${codeBlock(highlight(`meta: {
+  styles: [
+    '/app.css',
+    '/fonts.css',
+    'https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap',
+  ],
+}`, 'js'))}
+      ${callout('note', 'For maximum performance, host your own fonts rather than using Google Fonts. External stylesheet requests add render-blocking latency and a DNS lookup.')}
+
+      ${section('seo-tips', 'SEO tips')}
+      <ul>
+        <li>Write a unique <code>title</code> and <code>description</code> for every page — duplicate metadata prevents pages from competing in search results.</li>
+        <li>Keep descriptions under 160 characters — longer values are truncated.</li>
+        <li>Use structured data to qualify for Google rich results.</li>
+        <li>All metadata is in the server-rendered HTML — search engines and social scrapers do not need to execute JavaScript to read it.</li>
+        <li>Pulse targets 100/100 Lighthouse SEO out of the box. Run <code>/pulse-report</code> after new pages to confirm.</li>
+      </ul>
+    `,
+  }),
+}

package/docs/src/pages/mutations.js

@@ -0,0 +1,106 @@
+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('/mutations')
+
+export default {
+  route: '/mutations',
+  meta: {
+    title: 'Mutations — Pulse Docs',
+    description: 'Synchronous state changes in Pulse — how to declare and trigger mutations.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/mutations',
+    prev,
+    next,
+    content: `
+      ${h1('Mutations')}
+      ${lead('Mutations are the only permitted way to change client state. They are synchronous pure functions — network requests, DOM manipulation, and timers are structurally excluded. After every mutation, Pulse automatically applies constraints and re-renders the view.')}
+
+      ${section('what', 'What is a mutation?')}
+      <p>A mutation is a function with the signature <code>(state, event) =&gt; partialState</code>. It receives the current state and the DOM event that triggered it, and returns a plain object to merge into state.</p>
+      ${codeBlock(highlight(`mutations: {
+  increment: (state) => ({ count: state.count + 1 }),
+  decrement: (state) => ({ count: state.count - 1 }),
+  reset:     ()      => ({ count: 0 }),
+}`, 'js'))}
+      <p>The returned partial is shallow-merged. Only the returned keys are changed — everything else in state is preserved.</p>
+
+      ${section('binding', 'Binding mutations to DOM events')}
+      <p>Mutations are bound to DOM events using the <code>data-event</code> attribute in the view HTML:</p>
+      ${codeBlock(highlight(`<button data-event="increment">+</button>         <!-- click → increment -->
+<button data-event="click:decrement">-</button>   <!-- explicit click -->
+<input  data-event="change:setName">              <!-- change event -->
+<input  data-event="input:setQuery">              <!-- input event (every keystroke) -->`, 'html'))}
+
+      ${table(
+        ['Event type', 'Shorthand', 'Typical use'],
+        [
+          ['<code>click</code>', '<code>data-event="mutName"</code>', 'Buttons, links'],
+          ['<code>change</code>', '<code>data-event="change:mutName"</code>', 'Select dropdowns, checkboxes'],
+          ['<code>input</code>', '<code>data-event="input:mutName"</code>', 'Search/filter fields — add <code>data-debounce="300"</code> to rate-limit'],
+        ]
+      )}
+
+      ${section('debounce', 'Debounce and throttle')}
+      <p>Add <code>data-debounce="300"</code> alongside <code>data-event</code> to delay the mutation until typing stops. The mutation fires once, 300ms after the last keystroke — not on every character. Use this for live search and filter inputs.</p>
+      ${codeBlock(highlight(`<input data-event="input:search" data-debounce="300">
+<input data-event="input:filter" data-throttle="100">`, 'html'))}
+      <p><code>data-throttle="100"</code> fires at most once per 100ms — useful when you want frequent updates but need to limit the rate. Both attributes accept a value in milliseconds and apply to <code>input</code> and <code>change</code> events. No per-spec timer code needed.</p>
+
+      ${section('event-arg', 'The event argument')}
+      <p>The second argument to a mutation is the native DOM <code>Event</code> object, giving access to the element and its value:</p>
+      ${codeBlock(highlight(`mutations: {
+  setName:    (state, e) => ({ name: e.target.value }),
+  setCountry: (state, e) => ({ country: e.target.value }),
+  toggle:     (state, e) => ({ checked: e.target.checked }),
+}`, 'js'))}
+
+      ${section('partial-merge', 'Partial state merge')}
+      <p>Only the keys that need to change are returned. The runtime merges the returned object into the existing state at the top level:</p>
+      ${codeBlock(highlight(`// state = { step: 2, name: 'Alice', email: 'a@b.com' }
+
+mutations: {
+  nextStep: (state) => ({ step: state.step + 1 }),
+  // After: { step: 3, name: 'Alice', email: 'a@b.com' }
+  // name and email are untouched
+}`, 'js'))}
+      ${callout('warning', 'The merge is <strong>shallow</strong>. When state has nested objects, returning a new version of a nested key replaces the entire sub-object — not a deep merge. Use the spread operator to preserve nested fields:')}
+      ${codeBlock(highlight(`mutations: {
+  setEmail: (state, e) => ({
+    // Spread the nested object to preserve sibling keys
+    user: { ...state.user, email: e.target.value }
+  }),
+}`, 'js'))}
+
+      ${section('no-side-effects', 'No side effects')}
+      <p>Mutations are pure functions. Network requests, DOM manipulation, and timers belong in <a href="/actions">actions</a> — not here. The structural separation is what lets Pulse re-render predictably, apply constraints safely, and make state changes auditable.</p>
+
+      ${section('constraints', 'Mutations and constraints')}
+      <p>After every mutation, Pulse automatically applies any <a href="/constraints">constraints</a> declared in the spec. State bounds are never checked inside mutations — they are declared once and enforced by the framework regardless of what a mutation returns:</p>
+      ${codeBlock(highlight(`{
+  state: { count: 0 },
+  constraints: { count: { min: 0, max: 10 } },
+  mutations: {
+    increment: (state) => ({ count: state.count + 1 }),
+    // count is automatically clamped to 10 — no need to check here
+  }
+}`, 'js'))}
+
+      ${section('forms', 'Mutations and forms')}
+      <p>Mirroring every keystroke into state via <code>data-event="input:..."</code> causes <code>innerHTML</code> replacement on each keypress, which destroys input focus. Pulse prevents this by keeping form inputs uncontrolled — values are captured via <code>FormData</code> in an action's <code>onStart</code>, before the view re-renders:</p>
+      ${codeBlock(highlight(`<!-- mirroring every keystroke causes focus loss -->
+<input data-event="input:setEmail">
+
+<!-- uncontrolled: values captured at submit via FormData -->
+<form data-action="submit">
+  <input name="email" type="email">
+  <button>Submit</button>
+</form>`, 'html'))}
+      ${callout('tip', 'Mutations are the right tool for binary UI state (toggles, step counters, tab selections) and controls where a re-render on each change is acceptable — such as live character counters or filtered lists. For form submission, use actions.')}
+    `,
+  }),
+}

package/docs/src/pages/navigation.js

@@ -0,0 +1,85 @@
+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('/navigation')
+
+export default {
+  route: '/navigation',
+  meta: {
+    title: 'Navigation — Pulse Docs',
+    description: 'Client-side navigation in Pulse — how link interception, JSON responses, and spec re-mounting work.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/navigation',
+    prev,
+    next,
+    content: `
+      ${h1('Navigation')}
+      ${lead('Client-side navigation in Pulse requires no configuration. When hydration is active, same-origin link clicks are intercepted automatically — the server renders the new page and returns JSON, and Pulse swaps the content without a full reload. If anything fails, it falls back to standard browser navigation.')}
+
+      ${section('how-it-works', 'How it works')}
+      <p>When <code>initNavigation</code> is called (part of the hydration bootstrap), Pulse attaches a click listener to the document. When a same-origin <code>&lt;a&gt;</code> is clicked:</p>
+      <ol>
+        <li>The default navigation is prevented.</li>
+        <li>A fetch request is sent to the new URL with the header <code>X-Pulse-Navigate: true</code>.</li>
+        <li>The server renders the page and returns a JSON response instead of full HTML.</li>
+        <li>Pulse replaces the current page's root <code>innerHTML</code> with the new content and updates <code>document.title</code>.</li>
+        <li>The new page's spec bundle is dynamically imported.</li>
+        <li><code>mount()</code> is called to bind the new spec's events.</li>
+        <li>The browser history is updated with <code>history.pushState</code>.</li>
+      </ol>
+      ${callout('note', 'If any step fails — network error, missing bundle, unexpected response — Pulse falls back to <code>location.href = url</code> for a standard full-page navigation.')}
+
+      ${section('init-navigation', 'initNavigation')}
+      <p><code>initNavigation</code> is called automatically by the hydration bootstrap script. You do not call it manually in application code. It is exported from the runtime for use in custom bootstrap scenarios:</p>
+      ${codeBlock(highlight(`import { mount } from '@invisibleloop/pulse/runtime'
+import { initNavigation } from '@invisibleloop/pulse/navigate'
+
+mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+initNavigation(root, mount)`, 'js'))}
+
+      ${section('json-response', 'JSON response shape')}
+      <p>When Pulse receives a request with <code>X-Pulse-Navigate: true</code>, it renders the page and returns:</p>
+      ${codeBlock(highlight(`{
+  "html":        "<main>...the page content...</main>",
+  "title":       "New Page Title — Site",
+  "hydrate":     "/dist/new-page.boot-abc123.js",
+  "serverState": { "key": "value" }
+}`, 'js'))}
+      ${table(
+        ['Field', 'Description'],
+        [
+          ['<code>html</code>', 'The rendered page content (the output of the view function, without the full document wrapper).'],
+          ['<code>title</code>', 'The new page title, set via <code>document.title</code>.'],
+          ['<code>hydrate</code>', 'The bundle path for the new spec. <code>null</code> if the page has no hydration.'],
+          ['<code>serverState</code>', 'The server data for the new page, used when mounting the new spec.'],
+        ]
+      )}
+
+      ${section('link-interception', 'Which links are intercepted')}
+      <p>Only same-origin links are intercepted. Links with <code>target="_blank"</code>, <code>download</code>, <code>rel="external"</code>, or any cross-origin <code>href</code> are ignored and behave normally:</p>
+      ${codeBlock(highlight(`<!-- Intercepted by Pulse client navigation -->
+<a href="/about">About</a>
+<a href="/products/42">Product</a>
+
+<!-- NOT intercepted — standard browser navigation -->
+<a href="https://example.com">External</a>
+<a href="/report.pdf" download>Download</a>
+<a href="/admin" target="_blank">Open in new tab</a>`, 'html'))}
+
+      ${section('history', 'Browser history')}
+      <p>Pulse uses the History API (<code>history.pushState</code>) to update the URL after each navigation. The back and forward buttons work as expected — each history entry corresponds to a page navigation.</p>
+      <p>When the user navigates back, Pulse receives a <code>popstate</code> event and performs the same fetch-and-swap process for the previous URL.</p>
+
+      ${section('no-hydration', 'Navigation without hydration')}
+      <p>Client-side navigation only works on pages that have loaded the Pulse client runtime (i.e. pages with a <code>hydrate</code> path). If a user navigates from a hydrated page to a non-hydrated page, Pulse falls back to a full page load.</p>
+      ${callout('tip', 'For documentation sites or mostly-static apps, omitting <code>hydrate</code> entirely and relying on standard browser navigation is simpler and keeps the JS payload at zero.')}
+
+      ${section('scroll', 'Scroll behaviour')}
+      <p>After each client-side navigation, Pulse scrolls to the top of the page — matching the behaviour of a full page load. If the URL includes a hash (e.g. <code>/docs#section</code>), Pulse scrolls to the target element.</p>
+    `,
+  }),
+}