@invisibleloop/pulse 0.1.21

package/docs/src/pages/spec.js

@@ -0,0 +1,207 @@
+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('/spec')
+
+export default {
+  route: '/spec',
+  meta: {
+    title: 'Spec Reference — Pulse Docs',
+    description: 'Complete reference for every field in a Pulse page spec.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/spec',
+    prev,
+    next,
+    content: `
+      ${h1('Spec Reference')}
+      ${lead('The spec is a plain JavaScript object that defines a complete contract for a page. Pulse validates every spec at startup and rejects invalid ones before the server accepts connections. At runtime, it enforces state bounds, validation rules, and lifecycle order automatically.')}
+
+      ${section('quick-ref', 'Quick reference')}
+      ${table(
+        ['Field', 'Type', 'Required', 'Description'],
+        [
+          ['<code>route</code>', '<code>string</code>', 'Yes', 'URL pattern for this page. Supports <code>:param</code> segments.'],
+          ['<code>state</code>', '<code>object</code>', 'Yes', 'Initial client-side state. Deep-cloned on mount.'],
+          ['<code>view</code>', '<code>function</code>', 'Yes', 'Returns an HTML string. Receives <code>(state, serverState)</code>.'],
+          ['<code>meta</code>', '<code>object</code>', 'No', 'Page metadata: title, description, styles, OG tags, schema.'],
+          ['<code>hydrate</code>', '<code>string</code>', 'No', 'Browser-importable path to this spec file. Enables client hydration.'],
+          ['<code>mutations</code>', '<code>object</code>', 'No', 'Synchronous state updaters keyed by name.'],
+          ['<code>actions</code>', '<code>object</code>', 'No', 'Async operations with full lifecycle hooks.'],
+          ['<code>validation</code>', '<code>object</code>', 'No', 'Declarative validation rules keyed by dot-path state keys.'],
+          ['<code>constraints</code>', '<code>object</code>', 'No', 'Min/max bounds enforced after every mutation.'],
+          ['<code>persist</code>', '<code>string[]</code>', 'No', 'State keys to save in <code>localStorage</code>.'],
+          ['<code>server</code>', '<code>object</code>', 'No', 'Server-side data fetcher. Result passed to <code>view</code> as second arg.'],
+          ['<code>store</code>', '<code>string[]</code>', 'No', 'Global store keys this page subscribes to. See <a href="/store">Global Store</a>.'],
+          ['<code>methods</code>', '<code>string[]</code>', 'No', 'HTTP methods this page accepts. Default <code>[\'GET\', \'HEAD\']</code>. Add <code>\'POST\'</code> etc. to opt in.'],
+          ['<code>stream</code>', '<code>object</code>', 'No', 'Streaming SSR config: <code>shell</code> + <code>deferred</code> segment names.'],
+          ['<code>cache</code>', '<code>object</code>', 'No', 'HTTP cache control headers for the page response.'],
+          ['<code>serverTtl</code>', '<code>number</code>', 'No', 'Seconds to cache server data in-process.'],
+          ['<code>serverTimeout</code>', '<code>number</code>', 'No', 'Timeout in ms for all server fetchers on this page. Overrides the global <code>fetcherTimeout</code> option.'],
+          ['<code>contentType</code>', '<code>string</code>', 'No', 'Override response Content-Type. Enables raw (non-HTML) responses.'],
+          ['<code>onViewError</code>', '<code>function</code>', 'No', 'Fallback renderer called when <code>view()</code> throws. Return an HTML string.'],
+        ]
+      )}
+
+      ${section('route', 'route')}
+      <p>The URL pattern this spec handles. Supports static segments and dynamic <code>:param</code> segments.</p>
+      ${codeBlock(highlight(`route: '/products/:id'   // matches /products/42
+route: '/blog/:year/:slug'`, 'js'))}
+      <p>Dynamic segments are available in server data and actions via <code>ctx.params</code>. See <a href="/routing">Routing</a> for more.</p>
+
+      ${section('state', 'state')}
+      <p>The initial client-side state for the page. Always a plain object. Pulse deep-clones it on every mount — mutations never affect the original spec, and state cannot leak between page loads.</p>
+      ${codeBlock(highlight(`state: {
+  count: 0,
+  user: { name: '', email: '' },
+  items: [],
+}`, 'js'))}
+      <p>The state object is passed as the first argument to <code>view</code>, and as the first argument to every mutation and action hook. See <a href="/state">State</a>.</p>
+
+      ${section('view', 'view')}
+      <p>A pure function that receives <code>(state, serverState)</code> and returns an HTML string. Side effects are not permitted — the same inputs must always produce the same output. Pulse uses this guarantee to diff and re-render efficiently after mutations.</p>
+      ${codeBlock(highlight(`view: (state, server) => \`
+  <main>
+    <h1>Hello, \${state.name}</h1>
+    \${server.items.map(item => \`<p>\${item.title}</p>\`).join('')}
+  </main>
+\``, 'js'))}
+      <p>For streaming SSR, <code>view</code> can be an object of named segment functions. See <a href="/streaming">Streaming SSR</a>.</p>
+
+      ${section('meta', 'meta')}
+      <p>Page-level metadata. All fields are optional.</p>
+      ${codeBlock(highlight(`meta: {
+  title:       'Page Title — Site Name',
+  description: 'Meta description for search engines.',
+  styles:      ['/app.css', '/page.css'],
+  ogTitle:     'Open Graph title',
+  ogImage:     'https://example.com/og.jpg',
+  schema:      { '@type': 'WebPage', name: 'Page Title' }, // ld+json
+}`, 'js'))}
+      <p>See <a href="/meta">Metadata &amp; SEO</a> for the full reference.</p>
+
+      ${section('hydrate', 'hydrate')}
+      <p>A browser-importable path to this spec file. Setting this enables client-side hydration — Pulse emits a bootstrap script that imports the spec bundle and calls <code>mount()</code>. In production, the path is resolved automatically via <code>manifest.json</code>.</p>
+      ${codeBlock(highlight(`hydrate: '/src/pages/counter.js'   // dev: source file path
+// Production: resolved automatically via manifest.json`, 'js'))}
+      ${callout('note', 'Omit <code>hydrate</code> for purely server-rendered pages with no client interactivity. Pulse sends zero JavaScript to the browser — no runtime overhead, no hydration cost.')}
+
+      ${section('mutations', 'mutations')}
+      <p>Synchronous state updaters. Each mutation is a function <code>(state, event) =&gt; partialState</code>. The returned partial object is merged into state. See <a href="/mutations">Mutations</a>.</p>
+      ${codeBlock(highlight(`mutations: {
+  increment: (state) => ({ count: state.count + 1 }),
+  setName:   (state, event) => ({ name: event.target.value }),
+}`, 'js'))}
+      <p>Mutations can return <code>_toast</code> to show a notification — it is stripped from state automatically. See <a href="/actions#toast">Toast notifications</a>.</p>
+
+      ${section('actions', 'actions')}
+      <p>Async operations with a full lifecycle. Each action has hooks for <code>onStart</code>, optional <code>validate</code>, <code>run</code>, <code>onSuccess</code>, and <code>onError</code>. See <a href="/actions">Actions</a>.</p>
+      ${codeBlock(highlight(`actions: {
+  submit: {
+    onStart:   (state, formData) => ({ status: 'loading' }),
+    validate:  true,
+    run:       async (state, serverState, formData) => {
+      const res = await fetch('/api/submit', { method: 'POST', body: formData })
+      return res.json()
+    },
+    onSuccess: (state, payload) => ({ status: 'success', data: payload }),
+    onError:   (state, err) => ({
+      status: 'error',
+      errors: err?.validation ?? [{ message: err.message }],
+    }),
+  },
+}`, 'js'))}
+
+      ${section('validation', 'validation')}
+      <p>Declarative rules checked when an action has <code>validate: true</code>. Keys are dot-path strings into state. See <a href="/validation">Validation</a>.</p>
+      ${codeBlock(highlight(`validation: {
+  'fields.email': { required: true, format: 'email' },
+  'fields.name':  { required: true, minLength: 2, maxLength: 100 },
+  'fields.age':   { required: true, min: 18, max: 120 },
+}`, 'js'))}
+
+      ${section('constraints', 'constraints')}
+      <p>Min/max bounds enforced automatically after every mutation. Constraints cannot be bypassed — the state is clamped before the view re-renders, regardless of what the mutation returns. See <a href="/constraints">Constraints</a>.</p>
+      ${codeBlock(highlight(`constraints: {
+  count:    { min: 0, max: 100 },
+  quantity: { min: 1, max: 99 },
+}`, 'js'))}
+
+      ${section('persist', 'persist')}
+      <p>An array of dot-path state keys to persist in <code>localStorage</code>. Values are restored on the next visit. See <a href="/persist">Persist</a>.</p>
+      ${codeBlock(highlight(`persist: ['theme', 'user.preferences']`, 'js'))}
+
+      ${section('server', 'server')}
+      <p>Server-only data fetching. The result is passed to <code>view</code> as the second argument. Not available on the client. See <a href="/server-data">Server Data</a>.</p>
+      ${codeBlock(highlight(`server: {
+  data: async (ctx) => {
+    const product = await db.products.find(ctx.params.id)
+    return { product }
+  }
+}`, 'js'))}
+
+      ${section('stream', 'stream')}
+      <p>Enables streaming SSR. Declare which named view segments are in the <code>shell</code> (rendered immediately) and which are <code>deferred</code> (streamed when ready). See <a href="/streaming">Streaming SSR</a>.</p>
+      ${codeBlock(highlight(`stream: {
+  shell:    ['header', 'nav'],
+  deferred: ['feed', 'sidebar'],
+}`, 'js'))}
+
+      ${section('cache', 'cache')}
+      <p>HTTP Cache-Control header configuration for the page response. See <a href="/caching">Caching</a>.</p>
+      ${codeBlock(highlight(`cache: {
+  public:              true,
+  maxAge:              300,       // seconds
+  staleWhileRevalidate: 86400,
+}`, 'js'))}
+
+      ${section('serverTtl', 'serverTtl')}
+      <p>Number of seconds to cache the result of <code>server.data()</code> in-process. Subsequent requests within the TTL skip the async data fetch and re-render the HTML with the cached data. See <a href="/caching">Caching</a>.</p>
+      ${codeBlock(highlight(`serverTtl: 60  // cache server data for 60 seconds`, 'js'))}
+      ${callout('tip', '<strong>serverTtl vs cache</strong> — <code>serverTtl</code> caches only the server data fetcher results. The HTML is re-rendered on every request (good for personalised pages where only the fetched data is stable). <code>cache</code> caches the complete rendered HTML and sets <code>Cache-Control</code> headers (good for fully public pages that are identical for all users).')}
+
+      ${section('serverTimeout', 'serverTimeout')}
+      <p>Timeout in milliseconds for all <code>server.*</code> fetchers on this page. If any fetcher does not resolve within this limit, it rejects with a timeout error and the request returns a 500. Use this to prevent a slow DB query or external API from hanging the response indefinitely.</p>
+      ${codeBlock(highlight(`serverTimeout: 5000  // fail after 5 s — overrides createServer fetcherTimeout`, 'js'))}
+      <p>A global default applies to all pages via the <code>fetcherTimeout</code> option in <code>createServer</code>. <code>spec.serverTimeout</code> overrides it per page.</p>
+
+      ${section('on-view-error', 'onViewError')}
+      <p>An optional function called when <code>view()</code> throws at runtime. Return an HTML string to display in place of the crashed view. Without this, the Pulse runtime renders a default inline error message and logs the error to the console.</p>
+      ${codeBlock(highlight(`onViewError: (err, state, serverState) => \`
+  <div class="u-p-4 u-text-center">
+    <p>Something went wrong. <a href="">Reload</a></p>
+  </div>
+\``, 'js'))}
+      ${callout('note', 'On the server, a throwing view propagates to the server\'s error handler (500 response) unless <code>onViewError</code> is defined — in which case the page renders with the fallback HTML and a 200 status. On the client, the runtime always catches view errors and shows a fallback, whether or not <code>onViewError</code> is defined.')}
+
+      ${section('methods', 'methods')}
+      <p>HTTP methods this page accepts. Defaults to <code>['GET', 'HEAD']</code> — all other methods return 405. Add <code>'POST'</code> to handle form submissions or webhooks directly on a page route without a separate API endpoint.</p>
+      ${codeBlock(highlight(`methods: ['GET', 'POST']`, 'js'))}
+      <p>Read the method in <code>guard</code> to branch on POST vs GET:</p>
+      ${codeBlock(highlight(`export default {
+  route:   '/contact',
+  methods: ['GET', 'POST'],
+
+  guard: async (ctx) => {
+    if (ctx.method === 'POST') {
+      const data = await ctx.formData()
+      if (!data?.email) return { status: 422, json: { error: 'Email required' } }
+      await db.leads.create(data)
+      return { redirect: '/contact?sent=1' }
+    }
+  },
+
+  state: {},
+  view:  (state) => \`<form method="POST">...</form>\`,
+}`, 'js'))}
+      ${callout('note', 'For raw response specs (<code>contentType</code> set), all HTTP methods are accepted by default — <code>methods</code> has no effect. Use <code>ctx.method</code> inside <code>render</code> to branch.')}
+
+      ${section('contentType', 'contentType')}
+      <p>Override the response <code>Content-Type</code>. When set, the view function receives <code>(ctx, serverState)</code> and returns the raw response body — the normal HTML wrapper is bypassed. See <a href="/raw-responses">Raw Responses</a>.</p>
+      ${codeBlock(highlight(`contentType: 'application/rss+xml'`, 'js'))}
+    `,
+  }),
+}

package/docs/src/pages/state.js

@@ -0,0 +1,101 @@
+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('/state')
+
+export default {
+  route: '/state',
+  meta: {
+    title: 'State — Pulse Docs',
+    description: 'How client state is declared, initialised, and used in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/state',
+    prev,
+    next,
+    content: `
+      ${h1('State')}
+      ${lead('Pulse enforces a strict one-way data flow. State is declared once in the spec, deep-cloned on mount, and changed only through mutations. Direct mutation is not possible — the framework prevents it by design.')}
+
+      ${section('declaring', 'Declaring state')}
+      <p>The <code>state</code> field of a spec is the initial value. Always a plain object — nested objects and arrays are supported:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/checkout',
+  state: {
+    step: 1,
+    customer: {
+      name:  '',
+      email: '',
+    },
+    items:    [],
+    promoCode: null,
+  },
+  // ...
+}`, 'js'))}
+      ${callout('note', '<code>state: {}</code> is always included, even on pages with no interactivity. The spec schema requires it.')}
+
+      ${section('view-receives', 'The view receives state')}
+      <p>The <code>view</code> function is called with the current state as its first argument. On first render this is the initial state (or state restored from <code>localStorage</code> if <code>persist</code> is set). After mutations it is the updated state:</p>
+      ${codeBlock(highlight(`view: (state) => \`
+  <div>
+    <p>Step \${state.step} of 3</p>
+    <p>Hello, \${state.customer.name || 'guest'}</p>
+    <ul>
+      \${state.items.map(item => \`<li>\${item.name}</li>\`).join('')}
+    </ul>
+  </div>
+\``, 'js'))}
+
+      ${section('immutability', 'Immutability')}
+      <p>State is never mutated directly. Mutations are pure functions that return a <em>partial</em> object to merge — the framework rejects any other pattern:</p>
+      ${codeBlock(highlight(`// CORRECT — return a partial update
+mutations: {
+  nextStep: (state) => ({ step: state.step + 1 }),
+}
+
+// WRONG — never mutate state directly
+mutations: {
+  nextStep: (state) => { state.step++ },   // ✗ do not do this
+}`, 'js'))}
+      <p>The runtime performs a shallow merge of the returned partial into the current state. This means top-level keys are replaced, not deep-merged:</p>
+      ${codeBlock(highlight(`// state = { step: 1, customer: { name: 'Alice', email: 'a@b.com' } }
+
+mutations: {
+  // Only updates step — customer is untouched
+  nextStep: (state) => ({ step: state.step + 1 }),
+
+  // Replaces the entire customer object — spread to preserve email
+  setName: (state, e) => ({
+    customer: { ...state.customer, name: e.target.value }
+  }),
+}`, 'js'))}
+
+      ${section('deep-clone', 'Deep clone on mount')}
+      <p>When the page mounts, Pulse deep-clones <code>spec.state</code>. This guarantees:</p>
+      <ul>
+        <li>The live state and the spec's initial state are completely independent — mutations cannot corrupt the spec.</li>
+        <li>Navigating away and back resets state to the spec's initial values (unless <a href="/persist">persisted</a>).</li>
+        <li>Multiple instances of the same spec on the same page each get independent state.</li>
+      </ul>
+
+      ${section('server-state', 'State vs server state')}
+      <p>Pulse draws a hard boundary between <em>client state</em> (the <code>state</code> field) and <em>server state</em> (from <code>server.data()</code>). Client state lives in the browser and changes in response to mutations. Server state is resolved before render and passed to the view as its second argument — it is never exposed to the client after hydration:</p>
+      ${codeBlock(highlight(`view: (state, server) => \`
+  <div>
+    <h1>\${server.product.name}</h1>      <!-- server state -->
+    <p>Qty: \${state.quantity}</p>         <!-- client state -->
+  </div>
+\``, 'js'))}
+      ${callout('note', 'Server state is read-only and not available on the client after hydration. Anything that needs client interactivity belongs in <code>state</code>.')}
+
+      ${section('ssr-state', 'State during SSR')}
+      <p>On the server, the view is rendered with the spec's initial state. After hydration, <code>mount()</code> is called with <code>{ ssr: true }</code>, which skips the first client-side re-render and preserves the SSR-painted HTML exactly as the server sent it. This is what enables fast LCP — the initial HTML arrives from the server and the JS binds events without touching the DOM.</p>
+
+      ${section('persist-link', 'Persisting state')}
+      <p>State keys listed in the <a href="/persist"><code>persist</code></a> field are saved to <code>localStorage</code> and restored before the view renders on the next visit.</p>
+    `,
+  }),
+}

package/docs/src/pages/store.js

@@ -0,0 +1,181 @@
+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('/store')
+
+export default {
+  route: '/store',
+  meta: {
+    title: 'Global Store — Pulse Docs',
+    description: 'Share server-fetched data across pages with a global store in Pulse.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/store',
+    prev,
+    next,
+    content: `
+      ${h1('Global Store')}
+      ${lead('The global store is a single shared data layer. Declare server fetchers once in <code>pulse.store.js</code> — user profiles, settings, feature flags — and any page can access them by name. No prop drilling, no repeated fetches.')}
+
+      ${section('when-to-use', 'When to use the store')}
+      <p>The store is the right tool when the same server data is needed on multiple pages and it would be wasteful to redeclare the same fetcher in every spec:</p>
+      <ul>
+        <li>Current user / session — <code>store.user</code></li>
+        <li>App settings or feature flags — <code>store.settings</code></li>
+        <li>Navigation items that come from a CMS — <code>store.nav</code></li>
+        <li>Subscription or plan level — <code>store.plan</code></li>
+      </ul>
+      ${callout('note', 'The store has no client-side reactivity. Data is fetched on the server per request and is available to the view at mount time. For page-specific data, use <a href="/server-data"><code>spec.server</code></a> instead.')}
+
+      ${section('defining', 'Defining the store')}
+      <p>Create a <code>pulse.store.js</code> file at the root of your project. Export a plain object with an optional <code>state</code> (default values) and a <code>server</code> map of async fetchers:</p>
+      ${codeBlock(highlight(`// pulse.store.js
+export default {
+  // Default / fallback values used on the server before fetchers resolve
+  state: {
+    user:     null,
+    settings: { theme: 'dark', lang: 'en' },
+    nav:      [],
+  },
+
+  // Server fetchers — run once per request, results override state defaults
+  server: {
+    user:     async (ctx) => db.users.findByCookie(ctx.cookies.session),
+    settings: async (ctx) => db.settings.forUser(ctx.cookies.userId),
+    nav:      async ()    => cms.getNavItems(),
+  },
+}`, 'js'))}
+
+      ${section('registering', 'Registering the store')}
+      <p>Pass your store to <code>createServer</code> via the <code>store</code> option. The store is validated at startup — bad fetchers throw before the server accepts connections:</p>
+      ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
+import store from './pulse.store.js'
+import { dashboardSpec } from './src/pages/dashboard.js'
+import { settingsSpec }  from './src/pages/settings.js'
+
+createServer([dashboardSpec, settingsSpec], {
+  port:      3000,
+  staticDir: 'public',
+  store,                 // ← register the global store
+})`, 'js'))}
+
+      ${section('using', 'Using store data in a page')}
+      <p>Declare which store keys a page needs using the <code>store</code> field. Those keys are merged into the <code>server</code> argument of the view — alongside any page-level server data:</p>
+      ${codeBlock(highlight(`// src/pages/dashboard.js
+export default {
+  route:    '/dashboard',
+  store:    ['user', 'settings'],   // declare which store keys this page uses
+
+  // Page-level server data still works alongside store data
+  server: {
+    stats: async (ctx) => db.stats.forUser(ctx.store.user?.id),
+  },
+
+  state: { filter: 'week' },
+
+  view: (state, server) => \`
+    <main>
+      <h1>Hello, \${server.user?.name ?? 'there'}</h1>
+      <p>Theme: \${server.settings.theme}</p>
+      <p>Stats: \${server.stats.total} requests this \${state.filter}</p>
+    </main>
+  \`,
+}`, 'js'))}
+      <p>Only the keys listed in <code>spec.store</code> are available in the view — nothing leaks from the store to pages that do not declare a dependency on it. Page-level <code>server</code> keys always win if there is a name collision with the store.</p>
+
+      ${section('ctx-store', 'Accessing the store in server fetchers')}
+      <p>Store data is resolved before page server fetchers run. The full resolved store state is available as <code>ctx.store</code> in any page's <code>server</code> fetcher, <code>guard</code>, and <code>meta</code> functions:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/account',
+  store: ['user'],
+
+  // Guard can use ctx.store to check auth before fetching page data
+  guard: async (ctx) => {
+    if (!ctx.store.user) return { redirect: '/login' }
+  },
+
+  // Server fetchers receive ctx.store with the resolved store state
+  server: {
+    orders: async (ctx) => db.orders.forUser(ctx.store.user.id),
+  },
+
+  view: (state, server) => \`
+    <h1>Orders for \${server.user.name}</h1>
+  \`,
+}`, 'js'))}
+
+      ${section('store-field-reference', 'Store field reference')}
+      ${table(
+        ['Field', 'Type', 'Description'],
+        [
+          ['<code>state</code>', 'object', 'Default values. Used as fallbacks when a server fetcher returns <code>undefined</code> or the server key is absent.'],
+          ['<code>server</code>', 'object of functions', 'Async fetchers — <code>async (ctx) => value</code>. Receive the same <code>ctx</code> as page server fetchers. Results override <code>state</code> defaults.'],
+        ]
+      )}
+
+      ${section('spec-store-reference', 'spec.store field')}
+      ${table(
+        ['Field', 'Type', 'Description'],
+        [
+          ['<code>store</code>', 'string[]', 'Array of store key strings to make available in the view\'s <code>server</code> argument. e.g. <code>[\'user\', \'settings\']</code>'],
+        ]
+      )}
+      ${callout('tip', 'Pages that do not declare <code>store</code> receive no store data — the store never leaks to pages that do not ask for it.')}
+
+      ${section('reactivity', 'Reactive updates — no refresh needed')}
+      <p>When a page action changes store data, all other mounted pages that subscribe to the affected keys re-render immediately — no page refresh, no polling.</p>
+      <p>Return <code>_storeUpdate</code> from a page action's <code>onSuccess</code> to push a change into the global store:</p>
+      ${codeBlock(highlight(`// src/pages/settings.js
+export default {
+  route:    '/settings',
+  store:    ['settings'],
+  state:    { saved: false },
+
+  actions: {
+    saveTheme: {
+      run: async (state, server, payload) => {
+        const theme = payload.get('theme')
+        await fetch('/api/settings', { method: 'PATCH', body: payload })
+        return theme
+      },
+      onSuccess: (state, theme) => ({
+        saved: true,
+        _storeUpdate: { settings: { theme } },  // ← push to global store
+      }),
+      onError: (state, err) => ({ error: err.message }),
+    },
+  },
+
+  view: (state, server) => \`
+    <form data-action="saveTheme">
+      <select name="theme">
+        <option value="dark"  \${server.settings.theme === 'dark'  ? 'selected' : ''}>Dark</option>
+        <option value="light" \${server.settings.theme === 'light' ? 'selected' : ''}>Light</option>
+      </select>
+      <button type="submit">Save</button>
+      \${state.saved ? '<p>Saved!</p>' : ''}
+    </form>
+  \`,
+}`, 'js'))}
+      <p>Any other page that has <code>store: ['settings']</code> will re-render with the new theme value the moment <code>_storeUpdate</code> is dispatched — without navigating away or refreshing.</p>
+      ${callout('note', '<code>_storeUpdate</code> is stripped from the local page state — it is only forwarded to the store. The rest of the <code>onSuccess</code> return is merged into the page\'s own state as usual.')}
+
+      ${section('caching', 'Caching and performance')}
+      <p>Store fetchers run once per request, in parallel. They share the same request context as page server fetchers, so they can read cookies, params, and headers to scope data to the current user.</p>
+      <p>If your store data changes infrequently (nav items from a CMS, feature flags), consider adding a <code>serverTtl</code> to the relevant page spec to cache the full rendered HTML — or caching inside the fetcher itself:</p>
+      ${codeBlock(highlight(`// pulse.store.js — cache nav items in-process for 60 seconds
+import { createCache } from './src/lib/cache.js'
+
+const navCache = createCache(60)
+
+export default {
+  server: {
+    nav: async () => navCache.getOrFetch('nav', () => cms.getNavItems()),
+  },
+}`, 'js'))}
+    `,
+  }),
+}

package/docs/src/pages/streaming.js

@@ -0,0 +1,108 @@
+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('/streaming')
+
+export default {
+  route: '/streaming',
+  meta: {
+    title: 'Streaming SSR — Pulse Docs',
+    description: 'How streaming server-side rendering works in Pulse — shell, deferred segments, and when to use it.',
+    styles: ['/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/streaming',
+    prev,
+    next,
+    content: `
+      ${h1('Streaming SSR')}
+      ${lead('Streaming SSR eliminates the tradeoff between fast paint and real content. The shell — chrome, navigation, above-the-fold layout — renders and streams immediately. Slower data-dependent segments arrive over the same connection without blocking the initial paint.')}
+
+      ${section('how-it-works', 'How it works')}
+      <p>Without streaming, the server waits for all data to resolve before sending any HTML — slow queries block the entire response. Pulse splits the view into a <strong>shell</strong> (sent immediately) and <strong>deferred</strong> segments (sent as placeholders, then replaced when data resolves).</p>
+      <p>Deferred segments arrive as chunks of HTML over the same connection — no extra requests, no client-side JavaScript required to swap content in.</p>
+
+      ${section('enabling', 'Enabling streaming')}
+      <p>To use streaming, the <code>view</code> is an <strong>object of named segment functions</strong> rather than a single function. The spec declares which segments are in the shell and which are deferred:</p>
+      ${codeBlock(highlight(`export default {
+  route: '/dashboard',
+  state: {},
+  server: {
+    data: async (ctx) => ({
+      user:   await auth.getUser(ctx.cookies.sessionId),  // fast
+      feed:   await db.feed.latest(),                      // slow
+      stats:  await analytics.summary(ctx.params.id),      // slow
+    }),
+  },
+  stream: {
+    shell:    ['header', 'nav'],     // rendered immediately
+    deferred: ['feed', 'stats'],     // streamed when server data resolves
+  },
+  view: {
+    header: (state, server) => \`
+      <header class="site-header">
+        <a href="/">Dashboard</a>
+        <span>Hello, \${server.user.name}</span>
+      </header>
+    \`,
+    nav: () => \`
+      <nav>
+        <a href="/dashboard">Home</a>
+        <a href="/settings">Settings</a>
+      </nav>
+    \`,
+    feed: (state, server) => \`
+      <section class="feed">
+        \${server.feed.map(item => \`<article>\${item.title}</article>\`).join('')}
+      </section>
+    \`,
+    stats: (state, server) => \`
+      <div class="stats">
+        <p>Page views: \${server.stats.views}</p>
+        <p>Conversions: \${server.stats.conversions}</p>
+      </div>
+    \`,
+  },
+}`, 'js'))}
+
+      ${section('placeholders', 'Deferred placeholders')}
+      <p>While deferred segments are loading, Pulse renders a <code>&lt;div id="pulse-slot-[name]"&gt;</code> placeholder in their place. When the segment resolves, the rendered HTML is appended to the stream and a small inline script swaps the placeholder content.</p>
+      ${callout('note', 'The swap is done with a tiny inline script — not a separate JS bundle. Deferred streaming works even on pages with no hydration (<code>hydrate</code> omitted).')}
+
+      ${section('server-data', 'Server data and streaming')}
+      <p>All <code>server.data()</code> calls resolve in a single async call before rendering begins. Streaming is about splitting the <em>view</em> — not about parallelising data fetching. For parallel data fetching, use <code>Promise.all</code> inside <code>server.data()</code>:</p>
+      ${codeBlock(highlight(`server: {
+  data: async (ctx) => {
+    // Fetch in parallel — both requests run concurrently
+    const [feed, stats] = await Promise.all([
+      db.feed.latest(),
+      analytics.summary(),
+    ])
+    return { feed, stats }
+  },
+}`, 'js'))}
+
+      ${section('when-to-use', 'When to use streaming')}
+      ${table(
+        ['Scenario', 'Use streaming?'],
+        [
+          ['Page with fast server data (< 20ms)', 'No — standard SSR is simpler and fast enough'],
+          ['Page with slow database queries', 'Yes — stream the shell while data loads'],
+          ['Pages with above-the-fold and below-the-fold content', 'Yes — shell renders above the fold immediately'],
+          ['API or raw response endpoints', 'No — use <a href="/raw-responses">raw responses</a>'],
+        ]
+      )}
+
+      ${section('stream-option', 'Server-level streaming option')}
+      <p>Streaming is enabled by default in <code>createServer</code>. Disable it globally with <code>stream: false</code>:</p>
+      ${codeBlock(highlight(`createServer(specs, {
+  stream: false,  // disable streaming for all specs
+})`, 'js'))}
+      <p>Even with global streaming enabled, only specs that declare a <code>stream</code> field will use chunked responses. All other specs use regular buffered SSR.</p>
+
+      ${callout('tip', 'Streaming is most beneficial on pages with large datasets or slow queries. For most pages, the speed of Pulse\'s synchronous rendering means streaming adds unnecessary complexity.')}
+    `,
+  }),
+}