@invisibleloop/pulse 0.18.2 → 0.20.0

package/CLAUDE.md

@@ -294,6 +294,12 @@ await createServer(
                                   // dynamic :param routes contribute via spec.sitemap enumerators;
                                   // a physical sitemap.xml/robots.txt in staticDir always wins
     robots:       null,           // robots.txt when sitemap on: null = auto, false = off, string = verbatim
+    redirects: {                  // declarative redirects for legacy URLs — 301 by default,
+      '/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'],
@@ -310,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/routing.js

@@ -79,6 +79,19 @@ server: {
   },
 }`, 'js'))}
 
+      ${section('redirects', 'Redirects')}
+      <p>Migrating an existing site? Preserve the old URLs with the <code>redirects</code> map — legacy links and search rankings survive the move:</p>
+      ${codeBlock(highlight(`await createServer(pages, {
+  redirects: {
+    '/old-blog/:slug': '/blog/:slug',                 // 301 — :params carry over
+    '/pricing-2024':   '/pricing',                    // 301 (default)
+    '/promo':          { to: '/sale', status: 302 },  // temporary redirect
+    '/moved/:slug':    'https://other.com/:slug',     // absolute targets for domain moves
+  },
+})`, 'js'))}
+      <p>Redirects respond <strong>301</strong> by default (permanent — search engines transfer ranking to the target). Use <code>{ to, status }</code> for <code>302</code>, <code>307</code>, or <code>308</code>. The query string is preserved, redirects apply to GET/HEAD only, and the map is validated at startup — a bad entry fails the boot rather than silently misrouting traffic.</p>
+      ${callout('note', 'Redirects are checked before route matching, so a redirect source that equals a registered route shadows the page — the server logs a startup warning when that happens. Occasionally intentional (retiring a page), usually a mistake.')}
+
       ${section('not-found', '404 handling')}
       <p>If no spec matches the incoming request path, Pulse returns a 404. To customise it, create a spec with <code>route: '*'</code> — it renders through the normal pipeline (layout, styles, components) with status 404:</p>
       ${codeBlock(highlight(`export default {

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

@@ -51,6 +51,8 @@ await createServer(entries, options)`, 'js'))}
           ['<code>secret</code>', '<code>string</code>', 'random per boot', 'HMAC secret for CSRF tokens (<a href="/forms">Forms</a>). Set a stable value when running multiple instances so tokens issued by one validate on another.'],
           ['<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.18.2",
+  "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.18.2
+0.20.0

package/src/agent/guide-routing.md

@@ -147,6 +147,25 @@ export default {
 - **Every site should have one** — without it, visitors to a bad URL get the framework's unbranded default 404.
 - 500 errors are customised via `createServer`'s `onError` option, not a spec.
 
+## Declarative redirects (legacy URLs)
+
+When migrating an existing site to Pulse, preserve the old URLs with the `redirects` map in `pulse.config.js` / `createServer` — never let legacy URLs 404:
+
+```js
+export default {
+  redirects: {
+    '/old-blog/:slug': '/blog/:slug',             // 301 — :params carry over
+    '/pricing-2024':   '/pricing',                // 301
+    '/promo':          { to: '/sale', status: 302 },  // temporary
+    '/moved/:slug':    'https://other.com/:slug', // absolute targets for domain moves
+  },
+}
+```
+
+- **301 by default** (permanent — search engines transfer ranking). Use `{ to, status }` for 302/307/308.
+- Query strings are preserved; checked before route matching (GET/HEAD only); validated at startup — bad entries fail the boot.
+- A redirect source that equals a registered route shadows the page (startup warning) — that is sometimes intentional (retiring a page), usually a mistake.
+
 ## Sitemap & robots.txt
 
 Enable in `pulse.config.js` / `createServer` — the framework serves `/sitemap.xml` and `/robots.txt` generated from the registered routes:

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()
 
@@ -551,6 +574,14 @@ export async function createServer(entries, options = {}) {
                                     // spec.sitemap = async () => ['/blog/a', ...]
     robots         = null,          // robots.txt content when sitemap is enabled:
                                     // null = auto-generate, false = disable, string = serve verbatim
+    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
@@ -619,6 +650,49 @@ 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)
+  if (redirectTable.length > 0 && !quiet) {
+    const shadowed = redirectTable.filter(r => specs.some(s => s.route === r.source))
+    if (shadowed.length > 0) {
+      console.log(`  ⚠ redirects: ${shadowed.map(r => r.source).join(', ')} also match registered page routes — the redirect wins and the page is unreachable`)
+    }
+  }
+
   // Sitemap — track the live spec list (updated on hot reload) and surface a
   // startup hint for dynamic routes that can't be enumerated automatically.
   const sitemapEnabled = !!sitemap
@@ -665,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)
@@ -727,6 +817,27 @@ export async function createServer(entries, options = {}) {
         // 'allow' — no redirect
       }
 
+      // Declarative redirects — checked before route matching so legacy URLs
+      // redirect even when a spec also matches (a startup warning flags that).
+      // GET/HEAD only: redirecting a POST silently drops the body.
+      if (redirectTable.length > 0 && (req.method === 'GET' || req.method === 'HEAD')) {
+        for (const r of redirectTable) {
+          const m = pathname.match(r.pattern)
+          if (!m) continue
+          // Substitute captured :params into the target, keeping their original
+          // percent-encoding intact (no decode/re-encode round trip). Longest
+          // names first so :s never clobbers part of :slug.
+          let target = r.target
+          ;[...r.params.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .forEach(([i, name]) => { target = target.split(`:${name}`).join(m[i + 1]) })
+          if (target === pathname) break  // self-redirect — fall through to normal routing
+          res.writeHead(r.status, { Location: target + (url.search || ''), ...SECURITY_HEADERS, ...httpsHeaders(req) })
+          res.end()
+          return
+        }
+      }
+
       // Match route
       let match          = matchRoute(router, pathname)
       let responseStatus = 200
@@ -909,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) {
@@ -964,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))
 
@@ -998,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 !== '*'))
@@ -1079,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.
@@ -1103,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)
@@ -1131,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
@@ -1219,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
@@ -1724,6 +1841,47 @@ function escHtml(str) {
     .replace(/'/g, '&#39;')
 }
 
+/**
+ * Compile the declarative redirects map into matchable entries.
+ * Validates at startup — a bad entry throws before the server accepts connections.
+ *
+ * Sources are route patterns ('/old/:slug'); targets are paths or absolute URLs
+ * and may reference the same :params. Values are a target string (301) or
+ * { to, status } for 302/307/308.
+ *
+ * @param {Record<string, string | { to: string, status?: number }> | null} redirects
+ * @returns {Array<{ source: string, pattern: RegExp, params: string[], target: string, status: number }>}
+ */
+function compileRedirects(redirects) {
+  if (!redirects) return []
+  const VALID_STATUS = new Set([301, 302, 307, 308])
+  const table = []
+
+  for (const [source, value] of Object.entries(redirects)) {
+    if (!source.startsWith('/')) {
+      throw new Error(`Invalid redirect source "${source}" — sources must start with "/" (e.g. '/old-blog/:slug')`)
+    }
+    const target = typeof value === 'string' ? value : value?.to
+    const status = typeof value === 'string' ? 301 : (value?.status ?? 301)
+    if (typeof target !== 'string' || !(target.startsWith('/') || /^https?:\/\//.test(target))) {
+      throw new Error(`Invalid redirect target for "${source}" — targets must start with "/" or be an absolute http(s) URL`)
+    }
+    if (!VALID_STATUS.has(status)) {
+      throw new Error(`Invalid redirect status ${status} for "${source}" — use 301, 302, 307, or 308`)
+    }
+    // Targets may only reference params that the source captures
+    const { pattern, params } = routeToRegex(source)
+    const targetParams = [...target.matchAll(/:([a-zA-Z][\w-]*)/g)].map(m => m[1])
+    const unknown = targetParams.filter(p => !params.includes(p))
+    if (unknown.length > 0) {
+      throw new Error(`Redirect target for "${source}" references :${unknown[0]} which the source does not capture`)
+    }
+    table.push({ source, pattern, params, target, status })
+  }
+
+  return table
+}
+
 /**
  * Collect sitemap entries from the registered specs.
  *

package/src/server/server.test.js

@@ -1446,6 +1446,92 @@ await test('submit pages are excluded from the in-process page cache', async ()
 
 // ---------------------------------------------------------------------------
 
+console.log('\nDeclarative redirects\n')
+
+await test('plain redirect responds 301 with Location', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-hello': '/hello' } }, async (port) => {
+    const { status, headers } = await get(port, '/old-hello')
+    assert(status === 301, `Expected 301, got ${status}`)
+    assert(headers.location === '/hello', `Expected /hello, got ${headers.location}`)
+  })
+})
+
+await test(':params are substituted into the target', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-blog/:slug': '/blog/:slug' } }, async (port) => {
+    const { status, headers } = await get(port, '/old-blog/my-post')
+    assert(status === 301)
+    assert(headers.location === '/blog/my-post', `Expected /blog/my-post, got ${headers.location}`)
+  })
+})
+
+await test('percent-encoded params keep their encoding through substitution', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old/:slug': '/new/:slug' } }, async (port) => {
+    const { headers } = await get(port, '/old/caf%C3%A9')
+    assert(headers.location === '/new/caf%C3%A9', `Encoding mangled: ${headers.location}`)
+  })
+})
+
+await test('query string is preserved on redirect', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-hello': '/hello' } }, async (port) => {
+    const { headers } = await get(port, '/old-hello?utm=x&page=2')
+    assert(headers.location === '/hello?utm=x&page=2', `Query lost: ${headers.location}`)
+  })
+})
+
+await test('custom status via { to, status }', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/promo': { to: '/hello', status: 302 } } }, async (port) => {
+    const { status, headers } = await get(port, '/promo')
+    assert(status === 302, `Expected 302, got ${status}`)
+    assert(headers.location === '/hello')
+  })
+})
+
+await test('absolute URL targets work (domain moves)', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/moved/:slug': 'https://newsite.com/blog/:slug' } }, async (port) => {
+    const { headers } = await get(port, '/moved/post-1')
+    assert(headers.location === 'https://newsite.com/blog/post-1', `Got ${headers.location}`)
+  })
+})
+
+await test('redirect wins over a registered route at the same path', async () => {
+  await withServer([helloSpec], { stream: false, quiet: true, redirects: { '/hello': '/elsewhere' } }, async (port) => {
+    const { status, headers } = await get(port, '/hello')
+    assert(status === 301 && headers.location === '/elsewhere', `Expected redirect to win, got ${status}`)
+  })
+})
+
+await test('POST is not redirected', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/old-api': '/hello' } }, async (port) => {
+    const { status } = await requestFull(port, 'POST', '/old-api', {})
+    assert(status === 404, `Expected POST to skip redirects (404), got ${status}`)
+  })
+})
+
+await test('self-redirects fall through to normal routing instead of looping', async () => {
+  await withServer([helloSpec], { stream: false, redirects: { '/hello/:x': '/hello/:x' } }, async (port) => {
+    const { status } = await get(port, '/hello/abc')
+    assert(status === 404, `Expected fall-through to routing (404 here), got ${status}`)
+    const ok = await get(port, '/hello')
+    assert(ok.status === 200, 'Unrelated routes unaffected')
+  })
+})
+
+await test('invalid redirect config throws at startup', async () => {
+  const cases = [
+    { redirects: { 'no-slash': '/x' } },
+    { redirects: { '/x': 'no-slash-target' } },
+    { redirects: { '/x': { to: '/y', status: 418 } } },
+    { redirects: { '/x': '/y/:missing' } },
+  ]
+  for (const opts of cases) {
+    let threw = false
+    try { await createServer([helloSpec], { ...opts, port: nextPort++, quiet: true }) } catch { threw = true }
+    assert(threw, `Expected startup throw for ${JSON.stringify(opts.redirects)}`)
+  }
+})
+
+// ---------------------------------------------------------------------------
+
 console.log('\nSitemap + robots.txt\n')
 
 const aboutSpec   = { route: '/about', view: () => '<main id="main-content">About</main>' }
@@ -1560,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

@@ -94,6 +94,29 @@ export interface ServerOptions {
    */
   robots?: string | false | null
 
+  /**
+   * Declarative redirect map for legacy URLs (SEO-safe migrations).
+   * Sources are route patterns; targets are paths or absolute URLs and may
+   * reference the same :params. A string target redirects with 301; use
+   * { to, status } for 302/307/308. Checked before route matching (GET/HEAD
+   * only); the query string is preserved. Validated at startup.
+   * @example
+   * redirects: {
+   *   '/old-blog/:slug': '/blog/:slug',
+   *   '/promo':          { to: '/pricing', status: 302 },
+   * }
+   */
+  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.
@@ -126,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
@@ -141,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
 }
 
 // ---------------------------------------------------------------------------