@invisibleloop/pulse 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # Pulse
 
-**A spec-first, AI-native web framework.** Early access — v0.1.30.
+**A spec-first, AI-native web framework.** Early access.
 
 Write a plain JavaScript object that describes what a page does. Pulse handles routing, SSR, hydration, client-side navigation, compression, security headers, and caching automatically.
 

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

@@ -1 +1 @@
-0.1.38
+0.2.2

package/docs/public/docs.css

@@ -1157,8 +1157,10 @@ a:hover {
 }
 
 .demo-preview--col .demo-preview-inner {
-  flex-direction: column;
-  align-items: stretch;
+  display: block;
+}
+.demo-preview--col .demo-preview-inner > * + * {
+  margin-top: 0.75rem;
 }
 
 .demo-preview--scroll .demo-preview-inner {

package/docs/public/img/placeholder-landscape.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 450" role="img" aria-label="Placeholder image">
+  <defs>
+    <linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#0d1b2e"/>
+      <stop offset="100%" stop-color="#1a3a5c"/>
+    </linearGradient>
+    <linearGradient id="ground" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#1a2e1a"/>
+      <stop offset="100%" stop-color="#0d1a0d"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="450" fill="url(#sky)"/>
+  <circle cx="640" cy="100" r="55" fill="#f5c542" opacity=".15"/>
+  <circle cx="640" cy="100" r="40" fill="#f5c542" opacity=".2"/>
+  <polygon points="0,300 120,180 240,260 320,160 440,240 560,140 680,210 800,170 800,450 0,450" fill="url(#ground)"/>
+  <polygon points="0,310 100,270 200,300 320,260 440,290 560,255 680,280 800,260 800,450 0,450" fill="#0f200f" opacity=".7"/>
+  <rect width="800" height="450" fill="#1a1a2e" opacity=".1"/>
+</svg>

package/docs/public/img/placeholder-square.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" role="img" aria-label="Placeholder image">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#1a1a2e"/>
+      <stop offset="100%" stop-color="#0d0d1a"/>
+    </linearGradient>
+  </defs>
+  <rect width="400" height="400" fill="url(#bg)"/>
+  <circle cx="200" cy="155" r="72" fill="#2a2a3e"/>
+  <circle cx="200" cy="155" r="58" fill="#3a3a50"/>
+  <circle cx="200" cy="140" r="35" fill="#4a4a62"/>
+  <ellipse cx="200" cy="320" rx="110" ry="70" fill="#2a2a3e"/>
+  <ellipse cx="200" cy="310" rx="90" ry="58" fill="#3a3a50"/>
+</svg>

package/docs/public/img/placeholder-tall.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600" role="img" aria-label="Placeholder image">
+  <defs>
+    <linearGradient id="sea" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#0d2a4a"/>
+      <stop offset="100%" stop-color="#051520"/>
+    </linearGradient>
+    <linearGradient id="sky2" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#0d1b2e"/>
+      <stop offset="100%" stop-color="#1a3a5c"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="600" fill="url(#sky2)"/>
+  <rect x="0" y="320" width="800" height="280" fill="url(#sea)"/>
+  <rect x="0" y="310" width="800" height="20" fill="#0a2a3a" opacity=".6"/>
+  <rect x="120" y="200" width="60" height="120" fill="#1e2e3e"/>
+  <rect x="200" y="170" width="80" height="150" fill="#1a2a3a"/>
+  <rect x="300" y="210" width="50" height="110" fill="#1e2e3e"/>
+  <rect x="380" y="185" width="90" height="135" fill="#1a2a3a"/>
+  <rect x="490" y="220" width="55" height="100" fill="#1e2e3e"/>
+  <rect x="570" y="195" width="70" height="125" fill="#1a2a3a"/>
+  <path d="M0,320 Q200,300 400,315 Q600,330 800,310 L800,340 Q600,355 400,340 Q200,325 0,345Z" fill="#0d2535" opacity=".5"/>
+</svg>

package/docs/public/pulse-ui.css

@@ -774,6 +774,21 @@ hr.ui-divider {
 }
 .ui-hero--left .ui-hero-actions { justify-content: flex-start; }
 
+/* Split (text + image) */
+.ui-hero--split { text-align: left; }
+.ui-hero--split .ui-hero-inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 3rem;
+  align-items: center;
+}
+.ui-hero--split .ui-hero-actions { justify-content: flex-start; }
+.ui-hero--split .ui-hero-media { display: flex; align-items: center; justify-content: center; }
+.ui-hero--split .ui-hero-media img { width: 100%; height: auto; border-radius: var(--ui-radius, 8px); display: block; }
+.ui-hero--media-left .ui-hero-media { order: -1; }
+
 /* ─── Testimonial ────────────────────────────────────────────────────────── */
 .ui-testimonial {
   background:    var(--ui-surface, var(--surface, #111116));
@@ -1313,6 +1328,8 @@ hr.ui-divider {
   .ui-hero { padding: 3rem 1.25rem; }
   .ui-hero-title { font-size: 2rem; }
   .ui-hero-subtitle { font-size: 1rem; }
+  .ui-hero--split .ui-hero-inner { grid-template-columns: 1fr; }
+  .ui-hero--media-left .ui-hero-media { order: 0; }
 
   .ui-nav-links  { display: none; }
   .ui-nav-burger { display: flex; }
@@ -2529,7 +2546,7 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 .ui-image-img--cover {
   display:    block;
   width:      100%;
-  height:     auto;
+  height:     100%;
   object-fit: cover;
 }
 .ui-image-img {

package/docs/server.js

@@ -191,5 +191,8 @@ createServer(
     port:         process.env.PORT ? Number(process.env.PORT) : 4000,
     staticDir:    new URL('./public', import.meta.url).pathname,
     defaultCache: true,
+    csp: {
+      'img-src': ['https://picsum.photos', 'https://images.unsplash.com'],
+    },
   }
 )

package/docs/src/pages/components/hero.js

@@ -13,12 +13,30 @@ export default {
     styles: ['/pulse-ui.css', '/docs.css'],
   },
   state: {},
-  view: () => renderComponentPage({
+  view: () => {
+    const placeholderImg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400" style="width:100%;height:auto;border-radius:var(--ui-radius,8px);display:block" role="img" aria-label="Placeholder image">
+  <rect width="600" height="400" fill="#111116" rx="8"/>
+  <rect x="24" y="24" width="552" height="32" rx="6" fill="#1a1a22"/>
+  <circle cx="44" cy="40" r="6" fill="#ff5f57"/><circle cx="64" cy="40" r="6" fill="#febc2e"/><circle cx="84" cy="40" r="6" fill="#28c840"/>
+  <rect x="24" y="72" width="552" height="200" rx="6" fill="#1a1a22"/>
+  <rect x="40" y="92" width="200" height="12" rx="3" fill="#2a2a35"/>
+  <rect x="40" y="116" width="300" height="8" rx="3" fill="#222228"/>
+  <rect x="40" y="132" width="260" height="8" rx="3" fill="#222228"/>
+  <rect x="40" y="148" width="280" height="8" rx="3" fill="#222228"/>
+  <rect x="40" y="176" width="120" height="32" rx="6" fill="#9b8dff" opacity=".9"/>
+  <rect x="24" y="288" width="264" height="88" rx="6" fill="#1a1a22"/>
+  <rect x="312" y="288" width="264" height="88" rx="6" fill="#1a1a22"/>
+  <rect x="40" y="304" width="100" height="8" rx="3" fill="#2a2a35"/>
+  <rect x="40" y="320" width="140" height="6" rx="3" fill="#222228"/>
+  <rect x="328" y="304" width="100" height="8" rx="3" fill="#2a2a35"/>
+  <rect x="328" y="320" width="120" height="6" rx="3" fill="#222228"/>
+</svg>`
+    return renderComponentPage({
     currentHref: '/components/hero',
     prev,
     next,
     name: 'hero',
-    description: 'Full-width hero section. The <code>actions</code> slot accepts any combination of <code>button()</code> and <code>appBadge()</code> calls. Set <code>align: \'left\'</code> for a split-layout hero. Use <code>size: \'sm\'</code> for inner-page headers that don\'t need the full vertical padding.',
+    description: 'Full-width hero section. Pass <code>image</code> HTML to activate the split layout — text on one side, image on the other. Use <code>imageAlign</code> to swap sides. Set <code>align: \'left\'</code> for left-aligned text without an image. Use <code>size: \'sm\'</code> for inner-page headers.',
     content: `
       ${demo(
         hero({
@@ -36,6 +54,41 @@ export default {
 })`
       )}
 
+      ${demo(
+        hero({
+          eyebrow:  'Split layout',
+          title:    'Text left, image right',
+          subtitle: 'Pass an image slot to activate the split layout. The text sits on the left, image on the right.',
+          actions:  appBadge({ store: 'apple', href: '#' }) + ' ' + appBadge({ store: 'google', href: '#' }),
+          image:    placeholderImg,
+        }),
+        `hero({
+  eyebrow:  'Split layout',
+  title:    'Text left, image right',
+  subtitle: 'Pass an image slot to activate the split layout.',
+  actions:  appBadge({ store: 'apple',  href: appStoreUrl }) +
+            appBadge({ store: 'google', href: playStoreUrl }),
+  image:    \`<img src="\${screenshotUrl}" alt="Product screenshot">\`,
+})`
+      )}
+
+      ${demo(
+        hero({
+          eyebrow:    'Split layout',
+          title:      'Image left, text right',
+          subtitle:   'Set imageAlign: \'left\' to put the image on the left and text on the right.',
+          image:      placeholderImg,
+          imageAlign: 'left',
+        }),
+        `hero({
+  eyebrow:    'Split layout',
+  title:      'Image left, text right',
+  subtitle:   'Set imageAlign to swap sides.',
+  image:      \`<img src="\${screenshotUrl}" alt="Product screenshot">\`,
+  imageAlign: 'left',
+})`
+      )}
+
       ${demo(
         hero({
           title:    'Blog',
@@ -52,14 +105,17 @@ export default {
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
-          ['<code>eyebrow</code>',  'string',        '—',         'Small label above the title'],
-          ['<code>title</code>',    'string',        '—',         ''],
-          ['<code>subtitle</code>', 'string',        '—',         ''],
-          ['<code>actions</code>',  'string (HTML)', '—',         'Raw HTML slot'],
-          ['<code>align</code>',    'string',        "'center'",  "'center' or 'left'"],
-          ['<code>size</code>',     'string',        "'md'",      "'md' (5rem padding) or 'sm' (2.5rem top, no bottom) — use sm for inner-page headers"],
+          ['<code>eyebrow</code>',     'string',        '—',          'Small label above the title'],
+          ['<code>title</code>',       'string',        '—',          ''],
+          ['<code>subtitle</code>',    'string',        '—',          ''],
+          ['<code>actions</code>',     'string (HTML)', '—',          'Raw HTML slot — buttons, badges, etc.'],
+          ['<code>image</code>',       'string (HTML)', '—',          'Raw HTML slot — activates split layout when set'],
+          ['<code>imageAlign</code>',  'string',        "'right'",    "'right' (text left) or 'left' (text right) — only applies when image is set"],
+          ['<code>align</code>',       'string',        "'center'",   "'center' or 'left' — text alignment when no image"],
+          ['<code>size</code>',        'string',        "'md'",       "'md' (5rem padding) or 'sm' (2.5rem top, no bottom) — use sm for inner-page headers"],
         ]
       )}
     `,
-  }),
+  })
+  },
 }

package/docs/src/pages/components/image.js

@@ -24,14 +24,14 @@ export default {
       <h2 class="doc-h2" id="ratio">With aspect ratio</h2>
       <p>Set <code>ratio</code> to constrain the image to a fixed aspect ratio. The image fills the crop area with <code>object-fit: cover</code>.</p>
       ${demo(
-        uiImage({ src: 'https://picsum.photos/seed/pulse1/800/450', alt: 'Mountain landscape at dusk', ratio: '16/9' }),
+        uiImage({ src: '/img/placeholder-landscape.svg', alt: 'Mountain landscape at dusk', ratio: '16/9' }),
         `uiImage({ src: '/img/photo.jpg', alt: 'Mountain landscape at dusk', ratio: '16/9' })`,
         { col: true }
       )}
 
       <h2 class="doc-h2" id="rounded">Square and rounded</h2>
       ${demo(
-        `<div style="max-width:200px;margin:0 auto">${uiImage({ src: 'https://picsum.photos/seed/pulse2/400/400', alt: 'Profile photo', ratio: '1/1', rounded: true })}</div>`,
+        `<div style="max-width:200px;margin:0 auto">${uiImage({ src: '/img/placeholder-square.svg', alt: 'Profile photo', ratio: '1/1', rounded: true })}</div>`,
         `uiImage({ src: '/img/avatar.jpg', alt: 'Profile photo', ratio: '1/1', rounded: true })`,
         { col: true }
       )}
@@ -39,7 +39,7 @@ export default {
       <h2 class="doc-h2" id="caption">With caption</h2>
       ${demo(
         uiImage({
-          src:     'https://picsum.photos/seed/pulse3/800/600',
+          src:     '/img/placeholder-tall.svg',
           alt:     'Aerial view of a coastal town',
           ratio:   '4/3',
           caption: 'Aerial view of Porto, Portugal. Photo by João Silva.',

package/docs/src/pages/home.js

@@ -69,7 +69,7 @@ export default {
         <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. Designed for AI agents.</p>
+        <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>
         <div class="hero-ctas">
           <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.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.2
+0.2.4

package/public/pulse-ui.css

@@ -774,6 +774,21 @@ hr.ui-divider {
 }
 .ui-hero--left .ui-hero-actions { justify-content: flex-start; }
 
+/* Split (text + image) */
+.ui-hero--split { text-align: left; }
+.ui-hero--split .ui-hero-inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 3rem;
+  align-items: center;
+}
+.ui-hero--split .ui-hero-actions { justify-content: flex-start; }
+.ui-hero--split .ui-hero-media { display: flex; align-items: center; justify-content: center; }
+.ui-hero--split .ui-hero-media img { width: 100%; height: auto; border-radius: var(--ui-radius, 8px); display: block; }
+.ui-hero--media-left .ui-hero-media { order: -1; }
+
 /* ─── Testimonial ────────────────────────────────────────────────────────── */
 .ui-testimonial {
   background:    var(--ui-surface, var(--surface, #111116));
@@ -1313,6 +1328,8 @@ hr.ui-divider {
   .ui-hero { padding: 3rem 1.25rem; }
   .ui-hero-title { font-size: 2rem; }
   .ui-hero-subtitle { font-size: 1rem; }
+  .ui-hero--split .ui-hero-inner { grid-template-columns: 1fr; }
+  .ui-hero--media-left .ui-hero-media { order: 0; }
 
   .ui-nav-links  { display: none; }
   .ui-nav-burger { display: flex; }
@@ -2529,7 +2546,7 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
 .ui-image-img--cover {
   display:    block;
   width:      100%;
-  height:     auto;
+  height:     100%;
   object-fit: cover;
 }
 .ui-image-img {

package/scripts/build.js

@@ -51,11 +51,48 @@ function stripServerOnlyKeys(source) {
  * from a JS source string. Uses a character-level scanner to correctly handle
  * nested structures, string literals, template literals, and function expressions.
  */
+/**
+ * Returns true if `pos` in `source` falls inside a string or template literal.
+ * Used to avoid stripping keys that appear inside code-example strings in docs pages.
+ */
+function isInsideString(source, pos) {
+  let i = 0
+  const stack = []  // stack of open delimiters: '"' | "'" | '`' | '{'  ('{' = template expression)
+  while (i < pos) {
+    const c = source[i]
+    const top = stack[stack.length - 1]
+    if (top === '"' || top === "'") {
+      if (c === '\\') { i += 2; continue }
+      if (c === top)  { stack.pop() }
+      i++; continue
+    }
+    if (top === '`') {
+      if (c === '\\') { i += 2; continue }
+      if (c === '`')  { stack.pop(); i++; continue }
+      if (c === '$' && source[i + 1] === '{') { stack.push('{'); i += 2; continue }
+      i++; continue
+    }
+    if (top === '{') {
+      // inside a template expression — track nested braces
+      if (c === '{') { stack.push('{'); i++; continue }
+      if (c === '}') { stack.pop(); i++; continue }
+      if (c === '"' || c === "'" || c === '`') { stack.push(c); i++; continue }
+      i++; continue
+    }
+    // top-level
+    if (c === '"' || c === "'" || c === '`') { stack.push(c) }
+    i++
+  }
+  return stack.length > 0
+}
+
 function removeObjectKey(source, key) {
   const keyRe = new RegExp(`^([ \\t]*)(${key})([ \\t]*:)`, 'gm')
   let match
 
   while ((match = keyRe.exec(source)) !== null) {
+    if (isInsideString(source, match.index)) { continue }
+
     const removeStart = match.index                    // start of indentation
     const afterColon  = match.index + match[0].length // character after ':'
 

package/scripts/strip-server.test.js

@@ -14,10 +14,40 @@ function stripServerOnlyKeys(source) {
   return source
 }
 
+function isInsideString(source, pos) {
+  let i = 0
+  const stack = []
+  while (i < pos) {
+    const c = source[i]
+    const top = stack[stack.length - 1]
+    if (top === '"' || top === "'") {
+      if (c === '\\') { i += 2; continue }
+      if (c === top)  { stack.pop() }
+      i++; continue
+    }
+    if (top === '`') {
+      if (c === '\\') { i += 2; continue }
+      if (c === '`')  { stack.pop(); i++; continue }
+      if (c === '$' && source[i + 1] === '{') { stack.push('{'); i += 2; continue }
+      i++; continue
+    }
+    if (top === '{') {
+      if (c === '{') { stack.push('{'); i++; continue }
+      if (c === '}') { stack.pop(); i++; continue }
+      if (c === '"' || c === "'" || c === '`') { stack.push(c); i++; continue }
+      i++; continue
+    }
+    if (c === '"' || c === "'" || c === '`') { stack.push(c) }
+    i++
+  }
+  return stack.length > 0
+}
+
 function removeObjectKey(source, key) {
   const keyRe = new RegExp(`^([ \\t]*)(${key})([ \\t]*:)`, 'gm')
   let match
   while ((match = keyRe.exec(source)) !== null) {
+    if (isInsideString(source, match.index)) { continue }
     const removeStart = match.index
     const afterColon  = match.index + match[0].length
     let pos = afterColon
@@ -181,6 +211,16 @@ test('server with deeply nested template literal in view is not affected',
   'export default {\n  view: (s, srv) => `<ul>${srv.items.map(i => `<li>${i}</li>`).join(\'\')}</ul>`\n}'
 )
 
+test('render: inside a template literal string (docs code example) is not stripped',
+  'export default {\n  route: \'/auth\',\n  view: () => `${highlight(`export default {\n  render: (ctx) => ctx.user\n}`)}`\n}',
+  'export default {\n  route: \'/auth\',\n  view: () => `${highlight(`export default {\n  render: (ctx) => ctx.user\n}`)}`\n}'
+)
+
+test('server: inside a double-quoted string is not stripped',
+  'export default {\n  route: \'/docs\',\n  view: () => "<pre>server: { data: async () => {} }</pre>"\n}',
+  'export default {\n  route: \'/docs\',\n  view: () => "<pre>server: { data: async () => {} }</pre>"\n}'
+)
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)

package/src/runtime/navigate.js

@@ -22,10 +22,16 @@ export function initNavigation(root, mountFn) {
   // Track the current mount instance so we can destroy it (and its store
   // subscription) before mounting the next page.
   let currentMount = null
+  let currentNavController = null
 
   async function navigate(path, push) {
+    // Cancel any in-flight navigation before starting a new one
+    currentNavController?.abort()
+    const controller = new AbortController()
+    currentNavController = controller
+
     try {
-      const res = await fetch(path, { headers: { 'X-Pulse-Navigate': 'true' } })
+      const res = await fetch(path, { headers: { 'X-Pulse-Navigate': 'true' }, signal: controller.signal })
 
       if (!res.ok) { location.href = path; return }
 
@@ -34,6 +40,10 @@ export function initNavigation(root, mountFn) {
       if (ct.includes('application/x-ndjson')) {
         // Streaming nav response — apply chunks progressively as they arrive
         const reader  = res.body.getReader()
+        // Explicitly cancel the reader when this navigation is superseded — aborting
+        // the fetch signal does not reliably cancel an in-progress body stream reader
+        // in all browsers, so we do it explicitly.
+        controller.signal.addEventListener('abort', () => reader.cancel(), { once: true })
         const decoder = new TextDecoder()
         let buf              = ''
         let hydratePath      = null
@@ -87,6 +97,9 @@ export function initNavigation(root, mountFn) {
         }
         if (buf) await processLine(buf)
 
+        // Bail out if a newer navigation superseded us while we were streaming
+        if (controller.signal.aborted) return
+
         runScripts(root)
         document.dispatchEvent(new CustomEvent('pulse:navigate'))
 
@@ -102,6 +115,8 @@ export function initNavigation(root, mountFn) {
         // Legacy JSON response (server running with stream: false)
         const { html, title, styles, scripts, hydrate, serverState, storeState } = await res.json()
 
+        if (controller.signal.aborted) return
+
         if (storeState && window.__updatePulseStore__) {
           window.__updatePulseStore__(storeState)
         }
@@ -126,7 +141,8 @@ export function initNavigation(root, mountFn) {
         scrollAndFocus(root)
       }
 
-    } catch {
+    } catch (err) {
+      if (err?.name === 'AbortError') return
       location.href = path
     }
   }

package/src/server/index.js

@@ -601,8 +601,12 @@ export function createServer(specs, options = {}) {
 
       // Client-side navigation request — return JSON fragment (or NDJSON stream), not a full document
       if (req.headers['x-pulse-navigate'] === 'true') {
-        if (stream) {
-          await handleNavStreamResponse(spec, ctx, res)
+        // Only use NDJSON streaming when there are actual deferred segments to stream.
+        // For simple pages (no spec.stream.deferred), the JSON path is faster and does
+        // not hold the HTTP/1.1 connection open for the duration of the stream.
+        const hasDeferred = stream && spec.stream?.deferred?.length > 0
+        if (hasDeferred) {
+          await handleNavStreamResponse(spec, ctx, req, res)
         } else {
           await handleNavResponse(spec, ctx, res, dev)
         }
@@ -730,7 +734,7 @@ async function handleNavResponse(spec, ctx, res, dev = false) {
  * as their server data resolves. The browser applies chunks progressively,
  * showing shell content without waiting for slower deferred fetchers.
  */
-async function handleNavStreamResponse(spec, ctx, res) {
+async function handleNavStreamResponse(spec, ctx, req, res) {
   const meta = resolveMeta(spec.meta, ctx)
 
   res.writeHead(200, {
@@ -743,6 +747,12 @@ async function handleNavStreamResponse(spec, ctx, res) {
   const navStream = renderToNavStream(spec, ctx, meta)
   const reader    = navStream.getReader()
 
+  // If the client disconnects (e.g. user navigated away before the stream ended),
+  // cancel the reader immediately so the HTTP connection is freed rather than held
+  // open until the navStream finishes naturally.
+  const onClose = () => reader.cancel()
+  req.on('close', onClose)
+
   try {
     while (true) {
       const { done, value } = await reader.read()
@@ -752,6 +762,7 @@ async function handleNavStreamResponse(spec, ctx, res) {
   } catch {
     // Headers already sent — cannot change status, just end cleanly
   } finally {
+    req.off('close', onClose)
     res.end()
   }
 }

package/src/ui/hero.js

@@ -2,36 +2,60 @@
  * Pulse UI — Hero
  *
  * Full-width hero section with eyebrow, headline, subheadline, and action slot.
+ * Pass `image` HTML to activate the split layout — text on one side, image on the other.
  *
  * @param {object}  opts
- * @param {string}  opts.eyebrow   - Small label above the title (e.g. "Now available")
- * @param {string}  opts.title     - Main headline
- * @param {string}  opts.subtitle  - Supporting text beneath the headline
- * @param {string}  opts.actions   - Raw HTML slot — typically button() or appBadge() calls
- * @param {'center'|'left'} opts.align - Text alignment (default: 'center')
- * @param {'md'|'sm'} opts.size   - Vertical padding size: 'md' (default, 5rem) or 'sm' (2.5rem)
+ * @param {string}  opts.eyebrow      - Small label above the title (e.g. "Now available")
+ * @param {string}  opts.title        - Main headline
+ * @param {string}  opts.subtitle     - Supporting text beneath the headline
+ * @param {string}  opts.actions      - Raw HTML slot — typically button() or appBadge() calls
+ * @param {string}  opts.image        - Raw HTML slot for the image (activates split layout)
+ * @param {'right'|'left'} opts.imageAlign - Which side the image sits on (default: 'right')
+ * @param {'center'|'left'} opts.align    - Text alignment when no image (default: 'center')
+ * @param {'md'|'sm'} opts.size           - Vertical padding: 'md' (default, 5rem) or 'sm' (2.5rem)
  * @param {string}  opts.class
  */
 
 import { escHtml as e } from '../html.js'
 
 export function hero({
-  eyebrow    = '',
-  title      = '',
-  subtitle   = '',
-  actions    = '',
-  align      = 'center',
-  size       = 'md',
-  class: cls = '',
+  eyebrow     = '',
+  title       = '',
+  subtitle    = '',
+  actions     = '',
+  image       = '',
+  imageAlign  = 'right',
+  align       = 'center',
+  size        = 'md',
+  class: cls  = '',
 } = {}) {
-  const classes = ['ui-hero', align === 'left' && 'ui-hero--left', size === 'sm' && 'ui-hero--sm', cls].filter(Boolean).join(' ')
+  const split = Boolean(image)
+  const classes = [
+    'ui-hero',
+    split ? 'ui-hero--split' : align === 'left' && 'ui-hero--left',
+    split && imageAlign === 'left' && 'ui-hero--media-left',
+    size === 'sm' && 'ui-hero--sm',
+    cls,
+  ].filter(Boolean).join(' ')
 
-  return `<section class="${e(classes)}">
-  <div class="ui-hero-inner">
+  const content = `
     ${eyebrow  ? `<p class="ui-hero-eyebrow">${e(eyebrow)}</p>` : ''}
     ${title    ? `<h1 class="ui-hero-title">${e(title)}</h1>` : ''}
     ${subtitle ? `<p class="ui-hero-subtitle">${e(subtitle)}</p>` : ''}
-    ${actions  ? `<div class="ui-hero-actions">${actions}</div>` : ''}
+    ${actions  ? `<div class="ui-hero-actions">${actions}</div>` : ''}`
+
+  if (split) {
+    return `<section class="${e(classes)}">
+  <div class="ui-hero-inner">
+    <div class="ui-hero-content">${content}
+    </div>
+    <div class="ui-hero-media">${image}</div>
+  </div>
+</section>`
+  }
+
+  return `<section class="${e(classes)}">
+  <div class="ui-hero-inner">${content}
   </div>
 </section>`
 }

package/src/ui/uiimage.js

@@ -49,8 +49,8 @@ export function uiImage({
 
   if (ratio) {
     return `<figure class="${e(figClasses)}"${maxWidthStyle}>
-  <div class="ui-image-crop">
-    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img--cover" style="aspect-ratio:${e(ratio)}"${widthAttr}${heightAttr} loading="lazy" decoding="async">
+  <div class="ui-image-crop" style="aspect-ratio:${e(ratio)}">
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-image-img--cover"${widthAttr}${heightAttr} loading="lazy" decoding="async">
   </div>
   ${captionHtml}
 </figure>`