@invisibleloop/pulse 0.19.0 → 0.20.0

package/CLAUDE.md

@@ -298,6 +298,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 +316,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

@@ -163,6 +163,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.0",
   "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.0

package/src/agent/guide-server.md

@@ -102,6 +102,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/dev.js

@@ -236,6 +236,10 @@ const { updateSpecs } = await createServer(specs, {
   dev:       true,
   agentMode: !!process.env.PULSE_AGENT_MODE,
   ...(_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]

package/src/cli/start.js

@@ -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 */ }
 }
 
@@ -75,4 +82,5 @@ createServer(specs, {
   staticDir:    PUBLIC_DIR,
   defaultCache,
   ...(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)

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
@@ -622,6 +650,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 +739,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)
@@ -943,11 +1020,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, store, 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, store, 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, store, csp, faviconPath, 200, livePath)
       }
 
     } catch (err) {
@@ -998,6 +1075,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,6 +1114,7 @@ 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 !== '*'))
@@ -1113,7 +1196,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 +1220,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 +1248,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 +1336,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

@@ -1646,6 +1646,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,15 @@ export interface ServerInstance {
 
   /** Swap the spec list at runtime (used by the dev server for hot reload). */
   updateSpecs(specs: PulseSpec[]): 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
 }
 
 // ---------------------------------------------------------------------------