@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/mutations.js

@@ -1,107 +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('/mutations')
-
-export default {
-  route: '/mutations',
-  meta: {
-    theme:       'light',
-    title: 'Mutations — Pulse Docs',
-    description: 'Synchronous state changes in Pulse — how to declare and trigger mutations.',
-    styles: ['/theme.css', '/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

@@ -1,85 +0,0 @@
-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: {
-    theme:       'light',
-    title: 'Navigation — Pulse Docs',
-    description: 'Client-side navigation in Pulse — how link interception, JSON responses, and spec re-mounting work.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  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>
-    `,
-  }),
-}

package/docs/src/pages/performance.js

@@ -1,157 +0,0 @@
-import { renderLayout, h1, lead, section, codeBlock, table, callout } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/performance')
-
-export default {
-  route: '/performance',
-  meta: {
-    theme:       'light',
-    title: 'Performance — Pulse Docs',
-    description: 'Performance targets, techniques, and built-in optimisations in Pulse.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/performance',
-    prev,
-    next,
-    content: `
-      ${h1('Performance')}
-      ${lead('Performance in Pulse is structural, not optional. Streaming SSR, immutable asset caching, brotli compression, and zero client JS by default are the baseline — not optimisations applied after the fact. A page that uses the framework correctly cannot score poorly.')}
-
-      ${section('targets', 'Performance targets')}
-      <p>Every page served by Pulse should meet these targets on localhost with no throttling:</p>
-      ${table(
-        ['Metric', 'Target', 'How'],
-        [
-          ['LCP', 'Fast', 'Streaming SSR sends HTML before server data resolves. Actual LCP depends on server location, CDN, and network conditions.'],
-          ['CLS', '0.00', 'Always set <code>width</code> and <code>height</code> on images; framework never shifts layout'],
-          ['Lighthouse Performance', '100', 'Compression, immutable caching, no render-blocking resources'],
-          ['Lighthouse Accessibility', '100', 'Semantic HTML, proper alt text, sufficient contrast'],
-          ['Lighthouse SEO', '100', 'Meta tags, structured data, canonical links'],
-          ['Lighthouse Best Practices', '100', 'HTTPS, security headers, no deprecated APIs'],
-        ]
-      )}
-      ${callout('note', 'Run <code>mcp__chrome-devtools__lighthouse_audit</code> after every new page to verify all four scores are 100. Fix any failures before considering the task done.')}
-      ${callout('warning', '<strong>Third-party ads caveat:</strong> Pages that load ad network scripts will not achieve 100 across all categories. Ad scripts introduce render-blocking JS, third-party cookies (Best Practices), and late-loading content that causes CLS. Reserving fixed space for ad slots reduces CLS but cannot fully compensate for what ad networks inject at runtime. Treat 100/100/100 as the baseline for ad-free pages only.')}
-
-      ${section('streaming-ssr', 'Streaming SSR')}
-      <p>Pulse uses Node.js streams for SSR. The server sends the <code>&lt;head&gt;</code> and page shell immediately, before any async data resolves. Browsers start downloading CSS and fonts while the server fetches data — so the user sees a styled shell within milliseconds.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/feed',
-
-  // Shell renders instantly — hero, nav, layout
-  // Deferred segments wait for data then stream in
-  stream: {
-    shell:    ['header', 'hero'],
-    deferred: ['feed', 'sidebar'],
-  },
-
-  server: {
-    feed:    async () => db.posts.getLatest(20),   // slow
-    sidebar: async () => db.tags.getPopular(),     // slow
-  },
-
-  // view is a keyed object matching stream segments
-  view: {
-    header:  (state) => \`<header>...</header>\`,
-    hero:    (state) => \`<section class="hero">...</section>\`,
-    feed:    (state, server) => server.feed.map(renderPost).join(''),
-    sidebar: (state, server) => renderSidebar(server.sidebar),
-  },
-}`, 'js'))}
-
-      ${section('compression', 'Automatic compression')}
-      <p>All responses are compressed automatically. Pulse negotiates the best available encoding from the <code>Accept-Encoding</code> header:</p>
-      ${table(
-        ['Encoding', 'Priority', 'Typical savings'],
-        [
-          ['Brotli (<code>br</code>)', 'First choice', '20–30% smaller than gzip for text content'],
-          ['gzip', 'Fallback', 'Widely supported, good compression'],
-          ['None', 'Last resort', 'No compression (rare)'],
-        ]
-      )}
-      <p>HTML, CSS, JavaScript, JSON, XML, and SVG responses are all compressed. Binary formats (images, fonts) are served as-is.</p>
-
-      ${section('asset-caching', 'Immutable asset caching')}
-      <p>Production JS bundles include a content hash in their filename (<code>/dist/counter.boot-a1b2c3d4.js</code>). The server sends <code>Cache-Control: public, max-age=31536000, immutable</code> for these files — browsers cache them forever and never re-request them unless the hash changes.</p>
-      <p>When you deploy a new version, the hash changes, and users automatically get the new file. No cache-busting tricks needed.</p>
-      ${callout('tip', 'Static assets in <code>public/</code> get <code>max-age=3600</code>. For rarely-updated images, consider versioning them by filename.')}
-
-      ${section('zero-client-js', 'Zero client JS by default')}
-      <p>Pages with no <code>mutations</code>, <code>actions</code>, or <code>persist</code> send no JavaScript at all — the HTML is entirely self-contained. The Pulse CLI detects this automatically; you never need to opt out. This is appropriate for static content pages: marketing pages, blog posts, documentation.</p>
-      ${codeBlock(highlight(`// No mutations, actions, or persist → zero JS sent to browser
-export default {
-  route: '/about',
-  meta:  { title: 'About', styles: ['/app.css'] },
-  view:  () => \`<main><h1>About us</h1></main>\`,
-}`, 'js'))}
-
-      ${section('js-bundle-splitting', 'JS bundle splitting and caching')}
-      <p>When you open the network tab you will see a single <code>[page].boot-[hash].js</code> file loading. What is inside that file depends on how many pages your app has:</p>
-      ${table(
-        ['App size', 'What the boot file contains', 'Size (brotli)'],
-        [
-          ['Single page', 'Your spec + the full Pulse runtime bundled together', '~4 kB'],
-          ['Multiple pages', 'Your spec only — runtime is in a separate <code>runtime-[hash].js</code> chunk', '~0.4–0.9 kB'],
-        ]
-      )}
-      <p>With multiple pages, esbuild's code splitting extracts the Pulse runtime into a shared chunk because every page imports it. The browser downloads it once and caches it — subsequent page navigations only fetch the small per-page boot file.</p>
-      <p><strong>What you see in the network tab across navigations:</strong></p>
-      <ul>
-        <li><strong>First page visit</strong> — <code>runtime-[hash].js</code> (~3.8 kB) + <code>home.boot-[hash].js</code> (~0.4 kB)</li>
-        <li><strong>Navigate to another page</strong> — <code>contact.boot-[hash].js</code> (~0.5 kB) only. Runtime already cached.</li>
-        <li><strong>Return visit</strong> — nothing. Both files served from cache with <code>immutable</code> headers.</li>
-      </ul>
-      ${callout('tip', 'The runtime hash only changes when the Pulse runtime itself is updated — not when your app changes. Deploying new pages or mutations does not bust the runtime cache for returning visitors.')}
-
-      ${section('security-headers', 'Security headers')}
-      <p>Every response — including 404 and 500 errors — carries a full set of security headers automatically. There is no configuration step and no way to accidentally omit them:</p>
-      ${table(
-        ['Header', 'Value'],
-        [
-          ['<code>X-Content-Type-Options</code>', '<code>nosniff</code>'],
-          ['<code>X-Frame-Options</code>', '<code>DENY</code>'],
-          ['<code>Referrer-Policy</code>', '<code>strict-origin-when-cross-origin</code>'],
-          ['<code>Permissions-Policy</code>', '<code>camera=(), microphone=(), geolocation=()</code>'],
-          ['<code>Cross-Origin-Opener-Policy</code>', '<code>same-origin</code>'],
-          ['<code>Cross-Origin-Resource-Policy</code>', '<code>same-origin</code>'],
-        ]
-      )}
-      <p>These headers are applied automatically — no configuration needed.</p>
-
-      ${section('browser-support', 'Browser support')}
-      <p>Pulse ships modern JavaScript and CSS without transpilation or polyfills. The effective minimum is set by two features:</p>
-      ${table(
-        ['Constraint', 'Chrome', 'Firefox', 'Safari', 'Edge', 'Since'],
-        [
-          ['<code>?.</code> optional chaining (JS)', '80', '74', '13.1', '80', 'Feb – Mar 2020'],
-          ['<code>gap</code> on flexbox (CSS)', '84', '63', '14.1', '84', 'Aug 2020 – Apr 2021'],
-        ]
-      )}
-      <p>In practice, <strong>Safari 14.1 (April 2021) is the combined floor</strong> — browsers released after that date support everything Pulse uses. This covers roughly 95%+ of global traffic.</p>
-      ${callout('note', 'No explicit <code>target</code> is set in the esbuild config, so syntax ships as written. If you need to support older browsers, set <code>target</code> in <code>scripts/build.js</code> and esbuild will downcompile optional chaining and other modern syntax automatically.')}
-
-      ${section('cls', 'Preventing layout shift (CLS)')}
-      <p>Pulse targets 0.00 CLS. Layout shift is caused by elements that change size or position after the initial paint. These rules prevent it:</p>
-      <ul>
-        <li>Always set <code>width</code> and <code>height</code> on images (use the <code>img()</code> helper)</li>
-        <li>Never inject content above existing content after page load</li>
-        <li>Use <code>aspect-ratio</code> CSS for embeds (videos, iframes)</li>
-        <li>Avoid loading web fonts that cause FOUT — use <code>font-display: swap</code> or system fonts</li>
-      </ul>
-
-      ${section('lcp', 'Optimising LCP')}
-      <p>LCP (Largest Contentful Paint) is typically your hero image or largest heading. Tips:</p>
-      <ul>
-        <li>Use <code>priority: true</code> on the LCP image — sets <code>fetchpriority="high"</code> and <code>loading="eager"</code></li>
-        <li>Avoid blocking server fetches — use <code>stream</code> so the shell renders without waiting for data</li>
-        <li>Keep your hero HTML inline (SSR) — never rely on client JS to render the LCP element</li>
-        <li>Use modern image formats (AVIF, WebP) via the <code>picture()</code> helper</li>
-      </ul>
-
-      ${callout('warning', 'Never render your LCP element (hero image, main heading) client-side. If it requires a client JS import or a dynamic import, it will not paint until JS executes — pushing LCP from &lt;100ms to &gt;500ms.')}
-    `,
-  }),
-}

package/docs/src/pages/persist.js

@@ -1,89 +0,0 @@
-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('/persist')
-
-export default {
-  route: '/persist',
-  meta: {
-    theme:       'light',
-    title: 'Persist — Pulse Docs',
-    description: 'Persist client state across page refreshes using localStorage.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  state: {},
-  view: () => renderLayout({
-    currentHref: '/persist',
-    prev,
-    next,
-    content: `
-      ${h1('Persist')}
-      ${lead('The <code>persist</code> field declares which state keys survive page refreshes. Everything else resets. The list is explicit — nothing is persisted unless it is named here, and sensitive data should never appear in it.')}
-
-      ${section('declaring', 'Declaring persistence')}
-      <p><code>persist</code> is an array of dot-path strings. Each path points to a key in state that should be saved:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/settings',
-  state: {
-    theme:       'light',
-    fontSize:    16,
-    sidebarOpen: true,
-    user: {
-      name:        '',
-      preferences: { notifications: true, newsletter: false },
-    },
-  },
-  persist: [
-    'theme',
-    'fontSize',
-    'user.preferences',
-  ],
-  // ...
-}`, 'js'))}
-      <p>In this example, <code>theme</code>, <code>fontSize</code>, and the entire <code>user.preferences</code> sub-object are saved to <code>localStorage</code>. The <code>sidebarOpen</code> key and <code>user.name</code> are session-only — they reset on each visit.</p>
-
-      ${section('how-it-works', 'How it works')}
-      <p>On every state update, Pulse serialises the persisted keys and writes them to <code>localStorage</code> under a key derived from the page route. On the next mount, persisted values are read back and merged over the spec's initial state before the view renders.</p>
-
-      ${table(
-        ['Step', 'What happens'],
-        [
-          ['First visit', 'State initialised from <code>spec.state</code>. Nothing in storage yet.'],
-          ['User interacts', 'Mutations update state. Persisted keys are written to <code>localStorage</code>.'],
-          ['Page refresh / return visit', 'Persisted values loaded from storage and merged over initial state. View renders with restored state.'],
-        ]
-      )}
-
-      ${section('dot-paths', 'Dot-path notation')}
-      <p>Persist keys use the same dot-path notation as <a href="/validation">validation</a>. Entire top-level keys or specific nested sub-objects can be persisted:</p>
-      ${codeBlock(highlight(`persist: [
-  'theme',                    // top-level key
-  'user.preferences',         // nested sub-object (entire object is saved)
-  'cart.items',               // array of cart items
-]`, 'js'))}
-      ${callout('note', 'When persisting a nested path like <code>user.preferences</code>, the <em>entire value at that path</em> is saved and restored — not individual sub-keys within it.')}
-
-      ${section('storage-key', 'Storage key')}
-      <p>Pulse stores persisted state under <code>pulse:[route]</code> in <code>localStorage</code>. For example, a spec with <code>route: \'/settings\'</code> uses the key <code>pulse:/settings</code>. This namespacing prevents collisions between pages.</p>
-
-      ${section('ssr', 'SSR and persistence')}
-      <p>On the server, <code>localStorage</code> does not exist. The server always renders with the spec's initial state. Persisted values are applied on the client after hydration — before the first mutation, after mount.</p>
-      ${callout('warning', 'If SSR and client state diverge significantly due to persisted values, a content flash may occur. Best practice: keep persisted state to preferences and settings that do not affect the main page content.')}
-
-      ${section('clearing', 'Clearing persisted state')}
-      <p>To clear persisted state programmatically, remove the relevant key from <code>localStorage</code>:</p>
-      ${codeBlock(highlight(`localStorage.removeItem('pulse:/settings')`, 'js'))}
-      <p>Or use a mutation that resets the persisted fields to their initial values — Pulse will save the reset values on the next update.</p>
-
-      ${section('best-practices', 'Best practices')}
-      <ul>
-        <li>Persist preferences and settings (theme, language, layout choices)</li>
-        <li>Persist shopping cart contents or draft form data</li>
-        <li>Never persist sensitive data (tokens, passwords, PII) — <code>localStorage</code> is not secure storage</li>
-        <li>Never persist data that must be authoritative — use <a href="/server-data">server data</a> for anything that should be fresh from the server</li>
-        <li>Keep persisted payloads small — <code>localStorage</code> has a ~5 MB limit and blocks the main thread if abused</li>
-      </ul>
-    `,
-  }),
-}

package/docs/src/pages/project-structure.js

@@ -1,91 +0,0 @@
-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('/project-structure')
-
-export default {
-  route: '/project-structure',
-  meta: {
-    theme:       'light',
-    title: 'Project Structure — Pulse Docs',
-    description: 'Recommended directory layout for a Pulse application.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/project-structure',
-    prev,
-    next,
-    content: `
-      ${h1('Project Structure')}
-      ${lead('Pulse enforces a single convention: one spec per page, one directory per concern. The structure is not a recommendation — it is how the framework discovers and registers your pages. There is nothing to configure because there is nothing to decide.')}
-
-      ${section('layout', 'Layout')}
-      ${codeBlock(highlight(`my-app/
-├── package.json
-├── public/                # static assets served directly
-│   ├── app.css
-│   └── dist/              # generated bundles (pulse build)
-│       ├── manifest.json
-│       ├── runtime-[hash].js
-│       └── [name].boot-[hash].js
-└── src/
-    ├── pages/             # one file per page — auto-discovered
-    │   ├── home.js
-    │   ├── about.js
-    │   └── contact.js
-    ├── lib/               # shared helpers
-    │   └── db.js
-    └── components/        # shared view fragments (optional)
-        └── card.js`, 'bash'))}
-
-      ${section('pages', 'src/pages/')}
-      <p>Each file in <code>src/pages/</code> exports a single spec as the default export. <code>pulse dev</code> auto-discovers every file in this directory and registers it as a route. There is no route registry to maintain — the file is the registration.</p>
-
-      ${callout('note', 'Routes are derived from filenames by default (<code>about.js</code> → <code>/about</code>). For dynamic segments, <code>route</code> is set explicitly in the spec.')}
-
-      ${section('public', 'public/')}
-      <p>Static files served directly — CSS, fonts, images. Referenced via <code>meta.styles</code> in the spec. The <code>dist/</code> subdirectory is generated by <code>pulse build</code>. Its contents are content-hashed and must not be edited manually.</p>
-
-      ${table(
-        ['Path', 'Purpose'],
-        [
-          ['<code>public/app.css</code>', 'Your global stylesheet — reference it in spec <code>meta.styles</code>'],
-          ['<code>public/dist/</code>', 'Generated bundles from <code>npm run build</code> — do not edit manually'],
-          ['<code>public/dist/manifest.json</code>', 'Maps spec hydrate paths to hashed bundle filenames'],
-        ]
-      )}
-
-      ${section('lib', 'src/lib/')}
-      <p>Shared helpers used across multiple pages — database clients, API wrappers, utility functions. Imported directly into specs. Plain JavaScript modules with no framework coupling — they work identically in tests, scripts, or other contexts.</p>
-
-      ${section('components', 'src/components/ (optional)')}
-      <p>Reusable view fragments. Since views are just functions that return HTML strings, a component is simply a function:</p>
-
-      ${codeBlock(highlight(`// src/components/card.js
-export function card({ title, body }) {
-  return \`
-    <div class="card">
-      <h2>\${title}</h2>
-      <p>\${body}</p>
-    </div>
-  \`
-}`, 'js'), 'src/components/card.js')}
-
-      ${codeBlock(highlight(`// src/pages/home.js
-import { card } from '../components/card.js'
-
-export default {
-  route: '/',
-  view: () => card({ title: 'Hello', body: 'Welcome to Pulse' }),
-}`, 'js'), 'src/pages/home.js')}
-
-      ${section('one-file-per-page', 'One file per page')}
-      <p>Pulse enforces <strong>one spec per file</strong>. Every page is self-contained — state, view, mutations, actions, and validation in one place. This is not a style preference. It is how the framework eliminates the question of where things live.</p>
-
-      <p>This holds for dynamic routes too: <code>route: '/blog/:slug'</code> is <strong>one spec serving every matching URL</strong> — the <code>:param</code> does the multiplying, so a thousand blog posts are still a single file. A site is therefore a small collection of specs, one per route, sharing layouts and sections from <code>src/components/</code> rather than repeating them.</p>
-
-      ${callout('tip', 'For large pages, view fragments and helpers can be imported from other modules. The spec file remains the coordination point — the structure is always clear regardless of how the implementation is organised.')}
-    `,
-  }),
-}