@invisibleloop/pulse 0.20.9 → 0.20.11

package/docs/public/pulse-ui.css

@@ -1719,14 +1719,14 @@ hr.ui-divider {
 .ui-code-window-filename {
   font-size:   .75rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: .35rem;
 }
 
 .ui-code-window-lang {
   font-size:   .7rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: auto;
 }
 

package/docs/public/theme.css

@@ -24,22 +24,22 @@
   --border-subtle: #ece7d9;
   --text:          var(--brut-ink);
   --muted:         var(--brut-muted);
-  --muted-2:       #8a8272;
-  --accent:        var(--brut-gold-deep);
+  --muted-2:       #736b5c;
+  --accent:        #8a6300;
   --accent-text:   var(--brut-ink);
-  --accent-hover:  #a97f00;
+  --accent-hover:  #7a5700;
   --accent-dim:    rgba(201, 151, 0, 0.12);
   --green:         #166534;
   --red:           #b91c1c;
 
   /* Syntax tokens — dark-on-light, tuned for contrast on --surface-2 */
   --tok-kw:    #7c3aed;
-  --tok-str:   #15803d;
-  --tok-cmt:   #78716c;
-  --tok-num:   #c2410c;
+  --tok-str:   #166534;
+  --tok-cmt:   #5c574f;
+  --tok-num:   #9a3412;
   --tok-fn:    #1d4ed8;
-  --tok-prop:  #a16207;
-  --tok-op:    #0891b2;
+  --tok-prop:  #854d0e;
+  --tok-op:    #0e6280;
   --tok-punct: #57534e;
 
   /* Sticky header background — replaces the hardcoded rgba(13,13,16,.9) */

package/docs/src/pages/home.js

@@ -56,7 +56,12 @@ export default {
     title: 'Pulse — The spec-first web framework',
     description: 'Pulse is a server-first Node.js framework with zero runtime dependencies. One spec object per page: server data, state, mutations, and view in plain JS. Streaming SSR, security headers, and production caching are enforced by the architecture.',
     theme: 'light',
-    styles: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800;900&display=swap', '/pulse-ui.css', '/theme.css', '/docs.css', '/home-brut.css'],
+    styles: ['/pulse-ui.css', '/theme.css', '/docs.css', '/home-brut.css'],
+    // Loaded via JS after initial parse — non-render-blocking. The preconnect
+    // hints below still warm the connection up early, and display=swap in the
+    // URL means the browser paints with a fallback font immediately and swaps
+    // to Inter once it arrives, so there's no invisible-text window either way.
+    deferredStyles: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800;900&display=swap'],
     schema: {
       '@context': 'https://schema.org',
       '@type': 'SoftwareApplication',

package/docs/src/pages/templates.js

@@ -13,20 +13,26 @@ function esc(s) {
 }
 
 function statPill(label, value) {
-  return `<span style="display:inline-flex;align-items:center;gap:0.3rem;padding:0.2rem 0.6rem;border-radius:999px;font-size:0.72rem;font-weight:500;background:rgba(255,255,255,0.06);border:1px solid rgba(255,255,255,0.1);color:rgba(255,255,255,0.55)">
-    <span style="color:#7c3aed">●</span> ${esc(label)}: <strong style="color:rgba(255,255,255,0.85);font-weight:600">${esc(String(value))}</strong>
+  return `<span style="display:inline-flex;align-items:center;gap:0.3rem;padding:0.2rem 0.6rem;border-radius:999px;font-size:0.72rem;font-weight:500;background:rgba(255,255,255,0.08);border:1px solid rgba(255,255,255,0.14);color:rgba(255,255,255,0.7)">
+    <span style="color:#a78bfa">●</span> ${esc(label)}: <strong style="color:#fff;font-weight:600">${esc(String(value))}</strong>
   </span>`
 }
 
 function templateCard({ name, route, description, tags = [], stats = {}, preview = '' }) {
   const tagHtml = tags.map(t =>
-    `<span style="display:inline-block;padding:0.2rem 0.6rem;background:rgba(255,255,255,0.07);border:1px solid rgba(255,255,255,0.12);border-radius:4px;font-size:0.72rem;font-weight:500;color:rgba(255,255,255,0.55)">${esc(t)}</span>`
+    `<span style="display:inline-block;padding:0.2rem 0.6rem;background:rgba(255,255,255,0.1);border:1px solid rgba(255,255,255,0.16);border-radius:4px;font-size:0.72rem;font-weight:500;color:rgba(255,255,255,0.7)">${esc(t)}</span>`
   ).join('')
 
   const statHtml = Object.entries(stats).map(([k, v]) => statPill(k, v)).join('')
 
+  // This card is a deliberately dark, self-contained surface (macOS-style
+  // preview window + dark body) regardless of the page's own theme — it
+  // mirrors the code-window pattern elsewhere. Uses a real dark background
+  // (not a translucent white tint over the page background), so it reads
+  // correctly on both the light and dark docs themes and keeps the
+  // white-tinted text/borders it was designed with at proper contrast.
   return `
-    <div style="border:1px solid rgba(255,255,255,0.1);border-radius:0.875rem;overflow:hidden;display:flex;flex-direction:column;background:rgba(255,255,255,0.03)">
+    <div style="border:1px solid rgba(255,255,255,0.1);border-radius:0.875rem;overflow:hidden;display:flex;flex-direction:column;background:#171512">
 
       <a href="${esc(route)}" aria-label="Open ${esc(name)} template" style="display:block;background:#0d0d12;border-bottom:1px solid rgba(255,255,255,0.08);text-decoration:none;overflow:hidden">
         <div style="padding:0.5rem 0.75rem;background:#16161e;display:flex;align-items:center;gap:0.375rem;border-bottom:1px solid rgba(255,255,255,0.06)">
@@ -40,13 +46,13 @@ function templateCard({ name, route, description, tags = [], stats = {}, preview
         </div>
       </a>
 
-      <div style="padding:1.25rem 1.25rem 1rem;flex:1;display:flex;flex-direction:column;gap:0.875rem">
+      <div style="padding:1.25rem 1.25rem 1rem;flex:1;display:flex;flex-direction:column;gap:0.875rem;color:#fff">
         <div>
           <div style="display:flex;flex-wrap:wrap;align-items:center;gap:0.5rem;margin-bottom:0.5rem">
-            <h2 style="margin:0;font-size:1rem;font-weight:700;line-height:1.3">${esc(name)}</h2>
+            <h2 style="margin:0;font-size:1rem;font-weight:700;line-height:1.3;color:#fff">${esc(name)}</h2>
             ${tagHtml}
           </div>
-          <p style="margin:0;font-size:0.85rem;line-height:1.6;opacity:0.65">${esc(description)}</p>
+          <p style="margin:0;font-size:0.85rem;line-height:1.6;color:rgba(255,255,255,0.7)">${esc(description)}</p>
         </div>
         <div style="display:flex;flex-wrap:wrap;gap:0.3rem;padding-top:0.625rem;border-top:1px solid rgba(255,255,255,0.08)">${statHtml}</div>
       </div>

package/examples/public/pulse-ui.css

@@ -1719,14 +1719,14 @@ hr.ui-divider {
 .ui-code-window-filename {
   font-size:   .75rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: .35rem;
 }
 
 .ui-code-window-lang {
   font-size:   .7rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: auto;
 }
 

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.9
+0.20.11

package/public/pulse-ui.css

@@ -1719,14 +1719,14 @@ hr.ui-divider {
 .ui-code-window-filename {
   font-size:   .75rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: .35rem;
 }
 
 .ui-code-window-lang {
   font-size:   .7rem;
   font-family: var(--ui-mono);
-  color:       #9898b2;
+  color:       var(--ui-muted);
   margin-left: auto;
 }
 

package/scripts/build.js

@@ -502,7 +502,7 @@ const result = await esbuild.build({
   platform:    'browser',
   outdir:      OUT_DIR,
   entryNames:  '[name]-[hash]',
-  chunkNames:  'runtime-[hash]',
+  chunkNames:  'chunk-[hash]',
   splitting:   true,
   minify:      true,
   metafile:    true,
@@ -520,13 +520,25 @@ const result = await esbuild.build({
 
 const manifest = {}
 
+// Identify the real Pulse framework runtime chunk (the one containing mount())
+// by which auto-split chunks actually import RUNTIME_PATH — not by filename
+// prefix, since chunkNames now applies to every generic shared chunk esbuild
+// splits out (app-level shared code included), not just the framework runtime.
+const RUNTIME_ABS = path.resolve(RUNTIME_PATH)
+const realRuntimeChunk = Object.entries(result.metafile.outputs).find(([outFile, meta]) => {
+  if (meta.entryPoint) return false
+  // meta.inputs keys are relative to process.cwd() — resolve to compare reliably
+  return Object.keys(meta.inputs).some(input => path.resolve(input) === RUNTIME_ABS)
+})?.[0]
+
 for (const [outFile, meta] of Object.entries(result.metafile.outputs)) {
   // outFile is relative to process.cwd(), not ROOT — use path.resolve to get the
   // true absolute path before computing the URL-relative bundle path.
   const bundlePath = '/' + path.relative(path.join(ROOT, 'public'), path.resolve(outFile))
 
-  // Shared runtime chunk — esbuild generates this via splitting, no entryPoint
-  if (!meta.entryPoint && path.basename(outFile).startsWith('runtime-')) {
+  // Shared runtime chunk — esbuild generates this via splitting, no entryPoint.
+  // Identified by containing the actual runtime/index.js source, not by name.
+  if (!meta.entryPoint && outFile === realRuntimeChunk) {
     manifest['_runtime'] = bundlePath
     continue
   }

package/src/runtime/index.js

@@ -7,12 +7,28 @@
  * No framework. No virtual DOM. No dependencies.
  */
 
-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
 const showToast = (opts) => import('./toast.js').then(m => m.showToast(opts))
 
+// store.js is lazy-loaded only by pages that declare spec.store — pages that
+// never subscribe to the global store pay zero bytes for it (same pattern as
+// showToast above). updateStore is needed synchronously inside runAction()
+// for _storeUpdate (any page can push to the store from an action, even one
+// that doesn't itself subscribe), so it is loaded the same lazy way on first
+// use and cached in _storeModule for subsequent calls.
+let _storeModule = null
+const loadStore = () => _storeModule
+  ? Promise.resolve(_storeModule)
+  : import('./store.js').then(m => { _storeModule = m; return m })
+
+// data-store-event is wired via event delegation at bindEvents() time, before
+// spec.store is known to be involved (a page can carry a data-store-event
+// button without declaring spec.store itself) — load store.js on first fire.
+const dispatchStoreMutationLazy = (name, payload) =>
+  loadStore().then(({ dispatchStoreMutation }) => dispatchStoreMutation(name, payload))
+
 // ---------------------------------------------------------------------------
 // Mount
 // ---------------------------------------------------------------------------
@@ -29,37 +45,85 @@ export function mount(spec, el, serverState = {}, options = {}) {
     throw new Error('[Pulse] mount: spec must have a view')
   }
   // Spec is validated server-side at startup — no need to re-validate in the browser
-  // Initialise the client store from SSR data (no-op after the first page mount).
-  // window.__PULSE_STORE__ is serialised by the server when a store is registered.
-  if (typeof window !== 'undefined') {
-    initClientStore(window.__PULSE_STORE__ || {})
-    // Register store mutations so data-store-event bindings can dispatch them.
-    // No-op on subsequent mounts — mutations persist across client navigations.
-    if (options.store?.mutations) {
-      registerStoreMutations(options.store.mutations)
-    }
-  }
-
   // 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__)
+  // store.js (initClientStore, registerStoreMutations, subscribe, initLiveStore,
+  // getStoreState, updateStore, dispatchStoreMutation) is lazy-loaded — only pages
+  // that actually touch the store pay for it. Two independent triggers load it:
+  //   1. spec.store is non-empty (this page reads store data / needs live reactivity)
+  //   2. a data-store-event fires, or an action returns _storeUpdate (this page
+  //      pushes to the store without necessarily subscribing to it)
+  // Both paths funnel through loadStore(), which caches the resolved module so a
+  // second trigger on the same page is a no-op re-await, not a second fetch.
+  //
+  // initClientStore is safe to defer: it is only ever read via getStoreState(),
+  // which is only called from getEffectiveServerState() below, itself gated on
+  // _storeKeys.size — so a page with no spec.store never needs the store singleton
+  // initialised at all. window.__PULSE_STORE__ is also re-serialised fresh by the
+  // server on every navigation (see ssr.js buildStoreScript / navigate.js's
+  // window.__updatePulseStore__), so there is no cross-navigation dependency on an
+  // eager initClientStore call from a page that didn't declare spec.store.
+  // Populated once store.js resolves and this page subscribes — destroy() reads
+  // it at call time, so a destroy() that races the import still unsubscribes
+  // correctly (it just runs the .then() below first, since both are microtasks
+  // queued off the same import; destroy() itself is only ever called later, from
+  // user code or client navigation, well after mount() has returned).
+  let _unsubStore = null
+  let _destroyed  = false
+
+  // NOTE: subscribe() below is intentionally not gated on `typeof window` — this
+  // matches the pre-lazy behaviour, where store subscription worked in any
+  // environment (including Node test environments with no `window` global) as
+  // long as spec.store was non-empty. Only the window-derived inputs
+  // (window.__PULSE_STORE__, window.__PULSE_LIVE__) are individually guarded.
+  if (_storeKeys.size > 0) {
+    loadStore().then(({ initClientStore, registerStoreMutations, initLiveStore, subscribe }) => {
+      if (_destroyed) return
+      if (typeof window !== 'undefined') {
+        // window.__PULSE_STORE__ is serialised by the server when a store is registered.
+        initClientStore(window.__PULSE_STORE__ || {})
+        // Register store mutations so data-store-event bindings can dispatch them.
+        // No-op on subsequent mounts — mutations persist across client navigations.
+        if (options.store?.mutations) {
+          registerStoreMutations(options.store.mutations)
+        }
+        // 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 (window.__PULSE_LIVE__) {
+          initLiveStore(window.__PULSE_LIVE__)
+        }
+      }
+      // Subscribe to global store — re-render whenever store keys this page uses
+      // change. Wired here (after the async import resolves) rather than
+      // synchronously in mount() — see the module-level comment on loadStore.
+      _unsubStore = subscribe(() => render())
+    })
   }
   const _pageServerState = {}
   for (const [k, v] of Object.entries(serverState)) {
     if (!_storeKeys.has(k)) _pageServerState[k] = v
   }
 
+  // Snapshot of the store keys as SSR handed them to mount() — used as a
+  // fallback for renders that happen before store.js's lazy import resolves
+  // (initial render, and any dispatch that fires in that window). This keeps
+  // first paint identical to the pre-lazy behaviour: the SSR-seeded values are
+  // available immediately. Once store.js loads, getEffectiveServerState()
+  // switches over to the live singleton (getStoreState()), which is required
+  // for correctness after any store mutation.
+  const _storeSnapshot = {}
+  for (const k of _storeKeys) {
+    if (serverState[k] !== undefined) _storeSnapshot[k] = serverState[k]
+  }
+
   // Build the server state the view sees: fresh store slice + page-level data.
   // Page-level keys always win over store keys with the same name.
   function getEffectiveServerState() {
     if (!_storeKeys.size) return _pageServerState
-    const storeState = getStoreState()
+    const storeState = _storeModule ? _storeModule.getStoreState() : _storeSnapshot
     const slice = {}
     for (const key of _storeKeys) {
       if (storeState[key] !== undefined) slice[key] = storeState[key]
@@ -109,7 +173,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
     try {
       html = resolveView(spec, state, getEffectiveServerState())
     } catch (err) {
-      console.error('[Pulse] View error:', err)
+      console.error('[Pulse] view error:', err)
       const serverState = getEffectiveServerState()
       html = spec.onViewError
         ? spec.onViewError(err, state, serverState)
@@ -120,6 +184,24 @@ export function mount(spec, el, serverState = {}, options = {}) {
     morph(el, html)
   }
 
+  // ---------------------------------------------------------------------------
+  // Result application — shared by every mutation/action lifecycle step.
+  // Handles the side-channel keys (_toast, _storeUpdate), merges the rest of
+  // `raw` into state via constraints, and re-renders only if state actually
+  // changed. Used by dispatch() and every stage of runAction().
+  // ---------------------------------------------------------------------------
+
+  function applyResult(raw) {
+    const { _toast, _storeUpdate, ...partial } = raw ?? {}
+    // store.js may not be loaded yet on a page that doesn't itself declare
+    // spec.store but still pushes via _storeUpdate — load it on demand.
+    if (_storeUpdate) loadStore().then(({ updateStore }) => updateStore(_storeUpdate))
+    if (_toast)       showToast(_toast)
+    const prev = state
+    state = applyConstraints({ ...state, ...partial }, spec.constraints)
+    if (shallowChanged(prev, state)) render()
+  }
+
   // ---------------------------------------------------------------------------
   // Dispatch — the single entry point for all state changes
   // ---------------------------------------------------------------------------
@@ -128,12 +210,8 @@ export function mount(spec, el, serverState = {}, options = {}) {
     // Mutation
     if (spec.mutations?.[type]) {
       const raw = spec.mutations[type](state, payload)
-      if (raw?._toast) showToast(raw._toast)
-      const { _toast, ...partial } = raw ?? {}
-      const prev = state
-      state = applyConstraints({ ...state, ...partial }, spec.constraints)
+      applyResult(raw)
       persist()
-      if (shallowChanged(prev, state)) render()
       return
     }
 
@@ -143,7 +221,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
       return
     }
 
-    console.warn(`[Pulse] No mutation or action found for "${type}"`)
+    console.warn(`[Pulse] no mutation/action "${type}"`)
   }
 
   // ---------------------------------------------------------------------------
@@ -153,25 +231,15 @@ export function mount(spec, el, serverState = {}, options = {}) {
   async function runAction(name, action, currentState, payload) {
     // Optimistic update before async work
     if (action.onStart) {
-      const raw = action.onStart(currentState, payload)
-      if (raw?._toast) showToast(raw._toast)
-      const { _toast, ...partial } = raw ?? {}
-      const prev = state
-      state = applyConstraints({ ...state, ...partial }, spec.constraints)
-      if (shallowChanged(prev, state)) render()
+      applyResult(action.onStart(currentState, payload))
     }
 
     // Validate before running if requested
     if (action.validate) {
       const errors = validateFields(state, spec.validation)
       if (errors.length > 0) {
-        console.warn(`[Pulse] Validation failed for action "${name}":`, errors)
-        const raw = action.onError?.(state, { validation: errors }) ?? {}
-        if (raw._toast) showToast(raw._toast)
-        const { _toast, ...partial } = raw
-        const prev = state
-        state = applyConstraints({ ...state, ...partial }, spec.constraints)
-        if (shallowChanged(prev, state)) render()
+        console.warn(`[Pulse] Validation failed: "${name}"`, errors)
+        applyResult(action.onError?.(state, { validation: errors }))
         return
       }
     }
@@ -179,23 +247,10 @@ export function mount(spec, el, serverState = {}, options = {}) {
     try {
       // Pass fresh effective server state (includes live store values)
       const result = await action.run(state, getEffectiveServerState(), payload)
-      const raw    = action.onSuccess(state, result) ?? {}
-
-      // _storeUpdate — push changes to the global store and notify all subscribers
-      if (raw._storeUpdate) updateStore(raw._storeUpdate)
-      if (raw._toast)       showToast(raw._toast)
-      const { _storeUpdate: _su, _toast: _t, ...partial } = raw
-      const prev = state
-      state = applyConstraints({ ...state, ...partial }, spec.constraints)
-      if (shallowChanged(prev, state)) render()
+      applyResult(action.onSuccess(state, result))
     } catch (error) {
-      console.error(`[Pulse] Action "${name}" failed:`, error)
-      const raw = action.onError(state, error) ?? {}
-      if (raw._toast) showToast(raw._toast)
-      const { _toast, ...partial } = raw
-      const prev = state
-      state = applyConstraints({ ...state, ...partial }, spec.constraints)
-      if (shallowChanged(prev, state)) render()
+      console.error(`[Pulse] action "${name}" failed:`, error)
+      applyResult(action.onError(state, error))
     }
 
     persist()
@@ -210,9 +265,6 @@ export function mount(spec, el, serverState = {}, options = {}) {
   const _eventAbort = new AbortController()
   bindEvents(el, dispatch, _eventAbort.signal)
 
-  // Subscribe to global store — re-render whenever store keys this page uses change.
-  const _unsubStore = _storeKeys.size > 0 ? subscribe(() => render()) : null
-
   // If the element was server-rendered, skip the initial render to avoid
   // touching existing DOM — this preserves the early LCP paint from SSR.
   // Morph on first mutation will diff from whatever SSR left in the DOM.
@@ -235,7 +287,7 @@ export function mount(spec, el, serverState = {}, options = {}) {
     refresh: render,
 
     /** Tear down — remove event listeners, unsubscribe from store, clear element */
-    destroy: () => { _unsubStore?.(); _eventAbort.abort(); el.innerHTML = trustedHTML('') }
+    destroy: () => { _destroyed = true; _unsubStore?.(); _eventAbort.abort(); el.innerHTML = trustedHTML('') }
   }
 }
 
@@ -291,7 +343,7 @@ function bindEvents(el, dispatch, signal) {
     const storeTarget = e.target?.closest?.('[data-store-event]')
     if (storeTarget) {
       const [sType, sName] = parseEventAttr(storeTarget.dataset.storeEvent)
-      if (sType === 'click') { e.preventDefault(); dispatchStoreMutation(sName, e) }
+      if (sType === 'click') { e.preventDefault(); dispatchStoreMutationLazy(sName, e) }
       return
     }
 
@@ -334,7 +386,7 @@ function bindEvents(el, dispatch, signal) {
     const storeTarget = e.target?.closest?.('[data-store-event]')
     if (storeTarget) {
       const [sType, sName] = parseEventAttr(storeTarget.dataset.storeEvent)
-      if (sType === 'change') dispatchStoreMutation(sName, e)
+      if (sType === 'change') dispatchStoreMutationLazy(sName, e)
       return
     }
     const target = e.target?.closest?.('[data-event]')
@@ -348,7 +400,7 @@ function bindEvents(el, dispatch, signal) {
     const storeTarget = e.target?.closest?.('[data-store-event]')
     if (storeTarget) {
       const [sType, sName] = parseEventAttr(storeTarget.dataset.storeEvent)
-      if (sType === 'input') dispatchStoreMutation(sName, e)
+      if (sType === 'input') dispatchStoreMutationLazy(sName, e)
       return
     }
     const target = e.target?.closest?.('[data-event]')

package/src/runtime/runtime.test.js

@@ -598,7 +598,7 @@ test('dispatchStoreMutation warns on unknown mutation', () => {
   assert(warnings.some(w => w.includes('doesNotExist')), 'Expected warning for unknown store mutation')
 })
 
-test('dispatchStoreMutation notifies subscribed pages', () => {
+await testAsync('dispatchStoreMutation notifies subscribed pages', async () => {
   updateStore({ counter: 0 })
   const el = new FakeElement()
   const spec = {
@@ -608,6 +608,12 @@ test('dispatchStoreMutation notifies subscribed pages', () => {
     view: (state, server) => `<span>${server.counter ?? 0}</span>`,
   }
   mount(spec, el, { counter: 0 })
+  // store.js is lazy-loaded by mount() when spec.store is non-empty — its
+  // subscription is wired up after the dynamic import() resolves. Resolving
+  // a dynamic import is scheduled as a macrotask even for an already-cached
+  // module (verified empirically — microtask-only yields are not enough),
+  // so a setTimeout(0) tick-yield is required here, not just Promise.resolve().
+  await new Promise(r => setTimeout(r, 0))
   const before = el.innerHTML
   dispatchStoreMutation('inc')
   assert(el.innerHTML !== before, `Page should re-render after store mutation`)
@@ -623,7 +629,7 @@ test('registerStoreMutations is a no-op after first call', () => {
 
 console.log('\nLive store push (client)\n')
 
-test('initLiveStore connects once, merges SSE store events, survives bad frames', () => {
+await testAsync('initLiveStore connects once, merges SSE store events, survives bad frames', async () => {
   const instances = []
   globalThis.EventSource = class {
     constructor(url) { this.url = url; this._listeners = {}; instances.push(this) }
@@ -638,6 +644,9 @@ test('initLiveStore connects once, merges SSE store events, survives bad frames'
   // 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, {})
+  // store.js is lazy-loaded when spec.store is non-empty — wait for the dynamic
+  // import to resolve before the subscription (wired inside it) is live.
+  await new Promise(r => setTimeout(r, 0))
   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}`)
@@ -650,6 +659,41 @@ test('initLiveStore connects once, merges SSE store events, survives bad frames'
   delete globalThis.EventSource
 })
 
+console.log('\nLazy store loading (through mount())\n')
+
+await testAsync('mount() with spec.store lazy-loads store.js and wires reactivity end to end', async () => {
+  updateStore({ counter: 100 })
+  const el = new FakeElement()
+  const spec = {
+    route: '/lazy-store',
+    store: ['counter'],
+    state: {},
+    view: (state, server) => `<span>${server.counter ?? 0}</span>`,
+  }
+
+  const instance = mount(spec, el, { counter: 100 })
+
+  // mount() returns synchronously, before store.js's dynamic import has resolved —
+  // the view renders with the page-level serverState snapshot passed to mount()
+  // (not yet the live store slice), and store-driven reactivity is not wired yet.
+  assert(el.innerHTML.includes('100'), `Expected initial render to use the snapshot: ${el.innerHTML}`)
+
+  // Yield a macrotask so the lazy import('./store.js') resolves. This is the
+  // "one microtask/tick later" cost documented for the lazy-loading change —
+  // after this point store subscription, registerStoreMutations, and (when
+  // window.__PULSE_LIVE__ is set) initLiveStore have all been wired up.
+  await new Promise(r => setTimeout(r, 0))
+
+  // Store-driven re-render now works correctly end to end through mount():
+  // a mutation dispatched on the singleton reaches this page's subscription.
+  const before = el.innerHTML
+  dispatchStoreMutation('inc')
+  assert(el.innerHTML !== before, 'Page should re-render once store.js has loaded and subscribed')
+  assert(el.innerHTML.includes('101'), `Expected counter 101 in HTML, got: ${el.innerHTML}`)
+
+  instance.destroy()
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nDebounce / throttle\n')

package/src/runtime/ssr.js

@@ -313,6 +313,32 @@ export function buildHydrateScript(spec, storeDef, nonce) {
  * @param {Object}  [options.timing]     - Server-Timing values
  * @returns {string}
  */
+// Third-party stylesheets (e.g. Google Fonts) pay a DNS+TLS round trip before
+// the request can even start — preconnect warms that connection up in
+// parallel with the document request instead of after the browser parses the
+// stylesheet link. Relative URLs (same-origin) don't need this — the
+// connection to the page's own origin is already open. Shared by wrapDocument
+// (non-streaming render) and the streaming response head in server/index.js,
+// which builds its <head> independently rather than calling wrapDocument.
+export function buildStylePreconnects(styles = []) {
+  const styleOrigins = [...new Set(
+    styles
+      .map(href => { try { return new URL(href).origin } catch { return null } })
+      .filter(Boolean)
+  )]
+  return styleOrigins
+    .flatMap(origin => {
+      const links = [`<link rel="preconnect" href="${esc(origin)}">`]
+      // Google Fonts serves the CSS from fonts.googleapis.com but the actual
+      // font files from fonts.gstatic.com — preconnect to both up front.
+      if (origin === 'https://fonts.googleapis.com') {
+        links.push('<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>')
+      }
+      return links
+    })
+    .join('\n  ')
+}
+
 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'
@@ -328,6 +354,8 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
     meta.ogImage     ? `<meta property="og:image" content="${esc(meta.ogImage)}">` : '',
   ].filter(Boolean).join('\n  ')
 
+  const stylePreconnects = buildStylePreconnects([...(meta.styles || []), ...(meta.deferredStyles || [])])
+
   const stylePreloads = (meta.styles || [])
     .map(href => `<link rel="preload" as="style" href="${esc(href)}">`)
     .join('\n  ')
@@ -381,6 +409,7 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link rel="icon" href="${faviconHref || 'data:,'}">
   <title>${esc(title)}</title>
+  ${stylePreconnects}
   ${stylePreloads}
   ${runtimePreload}
   ${extraHead}

package/src/server/index.js

@@ -21,7 +21,7 @@ import { createRequire } from 'module'
 
 const _require = createRequire(import.meta.url)
 export const version = _require('../../package.json').version
-import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript } from '../runtime/ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript, buildStylePreconnects } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
 
@@ -1322,6 +1322,8 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
     try { res.writeEarlyHints({ link: earlyLinks }) } catch {}
   }
 
+  const stylePreconnects = buildStylePreconnects([...(meta.styles || []), ...(meta.deferredStyles || [])])
+
   const stylePreloads = (meta.styles || [])
     .map(href => `  <link rel="preload" as="style" href="${escHtml(href)}">`)
     .join('\n')
@@ -1358,7 +1360,7 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link rel="icon" href="${faviconPath || 'data:,'}">
   <title>${escHtml(title)}</title>
-${stylePreloads ? stylePreloads + '\n' : ''}${runtimePreload ? runtimePreload + '\n' : ''}${dev ? devImportMap(nonce) + '\n' : ''}${metaTags}
+${stylePreconnects ? stylePreconnects + '\n' : ''}${stylePreloads ? stylePreloads + '\n' : ''}${runtimePreload ? runtimePreload + '\n' : ''}${dev ? devImportMap(nonce) + '\n' : ''}${metaTags}
 </head>
 <body${bodyAttr}>
   <div id="pulse-root">`