@invisibleloop/pulse 0.19.0 → 0.20.1

package/CLAUDE.md

@@ -75,8 +75,10 @@ export const mySpec = {
   //   async () => [...]  → enumerate a dynamic :param route's URLs
   sitemap: async () => (await db.posts.list()).map(p => `/blog/${p.slug}`),
 
-  // Global store keys this page subscribes to — appears in view's server arg
-  // Store mutations update all subscribed pages without a server round-trip
+  // Global store keys this page subscribes to — appears in view's server arg.
+  // The store is defined in pulse.store.js at the project root — AUTO-DISCOVERED
+  // by pulse dev/start (no registration step). Mutations update all subscribed
+  // pages without a server round-trip.
   store: ['user', 'cart'],
 
   // Initial client state — deep cloned on mount, never mutated directly
@@ -298,6 +300,8 @@ await createServer(
       '/old-blog/:slug': '/blog/:slug',          // :params carry over, query string preserved
       '/promo': { to: '/pricing', status: 302 }, // custom status: 301 | 302 | 307 | 308
     },                            // checked before routing (GET/HEAD only); validated at startup
+    live:         true,           // SSE store-push channel (default path /__pulse/live) —
+                                  // createServer returns pushStore(partial) for broadcasting
     csp: {                        // extra sources merged into the framework's default CSP
       'style-src': ['https://fonts.googleapis.com'],
       'font-src':  ['https://fonts.gstatic.com'],
@@ -314,6 +318,37 @@ await createServer(
 
 All specs are validated at startup — bad specs throw before the server accepts connections.
 
+## Live Store Push (SSE)
+
+With `live: true`, `createServer` returns a **`pushStore(partial)`** function that broadcasts a store patch to every connected browser. Pages subscribed via `spec.store` re-render immediately — no polling, no client code:
+
+```js
+// Enable in pulse.config.js (CLI-managed apps) or createServer options:
+export default { live: true }
+```
+
+```js
+// Broadcast from any spec file — e.g. a webhook that updates stock:
+import { pushStore } from '@invisibleloop/pulse'
+
+export default {
+  route: '/hooks/stock',
+  contentType: 'text/plain',
+  state: {},
+  render: async (ctx) => {
+    const { sku, stock } = await ctx.json()
+    pushStore({ stock })          // every page with store: ['stock'] re-renders
+    return 'ok'
+  },
+}
+```
+
+When you own the server entry, `createServer` also returns the handle directly: `const { pushStore } = await createServer(pages, { live: true })`.
+
+- The client connects automatically — only on pages that declare `store: [...]` keys; one EventSource per tab, survives client navigations, reconnects natively.
+- **Broadcast channel: shared data only** (stock counts, announcements, live scores). Never push per-user data — every connected client receives every patch.
+- Views must handle keys that haven't arrived yet: `server.stock ?? '—'`.
+
 ## Multi-brand Sites
 
 Pass `resolveBrand: async (host) => brandConfig` to `createServer`. The result is cached per host for 60 seconds and attached to `ctx.brand`. It is available in `guard`, `server` fetchers, and any `meta` field that is a function.

package/docs/src/pages/server-api.js

@@ -52,6 +52,7 @@ await createServer(entries, options)`, 'js'))}
           ['<code>sitemap</code>', '<code>boolean | { origin }</code>', '<code>false</code>', 'Auto-serve <code>/sitemap.xml</code> + <code>robots.txt</code> from the registered routes. Dynamic <code>:param</code> routes contribute via <code>spec.sitemap</code> enumerators. See <a href="/meta#sitemap">Metadata &amp; SEO</a>.'],
           ['<code>robots</code>', '<code>string | false</code>', 'auto', 'robots.txt behaviour when sitemap is enabled — <code>false</code> disables, a string is served verbatim.'],
           ['<code>redirects</code>', '<code>object</code>', '<code>null</code>', 'Declarative redirect map for legacy URLs — <code>{ \'/old/:slug\': \'/new/:slug\' }</code>, 301 by default. See <a href="/routing#redirects">Routing</a>.'],
+          ['<code>live</code>', '<code>boolean | { path }</code>', '<code>false</code>', 'SSE store-push channel. The returned <code>pushStore(partial)</code> broadcasts store patches; subscribed pages re-render live. See <a href="/store#live">Global Store</a>.'],
           ['<code>onRequest</code>', '<code>function</code>', '<code>undefined</code>', 'Called on every request before routing. Return <code>false</code> to short-circuit Pulse handling.'],
           ['<code>onError</code>', '<code>function</code>', '<code>undefined</code>', 'Called on unhandled errors. Receives <code>(err, req, res)</code>. See <a href="/error-pages">Error Pages</a>.'],
         ]

package/docs/src/pages/store.js

@@ -50,16 +50,15 @@ export default {
 }`, '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>
+      <p><strong>There is no registration step.</strong> <code>pulse dev</code> and <code>pulse start</code> auto-discover <code>pulse.store.js</code> from the project root — the same way pages are discovered from <code>src/pages/</code>. The store is loaded server-side, served to the browser for mutations, validated at startup (bad fetchers fail the boot), and hot-reloaded in dev when you edit it.</p>
+      <p>Only when you run your own server entry do you pass it manually:</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], {
+createServer(pages, {
   port:      3000,
   staticDir: 'public',
-  store,                 // ← register the global store
+  store,                 // ← manual server entry only
 })`, 'js'))}
 
       ${section('using', 'Using store data in a page')}
@@ -163,6 +162,28 @@ export default {
       <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('live', 'Live store push — server-initiated updates')}
+      <p>For data that changes on the <strong>server</strong> — stock levels, live scores, announcements — enable the live channel and broadcast with <code>pushStore</code>. Subscribed pages re-render the moment a patch arrives, with no polling and no client code:</p>
+      ${codeBlock(highlight(`// pulse.config.js — enable the channel
+export default { live: true }`, 'js'))}
+      ${codeBlock(highlight(`// Broadcast from any spec file — e.g. a webhook that updates stock:
+import { pushStore } from '@invisibleloop/pulse'
+
+export default {
+  route: '/hooks/stock',
+  contentType: 'text/plain',
+  state: {},
+  render: async (ctx) => {
+    const { stock } = await ctx.json()
+    pushStore({ stock })          // pages with store: ['stock'] re-render
+    return 'ok'
+  },
+}`, 'js'))}
+      <p>When you own the server entry, <code>createServer</code> also returns the handle directly: <code>const { pushStore } = await createServer(pages, { live: true })</code>.</p>
+      <p>The browser side is automatic: pages that declare <code>store: [...]</code> keys open a single <code>EventSource</code> connection per tab (default endpoint <code>/__pulse/live</code>). The connection survives client-side navigations and reconnects natively after network interruptions. Pages without store keys never connect.</p>
+      ${callout('warning', 'The live channel is a <strong>broadcast</strong> — every connected client receives every patch. Push <strong>shared</strong> data only (stock, announcements, scores). For per-user updates, use page actions with <code>_storeUpdate</code> instead.')}
+      ${callout('note', 'Views must handle keys that haven\'t arrived yet — the first patch may land seconds after page load. Write <code>server.stock ?? \'—\'</code>, not <code>server.stock</code>. The page must also be hydrated (have mutations or actions); purely server-rendered pages have no JavaScript to receive patches.')}
+
       ${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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.19.0
+0.20.1

package/scripts/build.js

@@ -34,7 +34,10 @@ import { extractUsedClasses, purgeCss, minifyCss } from './css-purge.js'
  *     from being shipped to and evaluated in the browser
  *   - avoids bundling errors when server imports use Node-only modules
  */
-const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
+// NOTE: spec.submit is also server-only but must NOT be listed here — the key
+// scanner is line-anchored at any nesting depth, and `submit:` is the most
+// common ACTION name (actions: { submit: {…} }), which would get stripped too.
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render', 'sitemap']
 
 /**
  * Pulse subpath exports that are server-only (use Node built-ins).
@@ -351,17 +354,22 @@ function scanTemplateLiteral(src, pos) {
 
 /**
  * esbuild plugin — strips server-only spec properties before bundling.
- * Only transforms files under src/pages/ to avoid touching runtime/server code.
+ * Transforms files under src/pages/ plus the global store file (pulse.store.js
+ * carries server fetchers that must never reach the browser) — never touches
+ * runtime/server code.
  *
- * @param {string} pagesDir  Absolute path to src/pages/
+ * @param {string} pagesDir         Absolute path to src/pages/
+ * @param {string|null} storePath   Absolute path to pulse.store.js, if it exists
  */
-function createStripServerPlugin(pagesDir) {
+function createStripServerPlugin(pagesDir, storePath = null) {
   return {
     name: 'pulse-strip-server',
     setup(build) {
       build.onLoad({ filter: /\.js$/ }, (args) => {
-        if (!args.path.startsWith(pagesDir + path.sep) &&
-            args.path !== pagesDir.replace(/\/$/, '') + '.js') return undefined
+        const isPage  = args.path.startsWith(pagesDir + path.sep) ||
+                        args.path === pagesDir.replace(/\/$/, '') + '.js'
+        const isStore = storePath && args.path === storePath
+        if (!isPage && !isStore) return undefined
 
         const source   = fs.readFileSync(args.path, 'utf8')
         const stripped = stripServerOnlyImports(stripServerOnlyKeys(source))
@@ -435,6 +443,11 @@ const NAVIGATE_PATH = new URL('../src/runtime/navigate.js', import.meta.url).pat
 
 const PAGES_DIR = path.join(ROOT, 'src', 'pages')
 
+// Global store — bundled into boot files (server fetchers stripped) when present
+const STORE_PATH = fs.existsSync(path.join(ROOT, 'pulse.store.js'))
+  ? path.join(ROOT, 'pulse.store.js')
+  : null
+
 const bootstrapFiles = pages.flatMap(({ filePath }) => {
   // Strip server-only keys/imports to check what's left for the client.
   // Skip specs with no view — these are API routes or raw content specs
@@ -453,15 +466,22 @@ const bootstrapFiles = pages.flatMap(({ filePath }) => {
   const relRuntime    = path.relative(TMP_DIR, RUNTIME_PATH)
   const relNavigate   = path.relative(TMP_DIR, NAVIGATE_PATH)
 
+  // Global store — when pulse.store.js exists, every boot bundle imports it and
+  // passes it to mount() so client store mutations register in production.
+  // The strip plugin removes its server fetchers from the browser bundle;
+  // esbuild's shared-chunk splitting keeps it from being duplicated per page.
+  const storeImport = STORE_PATH ? `\nimport store from '${path.relative(TMP_DIR, STORE_PATH)}'` : ''
+  const mountOpts   = STORE_PATH ? `{ ssr: true, store }` : `{ ssr: true }`
+
   fs.writeFileSync(bootstrapPath, `\
 import spec from '${relSpec}'
 import { mount } from '${relRuntime}'
-import { initNavigation } from '${relNavigate}'
+import { initNavigation } from '${relNavigate}'${storeImport}
 
 const root = document.getElementById('pulse-root')
 if (root && !root.dataset.pulseMounted) {
   root.dataset.pulseMounted = '1'
-  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
+  mount(spec, root, window.__PULSE_SERVER__ || {}, ${mountOpts})
   initNavigation(root, mount)
 }
 
@@ -488,7 +508,7 @@ const result = await esbuild.build({
   metafile:    true,
   sourcemap:   false,
   treeShaking: true,
-  plugins:     [createStripServerPlugin(PAGES_DIR)],
+  plugins:     [createStripServerPlugin(PAGES_DIR, STORE_PATH)],
   define: {
     'process.env.NODE_ENV': '"production"'
   }

package/scripts/strip-server.test.js

@@ -7,7 +7,7 @@
 // Inline the scanner functions (duplicated here to keep test self-contained)
 // ---------------------------------------------------------------------------
 
-const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render', 'sitemap']
 const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
 
 function stripServerOnlyKeys(source) {
@@ -398,5 +398,24 @@ devTest('leaves module-level constants intact',
 
 // ---------------------------------------------------------------------------
 
+console.log('\nStore + new spec fields\n')
+
+test('sitemap enumerator is stripped (server-only)',
+  `export default {\n  route: '/blog/:slug',\n  sitemap: async () => ['/blog/a'],\n  view: () => '',\n}`,
+  `export default {\n  route: '/blog/:slug',\n  view: () => '',\n}`
+)
+
+test('submit is NOT stripped — it collides with the common submit action name',
+  `export default {\n  route: '/x',\n  actions: {\n    submit: {\n      run: async () => 1,\n    },\n  },\n  view: () => '',\n}`,
+  `export default {\n  route: '/x',\n  actions: {\n    submit: {\n      run: async () => 1,\n    },\n  },\n  view: () => '',\n}`
+)
+
+test('store definition: server fetchers stripped, state and mutations survive',
+  `export default {\n  state: { basket: [] },\n  server: {\n    nav: async () => fetchNav(),\n  },\n  mutations: {\n    add: (store, item) => ({ basket: [...store.basket, item] }),\n  },\n}`,
+  `export default {\n  state: { basket: [] },\n  mutations: {\n    add: (store, item) => ({ basket: [...store.basket, item] }),\n  },\n}`
+)
+
+// ---------------------------------------------------------------------------
+
 console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)
 if (fail > 0) process.exit(1)

package/src/agent/guide-server.md

@@ -18,12 +18,10 @@ Only declared keys are saved. Restored values that differ from the spec default
 
 The global store is a shared data layer. Server fetchers run per request; mutations run on the client and broadcast to all subscribed pages without a server round-trip.
 
-**Define the store** in `pulse.store.js`:
+**Define the store** in `pulse.store.js` at the project root — that's the whole setup. The CLI auto-discovers it (like pages in `src/pages/`), loads it server-side, serves it to the browser, and hot-reloads it on edit:
 ```js
 // pulse.store.js
 export default {
-  hydrate: '/pulse.store.js',                   // browser-importable path — required for mutations
-
   state: {                                      // default/fallback values
     user:     null,
     settings: { theme: 'dark', lang: 'en' },
@@ -45,10 +43,10 @@ export default {
 }
 ```
 
-**Register the store** in your server file:
+**No registration step is needed** with `pulse dev` / `pulse start` — `pulse.store.js` is auto-discovered. Only when you call `createServer` yourself do you pass it manually:
 ```js
 import store from './pulse.store.js'
-createServer([...specs], { store })
+createServer([...specs], { store })   // manual server entry only
 ```
 
 **Use store data in a page** — declare `spec.store` with the keys needed. They appear in the view's `server` argument:
@@ -102,6 +100,50 @@ actions: {
 ```
 `_storeUpdate` is stripped from local page state — it is only forwarded to the store. The rest of `onSuccess` merges into the page's own state as normal.
 
+### Live store push — server-initiated updates (SSE)
+
+For data that changes on the **server** (stock levels, live scores, announcements), enable the live channel and broadcast with `pushStore` — subscribed pages re-render without polling or any client code:
+
+```js
+// pulse.config.js — enable the channel (CLI-managed apps)
+export default { live: true }
+```
+
+```js
+// any spec file — broadcast via the module-level import (no server handle needed)
+import { pushStore } from '@invisibleloop/pulse'
+
+export default {
+  route: '/hooks/stock',
+  contentType: 'text/plain',
+  state: {},
+  render: async (ctx) => {
+    const { stock } = await ctx.json()
+    pushStore({ stock })   // every mounted page with store: ['stock'] re-renders
+    return 'ok'
+  },
+}
+```
+
+When you own the server entry, `createServer` also returns the handle: `const { pushStore } = await createServer(pages, { live: true })`.
+
+```js
+// page spec — subscribes like any store key
+export default {
+  route: '/product',
+  store: ['stock'],
+  state: {},
+  mutations: { noop: (s) => s },   // any mutation/action → page is hydrated
+  view: (state, server) => `<p>${server.stock ?? '—'} in stock</p>`,
+}
+```
+
+**Rules:**
+- **Shared data only.** The channel is a broadcast — every connected client receives every patch. Never push per-user data (use page actions + `_storeUpdate` for that).
+- Views must handle keys that haven't arrived yet (`server.stock ?? '—'`) — the first patch may land seconds after page load.
+- The page must be hydrated (have mutations/actions) — purely server-rendered pages have no JS to receive patches.
+- The connection is automatic and lazy: only pages with `store: [...]` keys open it, one EventSource per tab, native auto-reconnect.
+
 ## Server-side forms — `spec.submit` (works without client JS)
 
 A spec with a `submit` handler accepts POST on its own route. The form works with JavaScript disabled — hydrated `actions` become an enhancement, not a requirement.

package/src/cli/cli.test.js

@@ -105,6 +105,59 @@ for (const skill of requiredSkills) {
   })
 }
 
+// ---------------------------------------------------------------------------
+// Store auto-discovery (loadStore)
+// ---------------------------------------------------------------------------
+// Regression: pulse.store.js was documented but never loaded by the CLI —
+// dev/start servers got no store, so spec.store keys were always empty.
+
+console.log('\nStore auto-discovery\n')
+
+{
+  const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const { loadStore } = await import('./discover.js')
+
+  const dir = mkdtempSync(path.join(tmpdir(), 'pulse-store-'))
+  try {
+    // No store file → null
+    const none = await loadStore(dir)
+    test('loadStore returns null when pulse.store.js is absent', () => {
+      if (none !== null) throw new Error(`Expected null, got ${JSON.stringify(none)}`)
+    })
+
+    // Valid store file → definition with browser hydrate path set
+    writeFileSync(path.join(dir, 'pulse.store.js'),
+      `export default { state: { basket: [] }, server: { nav: async () => ['Home'] }, mutations: { add: (s, i) => ({ basket: [...s.basket, i] }) } }`)
+    const def = await loadStore(dir)
+    test('loadStore loads pulse.store.js and sets the browser hydrate path', () => {
+      if (!def)                                     throw new Error('Expected a store definition')
+      if (def.hydrate !== '/pulse.store.js')        throw new Error(`Expected hydrate /pulse.store.js, got ${def.hydrate}`)
+      if (typeof def.server?.nav !== 'function')    throw new Error('server fetchers missing')
+      if (typeof def.mutations?.add !== 'function') throw new Error('mutations missing')
+      if (!Array.isArray(def.state?.basket))        throw new Error('state missing')
+    })
+
+    // Cache-busted re-import returns the edited module (dev hot reload)
+    writeFileSync(path.join(dir, 'pulse.store.js'),
+      `export default { state: { basket: [], promo: true }, mutations: {} }`)
+    const fresh = await loadStore(dir, Date.now())
+    test('loadStore cache-busts for hot reload', () => {
+      if (fresh?.state?.promo !== true) throw new Error('Expected fresh store definition after edit')
+    })
+
+    // Bad export → clear error
+    writeFileSync(path.join(dir, 'pulse.store.js'), `export default 42`)
+    let threw = false
+    try { await loadStore(dir, Date.now() + 1) } catch (e) { threw = /store object/.test(e.message) }
+    test('loadStore throws a clear error for a non-object export', () => {
+      if (!threw) throw new Error('Expected a descriptive throw for bad default export')
+    })
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/cli/dev.js

@@ -11,7 +11,7 @@
 import path    from 'path'
 import fs      from 'fs'
 import { createServer } from '../server/index.js'
-import { loadPages }    from './discover.js'
+import { loadPages, loadStore } from './discover.js'
 import * as log         from './logger.js'
 
 // ---------------------------------------------------------------------------
@@ -109,6 +109,10 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
 
 const specs = await loadPages(ROOT)
 
+// Auto-discover the global store — pulse.store.js in the project root.
+// Mirrors page discovery; no custom server entry needed.
+const store = await loadStore(ROOT)
+
 if (specs.length === 0) {
   log.error('No pages found in src/pages/. Create a page to get started.')
   process.exit(1)
@@ -192,6 +196,9 @@ async function triggerReload(label = 'File changed') {
     try {
       const fresh = await loadPages(ROOT, now)
       updateSpecs(fresh)
+      // Hot-swap the store too — pulse.store.js edits take effect like spec edits
+      const freshStore = await loadStore(ROOT, now)
+      updateStore(freshStore)
       log.info(`${label} — specs reloaded`)
       checkUndefinedClasses(fresh)
     } catch (err) {
@@ -204,6 +211,11 @@ async function triggerReload(label = 'File changed') {
 // Watch src/ for changes to existing files (spec edits, component edits)
 fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => triggerReload('File changed'))
 
+// Watch the store file — it lives in the project root, outside src/
+if (fs.existsSync(path.join(ROOT, 'pulse.store.js'))) {
+  fs.watch(path.join(ROOT, 'pulse.store.js'), () => triggerReload('Store changed'))
+}
+
 // Also watch the pages directory explicitly so macOS reliably fires on new file creation.
 // On macOS, fs.watch with recursive=true watches subdirectory contents but may not fire
 // for the parent dir entry when a brand-new file is created. Watching the dir non-recursively
@@ -227,7 +239,7 @@ const reloadScript = (nonce) => `<script nonce="${nonce}">
   })();
 </script>`
 
-const { updateSpecs } = await createServer(specs, {
+const { updateSpecs, updateStore } = await createServer(specs, {
   port:      PORT,
   stream:    true,
   staticDir: fs.existsSync(PUBLIC_DIR) ? PUBLIC_DIR : null,
@@ -235,7 +247,12 @@ const { updateSpecs } = await createServer(specs, {
   extraBody: reloadScript,
   dev:       true,
   agentMode: !!process.env.PULSE_AGENT_MODE,
+  ...(store ? { store } : {}),
   ...(_config.csp ? { csp: _config.csp } : {}),
+  // Server options forwarded verbatim from pulse.config.js so dev behaves like
+  // production — keep in sync with start.js PASSTHROUGH_OPTIONS
+  ...(['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody'].reduce(
+    (acc, k) => (_config[k] !== undefined ? { ...acc, [k]: _config[k] } : acc), {})),
 
   onRequest(req, res) {
     const url = req.url.split('?')[0]
@@ -281,6 +298,11 @@ const { updateSpecs } = await createServer(specs, {
       return serveFile(filePath)
     }
 
+    // Global store — pulse.store.js lives in the project root (not src/), and the
+    // dev hydrate bootstrap imports it so client store mutations register.
+    // serveFile strips node:/server-only imports, same treatment as page specs.
+    if (url === '/pulse.store.js' && serveFile(path.join(ROOT, 'pulse.store.js'))) return false
+
     // Project source — /src/pages/, /src/components/, /src/lib/, etc.
     // Falls back to framework source for imports like /src/ui/ that sub-projects
     // resolve from relative paths (e.g. docs component pages → ../../../../src/ui/).

package/src/cli/discover.js

@@ -111,3 +111,29 @@ export async function loadPages(projectRoot, bust = 0) {
 
   return specs
 }
+
+/**
+ * Auto-discover the global store definition from pulse.store.js in the
+ * project root. Returns the store definition with `hydrate` set to its
+ * browser-importable path (used by the dev inline bootstrap), or null when
+ * the file doesn't exist.
+ *
+ * Mirrors page auto-discovery: pulse.store.js is the documented filename
+ * convention, so CLI-managed projects (pulse dev / pulse start) get the
+ * store without writing a custom server entry.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+export async function loadStore(projectRoot, cacheBust = null) {
+  const storePath = path.join(projectRoot, 'pulse.store.js')
+  if (!fs.existsSync(storePath)) return null
+
+  const url = 'file://' + storePath + (cacheBust ? `?t=${cacheBust}` : '')
+  const mod = await import(url)
+  const def = mod.default
+  if (!def || typeof def !== 'object') {
+    throw new Error('pulse.store.js must export a default store object ({ state?, server?, mutations? })')
+  }
+  return { ...def, hydrate: def.hydrate || '/pulse.store.js' }
+}

package/src/cli/start.js

@@ -11,7 +11,7 @@
 import path from 'path'
 import fs   from 'fs'
 import { createServer } from '../server/index.js'
-import { loadPages }    from './discover.js'
+import { loadPages, loadStore } from './discover.js'
 
 const args    = process.argv.slice(2)
 const rootArg = args.indexOf('--root')
@@ -44,6 +44,10 @@ if (!fs.existsSync(manifestPath)) {
 let port         = portArg !== -1 ? parseInt(args[portArg + 1], 10) : null
 let defaultCache = null
 let csp          = null
+let passthrough  = {}
+
+// Server options forwarded verbatim from pulse.config.js — keep in sync with dev.js
+const PASSTHROUGH_OPTIONS = ['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody']
 
 const configPath = path.join(ROOT, 'pulse.config.js')
 if (fs.existsSync(configPath)) {
@@ -52,6 +56,9 @@ if (fs.existsSync(configPath)) {
     port         = port || mod.default?.port || null
     defaultCache = mod.default?.defaultCache ?? null
     csp          = mod.default?.csp ?? null
+    for (const key of PASSTHROUGH_OPTIONS) {
+      if (mod.default?.[key] !== undefined) passthrough[key] = mod.default[key]
+    }
   } catch { /* ignore */ }
 }
 
@@ -64,6 +71,9 @@ port = parseInt(process.env.PORT, 10) || port || 3000
 
 const specs = await loadPages(ROOT)
 
+// Auto-discover the global store — pulse.store.js in the project root
+const store = await loadStore(ROOT)
+
 if (specs.length === 0) {
   console.error('No pages found in src/pages/.')
   process.exit(1)
@@ -74,5 +84,7 @@ createServer(specs, {
   stream:       true,
   staticDir:    PUBLIC_DIR,
   defaultCache,
+  ...(store ? { store } : {}),
   ...(csp ? { csp } : {}),
+  ...passthrough,
 })

package/src/runtime/index.js

@@ -7,7 +7,7 @@
  * No framework. No virtual DOM. No dependencies.
  */
 
-import { initClientStore, getStoreState, subscribe, updateStore, registerStoreMutations, dispatchStoreMutation } from './store.js'
+import { initClientStore, getStoreState, subscribe, updateStore, registerStoreMutations, dispatchStoreMutation, initLiveStore } from './store.js'
 import { trustedHTML, trustedScriptURL } from './tt.js'
 
 // Toast is lazy-loaded on first use — pages that never use _toast pay zero bytes
@@ -43,6 +43,13 @@ export function mount(spec, el, serverState = {}, options = {}) {
   // Separate page-level server state from store keys so they can be tracked
   // independently — store values come from the live singleton, not the snapshot.
   const _storeKeys = new Set(spec.store || [])
+
+  // Live store push — connect to the server's SSE channel, but only when this
+  // page actually subscribes to store keys. Singleton: survives navigations,
+  // repeat mounts are no-ops. Pages without store keys never open a connection.
+  if (typeof window !== 'undefined' && window.__PULSE_LIVE__ && _storeKeys.size > 0) {
+    initLiveStore(window.__PULSE_LIVE__)
+  }
   const _pageServerState = {}
   for (const [k, v] of Object.entries(serverState)) {
     if (!_storeKeys.has(k)) _pageServerState[k] = v

package/src/runtime/runtime.test.js

@@ -570,7 +570,7 @@ test('spec without persist does not write to localStorage', () => {
 
 console.log('\nStore mutations\n')
 
-import { registerStoreMutations, dispatchStoreMutation, getStoreState, updateStore } from './store.js'
+import { registerStoreMutations, dispatchStoreMutation, getStoreState, updateStore, initLiveStore } from './store.js'
 
 // Register all mutations once — the singleton ignores subsequent calls (by design)
 registerStoreMutations({
@@ -621,6 +621,35 @@ test('registerStoreMutations is a no-op after first call', () => {
   assert(getStoreState().count === before + 1, `Should still use original mutation, got ${getStoreState().count}`)
 })
 
+console.log('\nLive store push (client)\n')
+
+test('initLiveStore connects once, merges SSE store events, survives bad frames', () => {
+  const instances = []
+  globalThis.EventSource = class {
+    constructor(url) { this.url = url; this._listeners = {}; instances.push(this) }
+    addEventListener(type, fn) { this._listeners[type] = fn }
+  }
+
+  initLiveStore('/__pulse/live')
+  initLiveStore('/__pulse/live')   // singleton — second call is a no-op
+  assert(instances.length === 1, `Expected one EventSource, got ${instances.length}`)
+  assert(instances[0].url === '/__pulse/live', `Wrong URL: ${instances[0].url}`)
+
+  // A store event merges into the client store and notifies subscribers
+  const el = new FakeElement()
+  mount({ route: '/stock', store: ['stock'], state: {}, view: (s, server) => `<b>${server.stock ?? '—'}</b>` }, el, {})
+  instances[0]._listeners.store({ data: JSON.stringify({ stock: 7 }) })
+  assert(getStoreState().stock === 7, `Expected stock 7, got ${getStoreState().stock}`)
+  assert(el.innerHTML.includes('7'), `Subscribed page should re-render: ${el.innerHTML}`)
+
+  // Malformed frames must never throw or break the page
+  instances[0]._listeners.store({ data: 'not-json' })
+  instances[0]._listeners.store({ data: '"a-string"' })
+  assert(getStoreState().stock === 7, 'Bad frames must not corrupt the store')
+
+  delete globalThis.EventSource
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nDebounce / throttle\n')

package/src/runtime/ssr.js

@@ -269,12 +269,15 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
  * read these globals, and omitting the inline script keeps cached HTML nonce-free
  * so it can be served with a nonce-free CSP without a CSP violation.
  */
-export function buildStoreScript(spec, storeState, nonce) {
+export function buildStoreScript(spec, storeState, nonce, livePath = '') {
   if (!spec.hydrate) return ''
+  // __PULSE_LIVE__ tells the runtime where the SSE store-push channel lives;
+  // mount() connects only when the page actually subscribes to store keys.
+  const liveFlag = livePath ? `window.__PULSE_LIVE__='${livePath}';` : ''
   if (storeState && Object.keys(storeState).length > 0) {
-    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';window.__PULSE_STORE__=${JSON.stringify(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
+    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}window.__PULSE_STORE__=${JSON.stringify(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
   }
-  return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';</script>`
+  return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}</script>`
 }
 
 /**
@@ -310,7 +313,7 @@ export function buildHydrateScript(spec, storeDef, nonce) {
  * @param {Object}  [options.timing]     - Server-Timing values
  * @returns {string}
  */
-export function wrapDocument({ content, spec = {}, serverState = {}, storeState = null, storeDef = null, timing = {}, extraBody = '', extraHead = '', nonce = '', runtimeBundle = '', faviconHref = '' }) {
+export function wrapDocument({ content, spec = {}, serverState = {}, storeState = null, storeDef = null, timing = {}, extraBody = '', extraHead = '', nonce = '', runtimeBundle = '', faviconHref = '', livePath = '' }) {
   const meta  = spec.meta  || {}
   const title = meta.title || 'Pulse'
 
@@ -362,7 +365,7 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
     ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(serverState)};</script>`
     : ''
 
-  const storeStateScript = buildStoreScript(spec, storeState, nonce)
+  const storeStateScript = buildStoreScript(spec, storeState, nonce, livePath)
   const hydrateScript    = buildHydrateScript(spec, storeDef, nonce)
 
   // Server-Timing header value (caller is responsible for setting the header)
@@ -628,11 +631,14 @@ function encode(str) {
  * bundle (i.e. resolved via the manifest) rather than a raw source file.
  * Bundles live under /dist/ and carry a content hash in their filename.
  *
- * @param {string} hydratePath
+ * Null-safe: purely server-rendered pages (no mutations/actions/persist) have
+ * no hydrate path at all — they are never bundles.
+ *
+ * @param {string|undefined} hydratePath
  * @returns {boolean}
  */
 function isBundle(hydratePath) {
-  return hydratePath.startsWith('/dist/')
+  return typeof hydratePath === 'string' && hydratePath.startsWith('/dist/')
 }
 
 /**

package/src/runtime/store.js

@@ -73,6 +73,34 @@ export function registerStoreMutations(mutations) {
   _mutationsRegistered = true
 }
 
+// ---------------------------------------------------------------------------
+// Live store push — SSE channel from the server (createServer { live: true })
+// ---------------------------------------------------------------------------
+
+let _liveSource = null
+
+/**
+ * Connect to the server's live store-push channel (SSE). Singleton per tab —
+ * survives client-side navigations; repeat calls are no-ops. Patches arrive as
+ * `store` events and merge via updateStore(), so every page subscribed through
+ * spec.store re-renders immediately. EventSource reconnects automatically.
+ *
+ * Called by mount() only when the page subscribes to store keys and the server
+ * set window.__PULSE_LIVE__ — pages without store keys never open a connection.
+ *
+ * @param {string} url - the SSE endpoint path (e.g. '/__pulse/live')
+ */
+export function initLiveStore(url) {
+  if (_liveSource || typeof EventSource === 'undefined' || !url) return
+  _liveSource = new EventSource(url)
+  _liveSource.addEventListener('store', (e) => {
+    try {
+      const patch = JSON.parse(e.data)
+      if (patch && typeof patch === 'object') updateStore(patch)
+    } catch { /* malformed frame — ignore, never break the page */ }
+  })
+}
+
 /**
  * Dispatch a store mutation by name.
  * The mutation receives the current store state and an optional payload,

package/src/server/index.js

@@ -279,6 +279,29 @@ export class TtlCache {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Module-level pushStore — lets spec files broadcast without a server handle
+// ---------------------------------------------------------------------------
+// Scaffolded apps never call createServer themselves (the CLI owns it), so the
+// broadcast function is also exported at module level. createServer wires it up
+// when `live` is enabled; a webhook spec can then simply:
+//
+//   import { pushStore } from '@invisibleloop/pulse'
+//   export default { route: '/hooks/stock', contentType: 'text/plain',
+//     state: {}, render: async (ctx) => { pushStore(await ctx.json()); return 'ok' } }
+//
+// With multiple servers in one process (tests), the most recent live server
+// wins; use the handle returned by createServer for instance precision.
+
+let _livePushStore = null
+
+export function pushStore(partial) {
+  if (!_livePushStore) {
+    throw new Error('pushStore requires a running server started with live: true (set `live: true` in pulse.config.js or createServer options)')
+  }
+  return _livePushStore(partial)
+}
+
 const serverDataCache = new TtlCache()
 const pageHtmlCache   = new TtlCache()
 
@@ -554,6 +577,11 @@ export async function createServer(entries, options = {}) {
     redirects      = null,          // declarative redirect map for legacy URLs (SEO-safe migrations):
                                     // { '/old-blog/:slug': '/blog/:slug',           — 301 (default)
                                     //   '/promo': { to: '/pricing', status: 302 } } — custom status
+    live           = false,         // true | { path } — SSE store-push channel. createServer returns
+                                    // pushStore(partial): broadcasts a store patch to all connected
+                                    // clients; pages subscribed via spec.store re-render immediately.
+                                    // Broadcast = SHARED data only (stock, announcements), never
+                                    // per-user data. Default path: /__pulse/live
     onError        = (err, req, res) => defaultErrorHandler(err, req, res, dev),
     onRequest,
     agentMode      = false,        // show agent-active indicator in banner
@@ -565,9 +593,13 @@ export async function createServer(entries, options = {}) {
 
   const healthPath = healthCheck === true ? '/healthz' : (healthCheck || null)
 
+  // Store definition — `let` so the dev server can hot-swap it via updateStore()
+  // when pulse.store.js changes, the same way updateSpecs() swaps page specs.
+  let storeDef = store
+
   // Validate store at startup — fail fast before the server accepts connections
-  if (store) {
-    const { valid, errors } = validateStore(store)
+  if (storeDef) {
+    const { valid, errors } = validateStore(storeDef)
     if (!valid) {
       throw new Error(`Invalid Pulse store:\n${errors.map(e => `  — ${e}`).join('\n')}`)
     }
@@ -622,6 +654,39 @@ export async function createServer(entries, options = {}) {
   // tied to a cookie, so a restart only means in-flight forms re-render once.
   const csrfSecret = secret || crypto.randomBytes(32).toString('hex')
 
+  // Live store push — SSE clients and the broadcast function. The heartbeat
+  // comment keeps proxies from reaping idle connections; unref'd so it never
+  // holds the process open.
+  const livePath    = live ? ((typeof live === 'object' && live.path) || '/__pulse/live') : null
+  const liveClients = new Set()
+  const liveHeartbeat = livePath
+    ? setInterval(() => {
+        for (const res of liveClients) { try { res.write(':hb\n\n') } catch {} }
+      }, 25_000).unref()
+    : null
+
+  /**
+   * Broadcast a store patch to every connected live client. Subscribed pages
+   * (spec.store) merge it via updateStore() and re-render immediately.
+   * Returns the number of clients the patch was sent to.
+   */
+  function pushStore(partial) {
+    if (!livePath) throw new Error('pushStore requires createServer option live: true')
+    if (!partial || typeof partial !== 'object' || Array.isArray(partial)) {
+      throw new Error('pushStore(partial) expects a plain object of store keys to merge')
+    }
+    const frame = `event: store\ndata: ${JSON.stringify(partial)}\n\n`
+    let sent = 0
+    for (const res of liveClients) {
+      try { res.write(frame); sent++ } catch { liveClients.delete(res) }
+    }
+    return sent
+  }
+
+  // Wire the module-level pushStore export to this instance — spec files can
+  // `import { pushStore } from '@invisibleloop/pulse'` without a server handle.
+  if (livePath) _livePushStore = pushStore
+
   // Redirects — compile the declarative map once at startup (throws on bad
   // entries) and warn when a redirect source shadows a registered page route.
   const redirectTable = compileRedirects(redirects)
@@ -678,6 +743,22 @@ export async function createServer(entries, options = {}) {
         return
       }
 
+      // Live store push — SSE channel. Clients (the runtime's initLiveStore)
+      // connect here; pushStore() broadcasts store patches down the stream.
+      if (livePath && pathname === livePath && req.method === 'GET') {
+        res.writeHead(200, {
+          'Content-Type':      'text/event-stream',
+          'Cache-Control':     'no-store',
+          'Connection':        'keep-alive',
+          'X-Accel-Buffering': 'no',
+          ...SECURITY_HEADERS,
+        })
+        res.write(':connected\n\n')
+        liveClients.add(res)
+        req.on('close', () => liveClients.delete(res))
+        return
+      }
+
       // Request hook — allows middleware-like behaviour
       if (onRequest) {
         const result = onRequest(req, res)
@@ -820,8 +901,8 @@ export async function createServer(entries, options = {}) {
       // Global store — resolve once per request, attach to ctx before guard/server fetchers.
       // Use global fetcherTimeout for store fetchers; spec-level override applied below.
       ctx.fetcherTimeout = fetcherTimeout ?? null
-      if (store) {
-        ctx.store = await resolveStoreState(store, ctx)
+      if (storeDef) {
+        ctx.store = await resolveStoreState(storeDef, ctx)
       }
 
       const spec = resolveSpec(match.spec, hydrateMap)
@@ -943,11 +1024,11 @@ export async function createServer(entries, options = {}) {
       // string path — they are small, must carry an explicit status, and POST
       // bodies are already consumed.
       if (responseStatus !== 200 || req.method === 'POST') {
-        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath, responseStatus)
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, storeDef, csp, faviconPath, responseStatus, livePath)
       } else if (stream) {
-        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
+        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, storeDef, csp, faviconPath, livePath)
       } else {
-        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp, faviconPath)
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, storeDef, csp, faviconPath, 200, livePath)
       }
 
     } catch (err) {
@@ -998,6 +1079,11 @@ export async function createServer(entries, options = {}) {
     pageHtmlCache.stopEviction()
     brandCache.stopEviction()
 
+    // Close live SSE connections so they can't hold the drain open
+    if (liveHeartbeat) clearInterval(liveHeartbeat)
+    for (const res of [...liveClients]) { try { res.end() } catch {} }
+    liveClients.clear()
+
     // Stop accepting new connections; exit once all connections are closed
     server.close(() => process.exit(0))
 
@@ -1032,10 +1118,19 @@ export async function createServer(entries, options = {}) {
   return {
     server,
     shutdown,
+    pushStore,
     updateSpecs(newSpecs) {
       notFoundSpec = newSpecs.find(s => s.route === '*') || null
       router       = buildRouter(newSpecs.filter(s => s.route !== '*'))
       allSpecs     = newSpecs
+    },
+    /** Swap the store definition at runtime (dev hot reload of pulse.store.js). */
+    updateStore(newStoreDef) {
+      if (newStoreDef) {
+        const { valid, errors } = validateStore(newStoreDef)
+        if (!valid) throw new Error(`Invalid Pulse store:\n${errors.map(e => `  — ${e}`).join('\n')}`)
+      }
+      storeDef = newStoreDef || null
     }
   }
 }
@@ -1113,7 +1208,7 @@ async function handleNavStreamResponse(spec, ctx, req, res) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, status = 200) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, status = 200, livePath = '') {
   const cacheKey = buildCacheKey(spec, ctx)
   // Never cache POST re-renders or non-200 responses (custom 404s) — POST output
   // varies per submission and a cached 404 body would be served with a 200 later.
@@ -1137,7 +1232,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
     const canonicalTag      = canonicalUrl ? `<link rel="canonical" href="${escHtml(canonicalUrl)}">` : ''
     const resolvedSpec      = { ...spec, meta: await resolveMeta(spec.meta, ctx) }
     const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody
-    const wrapped           = wrapDocument({ content, spec: resolvedSpec, serverState, storeState: ctx.store || null, storeDef: store || null, timing, extraBody: resolvedExtraBody, extraHead: (dev ? devImportMap(nonce) + '\n  ' : '') + canonicalTag, nonce, runtimeBundle, faviconHref: faviconPath || '' })
+    const wrapped           = wrapDocument({ content, spec: resolvedSpec, serverState, storeState: ctx.store || null, storeDef: store || null, timing, extraBody: resolvedExtraBody, extraHead: (dev ? devImportMap(nonce) + '\n  ' : '') + canonicalTag, nonce, runtimeBundle, faviconHref: faviconPath || '', livePath })
     html              = wrapped.html
     serverTimingValue = wrapped.serverTimingValue
     if (ttl > 0) pageHtmlCache.set(cacheKey, { html }, ttl)
@@ -1165,7 +1260,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
  * Stream the response — shell first, deferred segments follow.
  * On a page-cache hit, serves the buffered HTML as a string (no streaming needed).
  */
-async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
+async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null, livePath = '') {
   // Serve from in-process page cache when available — skip streaming overhead.
   const cacheKey = buildCacheKey(spec, ctx)
   const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
@@ -1253,7 +1348,7 @@ ${stylePreloads ? stylePreloads + '\n' : ''}${runtimePreload ? runtimePreload +
   const scriptTags    = (meta.scripts || [])
     .map(src => `  <script src="${escHtml(src)}" defer></script>`)
     .join('\n')
-  const storeScript   = buildStoreScript(spec, ctx.store || null, nonce)
+  const storeScript   = buildStoreScript(spec, ctx.store || null, nonce, livePath)
   const hydrateScript = buildHydrateScript(spec, store, nonce)
 
   const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody

package/src/server/server.test.js

@@ -1294,6 +1294,30 @@ await test('without a "*" spec the default 404 still works', async () => {
   })
 })
 
+await test('custom 404 works in production mode (manifest with runtime bundle present)', async () => {
+  // Regression: in production the manifest sets runtimeBundle, which made
+  // wrapDocument call isBundle(spec.hydrate) — undefined for non-hydrated pages
+  // like a typical 404 spec → TypeError → 500 instead of the custom 404.
+  // Dev never hit it because runtimeBundle is '' there.
+  const prodManifest = { _runtime: '/dist/runtime-abcd1234.js' }
+  await withServer([helloSpec, notFoundPageSpec], { stream: true, manifest: prodManifest }, async (port) => {
+    const { status, body } = await get(port, '/nope')
+    assert(status === 404, `Expected 404 in production mode, got ${status}`)
+    assert(body.includes('Custom not found'), `Expected custom 404 content: ${body.slice(0, 200)}`)
+  })
+})
+
+await test('non-hydrated pages render on the buffered path in production mode', async () => {
+  // Same root cause, different surface: stream: false + production manifest
+  // crashed EVERY zero-JS page, not just the 404.
+  const prodManifest = { _runtime: '/dist/runtime-abcd1234.js' }
+  await withServer([helloSpec], { stream: false, manifest: prodManifest }, async (port) => {
+    const { status, body } = await get(port, '/hello')
+    assert(status === 200, `Expected 200, got ${status}`)
+    assert(body.includes('Hello world'), 'Expected page content')
+  })
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nServer-side forms (spec.submit) + CSRF\n')
@@ -1646,6 +1670,138 @@ await test('a failing enumerator does not take down the sitemap', async () => {
 
 // ---------------------------------------------------------------------------
 
+console.log('\nLive store push (SSE)\n')
+
+/** Open an SSE connection and return a handle that accumulates received text. */
+function openSse(port, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ hostname: 'localhost', port, path, headers: { Accept: 'text/event-stream' } }, (res) => {
+      let buf = ''
+      res.on('data', c => { buf += c.toString() })
+      resolve({ status: res.statusCode, headers: res.headers, read: () => buf, destroy: () => req.destroy() })
+    })
+    req.on('error', reject)
+  })
+}
+
+const wait = (ms) => new Promise(r => setTimeout(r, ms))
+
+await test('live: true serves the SSE endpoint', async () => {
+  const port = nextPort++
+  const { server } = await createServer([helloSpec], { port, quiet: true, live: true })
+  try {
+    const sse = await openSse(port, '/__pulse/live')
+    assert(sse.status === 200, `Expected 200, got ${sse.status}`)
+    assert(sse.headers['content-type'].includes('text/event-stream'), `Got ${sse.headers['content-type']}`)
+    await wait(50)
+    assert(sse.read().includes(':connected'), 'Expected connection comment')
+    sse.destroy()
+  } finally {
+    server.closeAllConnections?.()
+    await new Promise(r => server.close(r))
+  }
+})
+
+await test('pushStore broadcasts a patch to all connected clients', async () => {
+  const port = nextPort++
+  const { server, pushStore } = await createServer([helloSpec], { port, quiet: true, live: true })
+  try {
+    const a = await openSse(port, '/__pulse/live')
+    const b = await openSse(port, '/__pulse/live')
+    await wait(50)
+    const sent = pushStore({ stock: 5, banner: 'Sale on now' })
+    assert(sent === 2, `Expected 2 clients, got ${sent}`)
+    await wait(50)
+    for (const sse of [a, b]) {
+      assert(sse.read().includes('event: store'), 'Missing event name')
+      assert(sse.read().includes('"stock":5'), `Missing payload: ${sse.read()}`)
+    }
+    a.destroy(); b.destroy()
+  } finally {
+    server.closeAllConnections?.()
+    await new Promise(r => server.close(r))
+  }
+})
+
+await test('pushStore requires live: true and a plain-object patch', async () => {
+  const port = nextPort++
+  const off = await createServer([helloSpec], { port, quiet: true })
+  try {
+    let threw = false
+    try { off.pushStore({ x: 1 }) } catch { threw = true }
+    assert(threw, 'Expected throw without live: true')
+  } finally {
+    off.server.closeAllConnections?.()
+    await new Promise(r => off.server.close(r))
+  }
+  const port2 = nextPort++
+  const on = await createServer([helloSpec], { port: port2, quiet: true, live: true })
+  try {
+    let threw = false
+    try { on.pushStore('not-an-object') } catch { threw = true }
+    assert(threw, 'Expected throw for non-object patch')
+  } finally {
+    on.server.closeAllConnections?.()
+    await new Promise(r => on.server.close(r))
+  }
+})
+
+await test('module-level pushStore export reaches the live server (spec-file usage)', async () => {
+  const { pushStore: globalPush } = await import('./index.js')
+  const port = nextPort++
+  const { server } = await createServer([helloSpec], { port, quiet: true, live: true })
+  try {
+    const sse = await openSse(port, '/__pulse/live')
+    await wait(50)
+    const sent = globalPush({ score: 99 })
+    assert(sent === 1, `Expected module-level pushStore to reach 1 client, got ${sent}`)
+    await wait(50)
+    assert(sse.read().includes('"score":99'), `Missing payload via module export: ${sse.read()}`)
+    sse.destroy()
+  } finally {
+    server.closeAllConnections?.()
+    await new Promise(r => server.close(r))
+  }
+})
+
+await test('endpoint is 404 when live is not enabled', async () => {
+  await withServer([helloSpec], { stream: false }, async (port) => {
+    const { status } = await get(port, '/__pulse/live')
+    assert(status === 404, `Expected 404, got ${status}`)
+  })
+})
+
+await test('custom endpoint path via { path }', async () => {
+  const port = nextPort++
+  const { server } = await createServer([helloSpec], { port, quiet: true, live: { path: '/_realtime' } })
+  try {
+    const sse = await openSse(port, '/_realtime')
+    assert(sse.status === 200, `Expected 200 on custom path, got ${sse.status}`)
+    sse.destroy()
+  } finally {
+    server.closeAllConnections?.()
+    await new Promise(r => server.close(r))
+  }
+})
+
+await test('hydrated pages receive the __PULSE_LIVE__ flag; disabled servers do not', async () => {
+  const hydrated = {
+    route: '/live-page', hydrate: '/src/pages/live-page.js', store: ['stock'],
+    state: { n: 0 }, mutations: { inc: (s) => ({ n: s.n + 1 }) },
+    view: (state, server) => `<main id="main-content">${server.stock ?? '—'}</main>`,
+  }
+  await withServer([hydrated], { stream: false, live: true }, async (port) => {
+    const { body } = await get(port, '/live-page')
+    assert(body.includes(`window.__PULSE_LIVE__='/__pulse/live'`), `Flag missing: ${body.slice(0, 600)}`)
+  })
+  await withServer([hydrated], { stream: false }, async (port) => {
+    const { body } = await get(port, '/live-page')
+    assert(!body.includes('__PULSE_LIVE__'), 'Flag must be absent when live is disabled')
+  })
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nMalformed request handling\n')
 
 await test('malformed percent-encoding in path returns 404, not 500', async () => {

package/types/server.d.ts

@@ -108,6 +108,15 @@ export interface ServerOptions {
    */
   redirects?: Record<string, string | { to: string; status?: 301 | 302 | 307 | 308 }> | null
 
+  /**
+   * Enable the SSE store-push channel. createServer's return value gains a
+   * working pushStore(partial) that broadcasts store patches to all connected
+   * clients; pages subscribed via spec.store re-render immediately. Pass
+   * { path } to move the endpoint (default '/__pulse/live'). The channel is a
+   * broadcast — push SHARED data only (stock, announcements), never per-user data.
+   */
+  live?: boolean | { path?: string }
+
   /**
    * Extra CSP sources to merge into the framework's default Content-Security-Policy.
    * Use this to allow external stylesheets, fonts, or API origins.
@@ -140,6 +149,16 @@ export interface PulseStoreDefinition {
 // createServer return value
 // ---------------------------------------------------------------------------
 
+/**
+ * Module-level broadcast to the running live server — for spec files that have
+ * no server handle (the CLI owns createServer in scaffolded apps).
+ * Throws unless a server with `live: true` is running.
+ * @example
+ * import { pushStore } from '@invisibleloop/pulse'
+ * pushStore({ stock: 5 })
+ */
+export declare function pushStore(partial: Record<string, unknown>): number
+
 export interface ServerInstance {
   /** The underlying Node.js http.Server */
   server: Server
@@ -155,6 +174,18 @@ export interface ServerInstance {
 
   /** Swap the spec list at runtime (used by the dev server for hot reload). */
   updateSpecs(specs: PulseSpec[]): void
+
+  /** Swap the store definition at runtime (dev hot reload of pulse.store.js). Validates; throws on a bad definition. */
+  updateStore(storeDef: PulseStoreDefinition | null): void
+
+  /**
+   * Broadcast a store patch to every connected live client (requires the
+   * `live` option). Pages subscribed via spec.store merge the patch and
+   * re-render immediately. Returns the number of clients reached.
+   * Broadcast channel — push SHARED data only, never per-user data.
+   * @example pushStore({ stock: 5 })
+   */
+  pushStore(partial: Record<string, unknown>): number
 }
 
 // ---------------------------------------------------------------------------