@invisibleloop/pulse 0.7.2 → 0.8.0

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

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

package/docs/public/docs.css

@@ -683,6 +683,7 @@ a:hover {
   font-weight: 700;
   letter-spacing: -0.02em;
   margin: 0.75rem 0 1.25rem;
+  text-align: center;
 }
 
 .ai-first-lead {
@@ -691,6 +692,9 @@ a:hover {
   line-height: 1.75;
   max-width: 72ch;
   margin-bottom: 3rem;
+  text-align: center;
+  margin-left: auto;
+  margin-right: auto;
 }
 
 .ai-cols {
@@ -751,10 +755,10 @@ a:hover {
 }
 
 .ai-col-list li::before {
-  content: "–";
+  content: "✓";
   position: absolute;
   left: 0;
-  color: var(--muted-2);
+  color: var(--accent);
 }
 
 .ai-col--pulse .ai-col-list li {

package/docs/public/menu.js

@@ -3,62 +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 — #pulse-root is replaced, so the original
-  // navSidebar reference is detached. Re-query for the fresh sidebar element.
-  document.addEventListener('pulse:navigate', function () {
-    navSidebar = document.querySelector('.docs-sidebar')
-    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/pages/home.js

@@ -37,7 +37,7 @@ export default {
   route: '/',
   meta: {
     title: 'Pulse — The spec-first web framework',
-    description: 'Pulse is a server-first web framework with streaming SSR, zero client JS by default, and Lighthouse 100 built into the architecture. One spec format. One way to build. Production quality by design.',
+    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.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
   state: {},
@@ -67,9 +67,9 @@ export default {
           </svg>
         </div>
         <div class="hero-badge">v${version} — EARLY ACCESS</div>
-        <p class="hero-kicker">A Node.js framework for building server-rendered web apps</p>
-        <h1 class="hero-title">Describe the outcome. Pulse guarantees it.</h1>
-        <p class="hero-subtitle">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 framework, not left to configuration.<br><strong>Designed for AI agents.</strong></p>
+        <p class="hero-kicker">A server-first Node.js framework. Zero runtime dependencies.</p>
+        <h1 class="hero-title">One spec. One way to build. Production quality by design.</h1>
+        <p class="hero-subtitle">Each page is a single plain JS object — server data, client state, mutations, and view co-located in one place. Streaming SSR, security headers, and production caching are enforced by the framework, not left to configuration.<br><strong>Designed for AI agents. Simple enough to write yourself.</strong></p>
         <div class="hero-ctas">
           <a href="/getting-started" class="btn-primary">Get Started</a>
           <a href="/spec" class="btn-secondary">Read the Spec</a>
@@ -94,30 +94,30 @@ export default {
         <div class="home-stat-divider"></div>
         <div class="home-stat">
           <span class="home-stat-value">100</span>
-          <span class="home-stat-label">Lighthouse score</span>
+          <span class="home-stat-label">Lighthouse score, by design</span>
         </div>
       </section>
 
       <section class="how">
         <div class="how-inner">
-        <h2 class="section-label">How it works</h2>
+        <h2 class="section-label">The idea</h2>
         <div class="how-steps">
           <div class="how-step">
             <div class="how-step-num">1</div>
-            <h3>Write a spec</h3>
-            <p>Everything for a page lives in one object: server data, state, mutations, view. One format, no conventions to learn.</p>
+            <h3>The spec is the page</h3>
+            <p>Everything a page needs lives in one plain JS object — server data, client state, mutations, and view. One format, no split files, no hidden conventions.</p>
           </div>
           <div class="how-connector" aria-hidden="true"></div>
           <div class="how-step">
             <div class="how-step-num">2</div>
-            <h3>Validate automatically</h3>
-            <p>The schema enforces a single, correct structure. Either the spec is valid, or it’s rejected — no ambiguity, no runtime surprises.</p>
+            <h3>The schema is the contract</h3>
+            <p>Every spec is validated at startup. Either it's correct or it's rejected — no ambiguity, no misconfiguration that surfaces later in production.</p>
           </div>
           <div class="how-connector" aria-hidden="true"></div>
           <div class="how-step">
             <div class="how-step-num">3</div>
-            <h3>Production quality, built in</h3>
-            <p>Streaming SSR, security headers, and immutable caching come from the framework — not your config. Follow the spec, and the results follow.</p>
+            <h3>The framework is the guarantee</h3>
+            <p>Streaming SSR, security headers, and production caching come from the architecture. You write the product logic. The framework ships the quality.</p>
           </div>
         </div>
         </div>
@@ -126,8 +126,8 @@ export default {
       <section class="home-code">
         <div class="home-code-inner">
           <div class="home-code-header">
-            <h2>Everything in one object</h2>
-            <p>Server data, state, mutations, and view are co-located. No split files. No hidden conventions. The spec <strong>is</strong> the page.</p>
+            <h2>Everything a page needs. Nothing it doesn't.</h2>
+            <p>Server fetchers, client state, mutations, and view are co-located in one object. No split files. No magic exports. The spec <strong>is</strong> the page — readable, predictable, complete.</p>
           </div>
           <div class="home-code-block">
             ${codeWindow({ content: exampleSpec, filename: 'src/pages/dashboard.js', lang: 'JavaScript' })}
@@ -136,26 +136,26 @@ export default {
       </section>
 
       <section class="ai-first">
-        <div class="section-label">Why Pulse + AI</div>
-        <h2 class="ai-first-title">Designed for AI agents. Enforced by the framework.</h2>
-        <p class="ai-first-lead"><strong>Traditional frameworks</strong> were built for humans — multiple valid patterns, optional decisions, enough surface area for output to drift. Pulse is different.</p>
+        <div class="section-label">AI + Pulse</div>
+        <h2 class="ai-first-title">The constraint is the point. For humans and agents&nbsp;alike.</h2>
+        <p class="ai-first-lead">Pulse was designed around a simple observation: when there is only one correct way to build a page, every page is built correctly — whether you wrote it or an AI did. The spec format is the advantage. The schema is the enforcement.</p>
         <div class="ai-cols">
           <div class="ai-col">
-            <h3 class="ai-col-title ai-col-title--bad">AI + existing frameworks</h3>
+            <h3 class="ai-col-title">For developers</h3>
             <ul class="ai-col-list">
-              <li>Multiple valid patterns per page — the agent picks one, the next picks another.</li>
-              <li>Security headers, SSR config, and caching are optional decisions the agent can miss.</li>
-              <li>Output drifts over time as different agents make different choices.</li>
-              <li>Reviewing AI output requires knowing every pattern it could have used.</li>
+              <li>One format to learn — server, state, mutations, view in one place.</li>
+              <li>Production quality is the starting point, not a final audit.</li>
+              <li>Specs are short, self-contained, and easy to review.</li>
+              <li>Nothing to misconfigure — the framework doesn't give you the choice.</li>
             </ul>
           </div>
           <div class="ai-col ai-col--pulse">
-            <h3 class="ai-col-title ai-col-title--good">Pulse + AI enforces structure</h3>
+            <h3 class="ai-col-title ai-col-title--good">For AI agents</h3>
             <ul class="ai-col-list">
-              <li>One spec format per page.</li>
-              <li>Architecture enforces SSR, security, and caching.</li>
-              <li>Agents fill in the contract, never off-pattern.</li>
-              <li>Reading AI output means reading one JS object — nothing hidden.</li>
+              <li>One valid structure per page — agents can't pick the wrong pattern.</li>
+              <li>The schema rejects bad output at startup, not in production.</li>
+              <li>Security, SSR, and caching can't be accidentally omitted.</li>
+              <li>Consistent output across agents, sessions, and team members.</li>
             </ul>
           </div>
         </div>
@@ -164,7 +164,7 @@ export default {
       <section class="versus">
         <div class="section-label">How Pulse compares</div>
         <h2 class="versus-title">Constraints enforced. Not recommended.</h2>
-        <p class="versus-sub">Pulse enforces constraints and correctness out of the box; other frameworks leave it to the developer.</p>
+        <p class="versus-sub">Pulse enforces correctness out of the box. Other frameworks leave production quality to the developer.</p>
         <div class="versus-table-wrap table-sticky-col">
           <table class="versus-table">
             <thead>
@@ -195,13 +195,13 @@ export default {
               <tr>
                 <th scope="row">SSR out of the box</th>
                 <td class="v-yes">Streaming SSR, zero config</td>
-                <td class="v-partial">Yes, but client hydration adds JS overhead on every page</td>
+                <td class="v-partial">Yes, but client hydration adds JS on every page</td>
                 <td class="v-partial">Yes, but requires an adapter and client runtime on every page</td>
               </tr>
               <tr>
                 <th scope="row">Client JS shipped</th>
-                <td class="v-yes">~4 kB brotli (shared runtime, first visit)</td>
-                <td class="v-no">50-200 kB+ depending on features</td>
+                <td class="v-yes">~4 kB brotli on first visit; 0 kB on static pages</td>
+                <td class="v-no">50–200 kB+ depending on features used</td>
                 <td class="v-partial">~15 kB brotli</td>
               </tr>
               <tr>
@@ -224,7 +224,7 @@ export default {
               </tr>
               <tr>
                 <th scope="row">Production build step</th>
-                <td class="v-yes">None — <code>node server.js</code> is production</td>
+                <td class="v-yes">Server needs none — <code>node server.js</code> is production. Client bundles are optional.</td>
                 <td class="v-no">Required — <code>next build</code></td>
                 <td class="v-no">Required — <code>vite build</code></td>
               </tr>
@@ -243,24 +243,24 @@ export default {
               </svg>
             </div>
             <h2>Performance by design</h2>
-            <p>Pulse does not offer performance as an option — it enforces it structurally. A high Lighthouse score is the baseline. There is nothing to configure because there is nothing to get wrong.</p>
+            <p>Performance is not a Pulse feature — it is a structural outcome. A high Lighthouse score is the baseline. There is nothing to configure because the architecture makes the right choices automatically.</p>
           </div>
           <ul class="usp-points">
             <li>
               <strong>Fast LCP by design.</strong>
-              The shell renders and streams instantly. Deferred segments arrive as data resolves — no blocking, no flash.
+              The shell streams to the browser instantly. Deferred segments arrive as data resolves — no blocking, no flash, no placeholder juggling.
             </li>
             <li>
               <strong>~4 kB of JS on first visit.</strong>
-              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.4–0.9 kB.
+              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.4–0.9 kB. Static pages ship zero JS.
             </li>
             <li>
               <strong>Zero CLS.</strong>
-              The shell occupies the correct layout before data arrives. No placeholder juggling, no layout shift.
+              The shell occupies the correct layout before data arrives. No layout shift because there is no placeholder to replace.
             </li>
             <li>
               <strong>Immutable bundle caching.</strong>
-              Production bundles are content-hashed and served with <code>immutable, max-age=31536000</code>. Browsers cache them forever — deploys are instant for returning visitors.
+              Production bundles are content-hashed and served with <code>immutable, max-age=31536000</code>. Returning visitors pay no JS cost on deploy.
             </li>
           </ul>
         </div>
@@ -274,20 +274,20 @@ export default {
               </svg>
             </div>
             <h2>Safe by design</h2>
-            <p>Security is not a plugin or a checklist in Pulse — it is part of the response pipeline. Every page ships the headers most frameworks leave to the developer to remember.</p>
+            <p>Security is not a plugin in Pulse — it is part of the response pipeline. Every response ships the headers most frameworks leave to the developer to remember to add.</p>
           </div>
           <ul class="usp-points">
             <li>
               <strong>Security headers on every response.</strong>
-              <code>X-Frame-Options</code>, <code>X-Content-Type-Options</code>, <code>Referrer-Policy</code>, <code>Permissions-Policy</code>, <code>Cross-Origin-Opener-Policy</code> — all set automatically, including on 404 and 500 pages.
+              <code>X-Frame-Options</code>, <code>X-Content-Type-Options</code>, <code>Referrer-Policy</code>, <code>Permissions-Policy</code>, <code>Cross-Origin-Opener-Policy</code> — set automatically, including on 404 and 500 pages.
             </li>
             <li>
               <strong>Declarative state constraints.</strong>
-              <code>constraints</code> enforce min/max bounds on state after every mutation. The value can never go out of range regardless of what the client sends.
+              <code>constraints</code> enforce min/max bounds on state after every mutation. Values can never go out of range regardless of what the client sends.
             </li>
             <li>
               <strong>Co-located validation.</strong>
-              Validation rules live next to the state they guard. The agent can see what is being validated and why, in one place.
+              Validation rules live next to the state they guard. Easy to read, easy to review, impossible to misplace.
             </li>
             <li>
               <strong>Guard before data.</strong>
@@ -314,16 +314,16 @@ export default {
               The server is pure Node.js HTTP. No Express, no Fastify, no React. Nothing to add to <code>package.json</code> to run a production server.
             </li>
             <li>
-              <strong>No production build step.</strong>
-              <code>node server.js</code> is production. The build step is only needed to generate content-hashed client bundles — the server runs without it in dev.
+              <strong>No server build step.</strong>
+              <code>node server.js</code> is production. The optional build step generates content-hashed client bundles — the server runs without it.
             </li>
             <li>
               <strong>esbuild only in development.</strong>
-              The one dev dependency that compiles client bundles is esbuild. Fast, no plugins to configure, never part of the production runtime.
+              The one dev dependency that compiles client bundles is esbuild. Fast, zero plugins to configure, never part of the production runtime.
             </li>
             <li>
-              <strong>No framework upgrades breaking your app.</strong>
-              Because the spec is a plain JS object with no framework imports in page files, there is no framework API surface to break across versions.
+              <strong>No breaking upgrades.</strong>
+              Page files have no framework imports. The spec is a plain JS object. There is no framework API surface in your code to break across versions.
             </li>
           </ul>
         </div>
@@ -381,15 +381,15 @@ export default {
       </section>` : ''}
 
       <section class="home-cta">
-        <h2>The spec is the contract.<br>Your agent fills it in.</h2>
+        <h2>One format. Every page. Production ready.</h2>
         <ul class="home-cta-checks">
-          <li>Writes the spec</li>
-          <li>Validates against the schema</li>
-          <li>Checks Lighthouse — desktop and mobile</li>
-          <li>Runs the tests</li>
-          <li>Ships production quality</li>
+          <li>One spec object per page — always valid, always readable</li>
+          <li>Streaming SSR and security headers, zero configuration</li>
+          <li>100 Lighthouse built into the architecture</li>
+          <li>Works with AI agents — and without them</li>
+          <li>MIT licensed, zero runtime dependencies</li>
         </ul>
-        <p>MIT licensed and available now. Production quality is not the goal. It is the starting point.</p>
+        <p>Pulse is in early access. The goal is not to compete on features — it is to eliminate the class of problems that come from having too many of them.</p>
         <div class="home-cta-actions">
           <a href="/getting-started" class="btn-primary">Get Started</a>
           <a href="/spec" class="btn-secondary">Read the Spec</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "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.2
+0.8.0

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)