@invisibleloop/pulse 0.7.1 → 0.7.3

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.7.0
+0.7.2

package/docs/public/menu.js

@@ -3,60 +3,63 @@
  * Loaded as an external script so it passes the CSP (no unsafe-inline needed).
  */
 (function () {
-  // ── Sidebar ──────────────────────────────────────────────────────────────
-  var btn     = document.querySelector('.mobile-menu-btn')
-  var sidebar = document.querySelector('.docs-sidebar')
-  var overlay = document.querySelector('.sidebar-overlay')
+  // ── Scroll active nav item into view ─────────────────────────────────────
 
-  if (btn && sidebar) {
-    function open() {
-      sidebar.classList.add('open')
-      overlay && overlay.classList.add('visible')
-      document.body.style.overflow = 'hidden'
-    }
+  function centerNavLink(sidebar, link) {
+    if (!sidebar || !link) return
+    var navRect  = sidebar.getBoundingClientRect()
+    var linkRect = link.getBoundingClientRect()
+    sidebar.scrollTop = sidebar.scrollTop + (linkRect.top - navRect.top) - sidebar.clientHeight / 2 + link.clientHeight / 2
+  }
 
-    function close() {
-      sidebar.classList.remove('open')
-      overlay && overlay.classList.remove('visible')
-      document.body.style.overflow = ''
-    }
+  // ── Bind sidebar, mobile menu, and centre the active link ─────────────────
+  // Called on first load and after every client-side navigation, because
+  // #pulse-root is replaced on navigate — all element references go stale.
 
-    btn.addEventListener('click', function () {
-      sidebar.classList.contains('open') ? close() : open()
-    })
+  function init() {
+    var sidebar = document.querySelector('.docs-sidebar')
+    var btn     = document.querySelector('.mobile-menu-btn')
+    var overlay = document.querySelector('.sidebar-overlay')
 
-    overlay && overlay.addEventListener('click', close)
+    // Mobile open/close
+    if (btn && sidebar) {
+      function open() {
+        sidebar.classList.add('open')
+        overlay && overlay.classList.add('visible')
+        document.body.style.overflow = 'hidden'
+      }
 
-    sidebar.querySelectorAll('.nav-link').forEach(function (link) {
-      link.addEventListener('click', close)
-    })
-  }
+      function close() {
+        sidebar.classList.remove('open')
+        overlay && overlay.classList.remove('visible')
+        document.body.style.overflow = ''
+      }
 
-  // ── Scroll active nav item into view ─────────────────────────────────────
-  var navSidebar = document.querySelector('.docs-sidebar')
+      btn.addEventListener('click', function () {
+        sidebar.classList.contains('open') ? close() : open()
+      })
 
-  function centerNavLink(link) {
-    if (!navSidebar || !link) return
-    var navRect  = navSidebar.getBoundingClientRect()
-    var linkRect = link.getBoundingClientRect()
-    navSidebar.scrollTop = navSidebar.scrollTop + (linkRect.top - navRect.top) - navSidebar.clientHeight / 2 + link.clientHeight / 2
-  }
+      overlay && overlay.addEventListener('click', close)
 
-  // On initial load — scroll to the currently active link
-  var activeLink = navSidebar && navSidebar.querySelector('.nav-link.active')
-  if (activeLink) {
-    if (document.readyState === 'complete') {
-      setTimeout(function () { centerNavLink(activeLink) }, 50)
-    } else {
-      window.addEventListener('load', function () { centerNavLink(activeLink) })
+      sidebar.querySelectorAll('.nav-link').forEach(function (link) {
+        link.addEventListener('click', close)
+      })
     }
+
+    // Centre the active link
+    var activeLink = sidebar && sidebar.querySelector('.nav-link.active')
+    if (activeLink) centerNavLink(sidebar, activeLink)
   }
 
-  // After client-side navigation — sidebar DOM is replaced, so re-query and re-centre
-  document.addEventListener('pulse:navigate', function () {
-    var newActive = navSidebar && navSidebar.querySelector('.nav-link.active')
-    centerNavLink(newActive)
-  })
+  // On initial load — wait for layout paint before scrolling
+  if (document.readyState === 'complete') {
+    setTimeout(init, 50)
+  } else {
+    window.addEventListener('load', init)
+  }
+
+  // After client-side navigation — re-bind everything against the fresh DOM
+  document.addEventListener('pulse:navigate', init)
 
   // ── Slider fill ──────────────────────────────────────────────────────────
   function updateSliderFill(input) {

package/docs/src/lib/layout.js

@@ -14,7 +14,7 @@ let _manifest = {}
 export function initLayoutManifest(m) { _manifest = m }
 const asset = href => _manifest[href] || href
 
-const { version } = pkg
+const version = typeof pkg !== 'undefined' ? (pkg?.version ?? '') : ''
 
 function esc(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -57,7 +57,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root docs --port 4000",
     "docs:start": "node docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.7.1
+0.7.3

package/scripts/build.js

@@ -476,7 +476,9 @@ const result = await esbuild.build({
 const manifest = {}
 
 for (const [outFile, meta] of Object.entries(result.metafile.outputs)) {
-  const bundlePath = '/' + path.relative(path.join(ROOT, 'public'), path.join(ROOT, outFile))
+  // 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-')) {

package/src/cli/dev.js

@@ -187,11 +187,14 @@ const { updateSpecs } = createServer(specs, {
 
     const serveFile = (filePath) => {
       if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return false
-      // Strip node:* imports — they don't resolve in the browser. Server-only imports
-      // are only used inside spec.server functions which the client runtime never calls.
+      // Strip server-only imports that can't resolve in the browser:
+      //   - node:* built-ins (fs, path, etc.)
+      //   - JSON files imported with `with { type: 'json' }` (e.g. package.json for version)
+      // These are only used inside spec.server functions or module-level server init;
+      // the client runtime never calls those code paths.
       let content = fs.readFileSync(filePath, 'utf-8')
       content = content.replace(
-        /^[ \t]*import\s+(?:\{[^}]*\}|[\w*]+(?:\s+as\s+\w+)?)\s+from\s+['"]node:[^'"]+['"]\s*;?[ \t]*\n?/gm,
+        /^[ \t]*import\s+(?:\{[^}]*\}|[\w*]+(?:\s+as\s+\w+)?)\s+from\s+['"](?:node:[^'"]+|[^'"]*\.json)['"]\s*(?:with\s*\{[^}]*\})?\s*;?[ \t]*\n?/gm,
         ''
       )
       res.writeHead(200, {

package/src/runtime/navigate.js

@@ -104,10 +104,13 @@ export function initNavigation(root, mountFn) {
         document.dispatchEvent(new CustomEvent('pulse:navigate'))
 
         if (hydratePath && mountFn) {
+          const { default: spec } = await import(/* @vite-ignore */ hydratePath)
+          // A newer navigation may have started while the import was in flight —
+          // bail out rather than destroying the already-mounted next page.
+          if (controller.signal.aborted) return
           currentMount?.destroy()
           root.dataset.pulseMounted = '1'
           window.__PULSE_SERVER__ = finalServerState
-          const { default: spec } = await import(/* @vite-ignore */ hydratePath)
           if (spec) currentMount = mountFn(spec, root, finalServerState)
         }
 
@@ -130,10 +133,11 @@ export function initNavigation(root, mountFn) {
         if (push) history.pushState({ pulse: true, path }, '', path)
 
         if (hydrate && mountFn) {
+          const { default: spec } = await import(/* @vite-ignore */ hydrate)
+          if (controller.signal.aborted) return
           currentMount?.destroy()
           root.dataset.pulseMounted = '1'
           window.__PULSE_SERVER__ = serverState || {}
-          const { default: spec } = await import(/* @vite-ignore */ hydrate)
           if (spec) currentMount = mountFn(spec, root, serverState || {})
         }
 

package/src/runtime/navigate.test.js

@@ -0,0 +1,304 @@
+/**
+ * Pulse — Navigate tests
+ * run: node src/runtime/navigate.test.js
+ */
+
+import { initNavigation } from './navigate.js'
+import assert from 'node:assert'
+
+// ── Test runner ───────────────────────────────────────────────────────────────
+
+let passed = 0
+let failed = 0
+
+async function test(label, fn) {
+  try {
+    await fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+// ── Minimal browser shims ─────────────────────────────────────────────────────
+
+function makeRoot() {
+  const root = {
+    innerHTML: '',
+    dataset:   {},
+    querySelector:    () => null,
+    querySelectorAll: () => [],
+    hasAttribute: (k) => root._attrs.has(k),
+    setAttribute: (k) => root._attrs.add(k),
+    removeAttribute: (k) => root._attrs.delete(k),
+    addEventListener: () => {},
+    focus: () => {},
+    _attrs: new Set(),
+  }
+  return root
+}
+
+/**
+ * Set up fresh browser globals and call initNavigation().
+ * Returns helpers to fire the registered click and popstate handlers.
+ */
+function setup({ mountFn = null } = {}) {
+  let clickHandler = null
+  let popHandler   = null
+
+  global.history  = { replaceState: () => {}, pushState: () => {} }
+  global.location = { pathname: '/start', search: '', origin: 'http://localhost', href: '' }
+  global.window   = {
+    scrollTo: () => {},
+    addEventListener: (e, fn) => { if (e === 'popstate') popHandler = fn },
+  }
+  global.document = {
+    title: 'Test',
+    addEventListener: (e, fn) => { if (e === 'click') clickHandler = fn },
+    dispatchEvent:    () => {},
+    querySelectorAll: () => [],
+    createElement:    () => ({
+      rel: '', href: '', src: '', textContent: '', type: '',
+      setAttribute: () => {},
+      getAttribute: () => null,
+      onload: null, onerror: null,
+    }),
+    head: { appendChild: () => {} },
+  }
+  global.CustomEvent = class { constructor(n) { this.type = n } }
+
+  const root = makeRoot()
+  initNavigation(root, mountFn)
+
+  return {
+    root,
+    click: (ev) => clickHandler(ev),
+    pop:   (ev) => popHandler(ev),
+  }
+}
+
+/** Build a synthetic click event targeting an anchor. */
+function clickEvent({ href, ctrlKey = false, metaKey = false, shiftKey = false, altKey = false, linkTarget = '' }) {
+  const anchor = {
+    getAttribute: (k) => k === 'href' ? (href ?? null) : null,
+    target: linkTarget,
+  }
+  return {
+    target:      { closest: (sel) => sel === 'a' ? anchor : null },
+    ctrlKey, metaKey, shiftKey, altKey,
+    preventDefault: () => {},
+  }
+}
+
+/** Event where target has no ancestor <a>. */
+function nonAnchorEvent() {
+  return {
+    target:      { closest: () => null },
+    ctrlKey: false, metaKey: false, shiftKey: false, altKey: false,
+    preventDefault: () => {},
+  }
+}
+
+// ── Click handler — link filtering ───────────────────────────────────────────
+
+console.log('\nClick handler — link filtering\n')
+
+await test('does not intercept clicks with no ancestor anchor', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(nonAnchorEvent())
+  assert(!called)
+})
+
+await test('does not intercept anchor with no href', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: null }))
+  assert(!called)
+})
+
+await test('does not intercept cross-origin links', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: 'https://example.com/page' }))
+  assert(!called)
+})
+
+await test('does not intercept ctrl+click', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: '/page', ctrlKey: true }))
+  assert(!called)
+})
+
+await test('does not intercept meta+click', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: '/page', metaKey: true }))
+  assert(!called)
+})
+
+await test('does not intercept shift+click', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: '/page', shiftKey: true }))
+  assert(!called)
+})
+
+await test('does not intercept target=_blank links', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: '/page', linkTarget: '_blank' }))
+  assert(!called)
+})
+
+await test('intercepts same-origin links', async () => {
+  const { click } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  click(clickEvent({ href: '/same-origin' }))
+  assert(called, 'fetch should be called for same-origin link')
+})
+
+// ── Navigation — fetch abort and cancellation ────────────────────────────────
+
+console.log('\nNavigation — fetch abort and cancellation\n')
+
+await test('aborts in-flight fetch when a new navigation starts', async () => {
+  const { click } = setup()
+  const signals = []
+  global.fetch = async (_url, opts) => {
+    signals.push(opts.signal)
+    return new Promise(() => {}) // never resolves
+  }
+
+  click(clickEvent({ href: '/page-a' }))
+  click(clickEvent({ href: '/page-b' }))
+
+  assert.equal(signals.length, 2, 'two fetches made')
+  assert(signals[0].aborted,  'first navigation signal should be aborted')
+  assert(!signals[1].aborted, 'second navigation signal should not be aborted')
+})
+
+await test('swallows AbortError — does not fall back to location.href', async () => {
+  const { click } = setup()
+  global.fetch = async () => {
+    const err = new Error('aborted')
+    err.name = 'AbortError'
+    throw err
+  }
+  let fallbackSet = false
+  Object.defineProperty(global.location, 'href', {
+    set: () => { fallbackSet = true },
+    get: () => '',
+    configurable: true,
+  })
+  click(clickEvent({ href: '/page' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert(!fallbackSet, 'AbortError must not trigger location.href fallback')
+})
+
+await test('falls back to location.href on network error', async () => {
+  const { click } = setup()
+  global.fetch = async () => { throw new Error('network failure') }
+  let fallback = null
+  Object.defineProperty(global.location, 'href', {
+    set: (v) => { fallback = v },
+    get: () => '',
+    configurable: true,
+  })
+  click(clickEvent({ href: '/broken' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert.equal(fallback, '/broken')
+})
+
+await test('falls back to location.href on non-ok response', async () => {
+  const { click } = setup()
+  global.fetch = async () => ({ ok: false })
+  let fallback = null
+  Object.defineProperty(global.location, 'href', {
+    set: (v) => { fallback = v },
+    get: () => '',
+    configurable: true,
+  })
+  click(clickEvent({ href: '/missing' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert.equal(fallback, '/missing')
+})
+
+// ── Navigation — JSON response ───────────────────────────────────────────────
+
+console.log('\nNavigation — JSON response\n')
+
+function jsonFetch(payload) {
+  return async () => ({
+    ok: true,
+    headers: { get: () => 'application/json' },
+    json: async () => payload,
+  })
+}
+
+await test('sets root.innerHTML from JSON html field', async () => {
+  const { click, root } = setup()
+  global.fetch = jsonFetch({ html: '<p>Hello</p>', title: 'T', styles: [], scripts: [], hydrate: null, serverState: {}, storeState: null })
+  click(clickEvent({ href: '/new' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert.equal(root.innerHTML, '<p>Hello</p>')
+})
+
+await test('updates document.title from JSON title field', async () => {
+  const { click } = setup()
+  global.fetch = jsonFetch({ html: '', title: 'New Title', styles: [], scripts: [], hydrate: null, serverState: {}, storeState: null })
+  click(clickEvent({ href: '/titled' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert.equal(global.document.title, 'New Title')
+})
+
+await test('updates store state when storeState is present', async () => {
+  const { click } = setup()
+  global.fetch = jsonFetch({ html: '', title: '', styles: [], scripts: [], hydrate: null, serverState: {}, storeState: { theme: 'dark' } })
+  let stored = null
+  global.window.__updatePulseStore__ = (s) => { stored = s }
+  click(clickEvent({ href: '/store-page' }))
+  await new Promise(r => setTimeout(r, 10))
+  assert.deepEqual(stored, { theme: 'dark' })
+})
+
+// ── Navigation — popstate ────────────────────────────────────────────────────
+
+console.log('\nNavigation — popstate\n')
+
+await test('navigates on pulse popstate', async () => {
+  const { pop } = setup()
+  let fetchedPath = null
+  global.fetch = async (path) => { fetchedPath = path; return new Promise(() => {}) }
+  global.location.pathname = '/history-page'
+  global.location.search   = ''
+  pop({ state: { pulse: true } })
+  await new Promise(r => setTimeout(r, 0))
+  assert.equal(fetchedPath, '/history-page')
+})
+
+await test('ignores popstate without pulse state', async () => {
+  const { pop } = setup()
+  let called = false
+  global.fetch = async () => { called = true; return new Promise(() => {}) }
+  pop({ state: null })
+  pop({ state: { pulse: false } })
+  assert(!called, 'fetch should not be called for non-pulse popstate')
+})
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/runtime/ssr.js

@@ -258,9 +258,48 @@ export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// Page HTML wrapper
+// Page HTML wrapper — shared script builders
 // ---------------------------------------------------------------------------
 
+/**
+ * Build the inline script that exposes window.__PULSE_NONCE__ and (optionally)
+ * window.__PULSE_STORE__ to the client runtime.
+ *
+ * Only emitted for hydrated pages. Purely server-rendered pages have no JS to
+ * 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) {
+  if (!spec.hydrate) return ''
+  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}';</script>`
+}
+
+/**
+ * Build the hydration <script> tag that mounts the spec client-side.
+ *
+ * Bundle paths (/dist/) → a single external <script type="module" src="..."> tag.
+ * Dev source paths       → an inline module block with explicit imports (nonce required).
+ */
+export function buildHydrateScript(spec, storeDef, nonce) {
+  if (!spec.hydrate) return ''
+  if (isBundle(spec.hydrate)) {
+    return `<script type="module" src="${esc(spec.hydrate)}"></script>`
+  }
+  const storeImport = storeDef?.hydrate ? `\n  import store from '${esc(storeDef.hydrate)}'` : ''
+  const storeArg    = storeDef?.hydrate ? ', { ssr: true, store }' : ', { ssr: true }'
+  return `<script type="module" nonce="${nonce}">
+  import spec from '${esc(spec.hydrate)}'
+  import { mount } from '/@pulse/runtime/index.js'
+  import { initNavigation } from '/@pulse/runtime/navigate.js'${storeImport}
+  const root = document.getElementById('pulse-root')
+  mount(spec, root, window.__PULSE_SERVER__ || {}${storeArg})
+  initNavigation(root, mount)
+</script>`
+}
+
 /**
  * Wrap rendered content in a full HTML document.
  *
@@ -320,40 +359,8 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
     ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(serverState)};</script>`
     : ''
 
-  // Serialise store state so the client store singleton can be initialised.
-  // Also exposes window.__updatePulseStore__ so navigate.js can refresh the
-  // singleton with fresh server data on client-side navigations.
-  // window.__PULSE_NONCE__ lets the toast runtime inject a nonce'd <style> tag
-  // to satisfy the style-src CSP directive.
-  const storeStateScript = storeState && Object.keys(storeState).length > 0
-    ? `<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>`
-    : spec.hydrate
-      ? `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';</script>`
-      : ''
-
-  // Hydration bootstrap — makes the server-rendered HTML interactive.
-  // When hydrate points to a self-executing bundle (/dist/…) a single <script>
-  // tag is enough; the bundle imports spec + runtime and calls mount() itself.
-  // In dev mode (source file path) we emit the explicit inline import block.
-  const storeImport  = spec.hydrate && !isBundle(spec.hydrate) && storeDef?.hydrate
-    ? `\n  import store from '${esc(storeDef.hydrate)}'`
-    : ''
-  const storeArg     = spec.hydrate && !isBundle(spec.hydrate) && storeDef?.hydrate
-    ? ', { ssr: true, store }'
-    : ', { ssr: true }'
-
-  const hydrateScript = spec.hydrate
-    ? isBundle(spec.hydrate)
-      ? `<script type="module" src="${esc(spec.hydrate)}"></script>`
-      : `<script type="module" nonce="${nonce}">
-  import spec from '${esc(spec.hydrate)}'
-  import { mount } from '/@pulse/runtime/index.js'
-  import { initNavigation } from '/@pulse/runtime/navigate.js'${storeImport}
-  const root = document.getElementById('pulse-root')
-  mount(spec, root, window.__PULSE_SERVER__ || {}${storeArg})
-  initNavigation(root, mount)
-</script>`
-    : ''
+  const storeStateScript = buildStoreScript(spec, storeState, nonce)
+  const hydrateScript    = buildHydrateScript(spec, storeDef, nonce)
 
   // Server-Timing header value (caller is responsible for setting the header)
   const serverTimingValue = timing.total !== undefined

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 } from '../runtime/ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
 
@@ -92,8 +92,8 @@ function buildCsp(nonce, ext = {}) {
 
 /**
  * Build the nonce-free CSP for cached responses.
- * Safe because cached pages (no spec.server, no spec.store) are only cached
- * when they have no spec.hydrate — so no inline nonce scripts are present.
+ * Safe because isCacheablePage() only returns true when spec.server, spec.store,
+ * and spec.hydrate are all absent — guaranteeing no inline nonce scripts in the HTML.
  * @param {Record<string,string[]>} [ext]  Extra sources to merge in per directive.
  */
 function buildCachedCsp(ext = {}) {
@@ -305,6 +305,26 @@ function pageCacheTtl(spec, dev, defaultCache) {
   return cfg?.maxAge || 0
 }
 
+/** Build the in-process page cache key scoped to route + request parameters. */
+function buildCacheKey(spec, ctx) {
+  return spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
+}
+
+/**
+ * True when a page's rendered HTML is safe to cache in-process.
+ *
+ * A page is NOT cacheable if it has any of:
+ *   - spec.server  — embeds a nonce'd __PULSE_SERVER__ inline script
+ *   - spec.store   — same
+ *   - spec.hydrate — embeds a nonce'd __PULSE_NONCE__ inline script (for toasts)
+ *
+ * In all three cases the cached HTML would contain a nonce that doesn't match
+ * the nonce-free CSP used for cached responses, causing a CSP violation.
+ */
+function isCacheablePage(spec) {
+  return !spec.server && !spec.store?.length && !spec.hydrate
+}
+
 // ---------------------------------------------------------------------------
 // Dev import map — lets browser resolve @invisibleloop/pulse/* bare specifiers
 // ---------------------------------------------------------------------------
@@ -350,8 +370,7 @@ async function cachedRenderToString(spec, ctx, dev) {
     return renderToString(spec, ctx)
   }
 
-  // Build a cache key scoped to this route + request parameters
-  const key = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
+  const key = buildCacheKey(spec, ctx)
 
   const cached = serverDataCache.get(key)
   if (cached) return cached
@@ -841,9 +860,8 @@ async function handleNavStreamResponse(spec, ctx, req, res) {
  * 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) {
-  const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
-  // Pages with server data or store data embed a nonce'd __PULSE_SERVER__ script — don't cache them
-  const ttl      = (!spec.server && !spec.store?.length) ? pageCacheTtl(spec, dev, defaultCache) : 0
+  const cacheKey = buildCacheKey(spec, ctx)
+  const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
 
   let html, serverTimingValue, fromCache = false
 
@@ -892,9 +910,8 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
  */
 async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}, faviconPath = null) {
   // Serve from in-process page cache when available — skip streaming overhead.
-  // Pages with spec.server or spec.store embed a nonce'd __PULSE_SERVER__ script so are never cached.
-  const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
-  const ttl      = (!spec.server && !spec.store?.length) ? pageCacheTtl(spec, dev, defaultCache) : 0
+  const cacheKey = buildCacheKey(spec, ctx)
+  const ttl      = isCacheablePage(spec) ? pageCacheTtl(spec, dev, defaultCache) : 0
   const cached   = ttl > 0 ? pageHtmlCache.get(cacheKey) : null
 
   if (cached) {
@@ -973,45 +990,19 @@ ${stylePreloads ? stylePreloads + '\n' : ''}${runtimePreload ? runtimePreload +
 <body${bodyAttr}>
   <div id="pulse-root">`
 
-  const storeImport  = !spec.hydrate?.startsWith('/dist/') && store?.hydrate
-    ? `\n  import store from '${escHtml(store.hydrate)}'`
-    : ''
-  const storeArg     = !spec.hydrate?.startsWith('/dist/') && store?.hydrate
-    ? ', { ssr: true, store }'
-    : ', { ssr: true }'
-
-  const hydrateScript = spec.hydrate
-    ? spec.hydrate.startsWith('/dist/')
-      ? `\n  <script type="module" src="${escHtml(spec.hydrate)}"></script>`
-      : `\n  <script type="module" nonce="${nonce}">
-  import spec from '${escHtml(spec.hydrate)}'
-  import { mount } from '/@pulse/runtime/index.js'
-  import { initNavigation } from '/@pulse/runtime/navigate.js'${storeImport}
-  const root = document.getElementById('pulse-root')
-  mount(spec, root, window.__PULSE_SERVER__ || {}${storeArg})
-  initNavigation(root, mount)
-</script>`
-    : ''
-
-  const scriptTags = (meta.scripts || [])
+  const scriptTags    = (meta.scripts || [])
     .map(src => `  <script src="${escHtml(src)}" defer></script>`)
     .join('\n')
+  const storeScript   = buildStoreScript(spec, ctx.store || null, nonce)
+  const hydrateScript = buildHydrateScript(spec, store, nonce)
 
   const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody
 
-  // Emit window.__PULSE_STORE__ so the client store singleton can be initialised.
-  // Also exposes __updatePulseStore__ for navigate.js to refresh store on navigation.
-  // window.__PULSE_NONCE__ lets the toast runtime inject a nonce'd <style> tag to
-  // satisfy the style-src CSP directive (which disallows uninonce'd inline styles).
-  const storeScript = ctx.store && Object.keys(ctx.store).length > 0
-    ? `\n  <script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';window.__PULSE_STORE__=${JSON.stringify(ctx.store)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
-    : spec.hydrate
-      ? `\n  <script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';</script>`
-      : ''
-
   const docClose = `
   </div>
-  ${scriptTags}${storeScript}${hydrateScript}
+  ${scriptTags}
+  ${storeScript}
+  ${hydrateScript}
   ${resolvedExtraBody}
 </body>
 </html>`