@invisibleloop/pulse 0.1.39 → 0.2.0

package/src/runtime/runtime.test.js

@@ -254,6 +254,30 @@ test('constraints on nested paths', () => {
   assert(instance.getState().slider.value === 100, `Expected 100, got ${instance.getState().slider.value}`)
 })
 
+test('render is skipped when mutation produces no state change', () => {
+  const el = new FakeElement()
+  let renderCount = 0
+  const spec = {
+    route: '/nochange',
+    state: { count: 10 },
+    constraints: { count: { min: 0, max: 10 } },
+    view: (s) => { renderCount++; return `<span>${s.count}</span>` },
+    mutations: {
+      increment: (state) => ({ count: state.count + 1 }),  // clamped to 10
+      noop:      ()      => ({}),                           // empty partial
+    }
+  }
+  const instance = mount(spec, el)
+  renderCount = 0  // reset after initial render
+
+  instance.dispatch('increment')  // already at max — state unchanged
+  instance.dispatch('noop')       // empty partial — state unchanged
+  assert(renderCount === 0, `Expected 0 renders for no-change dispatches, got ${renderCount}`)
+
+  instance.dispatch('increment') // state unchanged by constraint
+  assert(instance.getState().count === 10)
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nActions\n')

package/src/runtime/ssr.js

@@ -90,27 +90,38 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
   // Run async — don't await here, stream is returned immediately
   ;(async () => {
     try {
-      // Resolve shell server data (only what shell segments need)
-      const shellServerState = await resolveServerStateForSegments(spec, ctx, shell)
+      const timeout = ctx.fetcherTimeout ?? null
+
+      // Eagerly start ALL fetcher promises so shell and deferred run in parallel.
+      // Each fetcher runs at most once — deferred-scoped fetchers fire immediately
+      // rather than waiting for the shell to finish, and shared fetchers are
+      // never called twice even if referenced by multiple segments.
+      const fetcherCache = new Map()
+      if (spec.server) {
+        for (const [key, fn] of Object.entries(spec.server)) {
+          fetcherCache.set(key, withTimeout(fn(ctx), timeout, key))
+        }
+      }
 
-      // Merge declared store keys — store keys lose to page-level keys
+      // Await only the fetchers the shell segments need
+      const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
       const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
 
-      // Write shell immediately
+      // Write shell immediately — deferred fetchers may still be in-flight
       const shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
       controller.enqueue(encode(shellHtml))
 
-      // Write deferred segments as they resolve
       if (deferred.length > 0) {
-        // Enqueue placeholder elements so the browser knows where to insert
+        // Placeholders so the browser knows where to insert deferred content
         const placeholders = deferred
           .map(key => `<pulse-deferred id="pd-${key}"></pulse-deferred>`)
           .join('')
         controller.enqueue(encode(placeholders))
 
-        // Resolve and stream each deferred segment
+        // Stream each deferred segment as soon as its own fetchers resolve.
+        // Promise.all runs them concurrently — the fastest segment wins.
         await Promise.all(deferred.map(async (key) => {
-          const segServerState = await resolveServerStateForSegments(spec, ctx, [key])
+          const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
           const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
           const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
 
@@ -129,14 +140,114 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
         }))
       }
 
-      // Inject server state so the client hydration can read it without
-      // a second request — mirrors what wrapDocument does for the string path.
-      // Emit when there is page server data or store data to serialise.
-      if (Object.keys(mergedShellState).length > 0) {
-        const script = `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedShellState)};</script>`
-        controller.enqueue(encode(script))
+      // Collect all resolved server state for client hydration.
+      // All promises are already settled by the time we reach here.
+      const allServerState = fetcherCache.size > 0
+        ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
+        : {}
+      const mergedAllState = mergeStoreKeys(spec, allServerState, ctx.store)
+      if (Object.keys(mergedAllState).length > 0) {
+        controller.enqueue(encode(
+          `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
+        ))
+      }
+
+      controller.close()
+    } catch (err) {
+      controller.error(err)
+    }
+  })()
+
+  return stream
+}
+
+// ---------------------------------------------------------------------------
+// renderToNavStream
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a spec to a stream of newline-delimited JSON (NDJSON) messages
+ * for use during client-side navigation. Sends four message types:
+ *
+ *   { type: 'meta',     title, styles, scripts, hydrate }  — immediately
+ *   { type: 'html',     html, deferred }                   — shell ready
+ *   { type: 'deferred', id, html }                         — each deferred segment
+ *   { type: 'done',     serverState, storeState }          — all data resolved
+ *
+ * The client (navigate.js) reads lines as they arrive:
+ *   - meta  → updates title + stylesheets
+ *   - html  → swaps root.innerHTML (shell), finds <pulse-deferred> placeholders
+ *   - deferred → replaces the matching placeholder with rendered HTML
+ *   - done  → stores serverState, mounts spec
+ *
+ * @param {import('../spec/schema.js').PulseSpec} spec
+ * @param {Object} [ctx]
+ * @param {Object} [resolvedMeta]  - Pre-resolved meta (title, styles, scripts)
+ * @returns {ReadableStream}
+ */
+export function renderToNavStream(spec, ctx = {}, resolvedMeta = {}) {
+  assertValidSpec(spec)
+
+  const { shell, deferred } = getStreamOrder(spec)
+  const clientState = { ...spec.state }
+
+  let controller
+  const stream = new ReadableStream({ start(c) { controller = c } })
+
+  ;(async () => {
+    try {
+      const timeout = ctx.fetcherTimeout ?? null
+      const writeLine = (obj) => controller.enqueue(encode(JSON.stringify(obj) + '\n'))
+
+      // Eagerly start ALL fetcher promises so shell and deferred run in parallel
+      const fetcherCache = new Map()
+      if (spec.server) {
+        for (const [key, fn] of Object.entries(spec.server)) {
+          fetcherCache.set(key, withTimeout(fn(ctx), timeout, key))
+        }
+      }
+
+      // 1. Send meta immediately — no data fetching needed
+      writeLine({
+        type:    'meta',
+        title:   resolvedMeta.title   || 'Pulse',
+        styles:  resolvedMeta.styles  || [],
+        scripts: resolvedMeta.scripts || [],
+        hydrate: spec.hydrate || null,
+      })
+
+      // 2. Await shell fetchers then send shell HTML
+      const shellServerState = await awaitFetchersForSegments(spec, shell, fetcherCache)
+      const mergedShellState = mergeStoreKeys(spec, shellServerState, ctx.store)
+      let shellHtml = renderNamedSegments(spec, shell, clientState, mergedShellState)
+
+      // Append <pulse-deferred> placeholders so the client knows where to inject deferred content
+      if (deferred.length > 0) {
+        shellHtml += deferred.map(key => `<pulse-deferred id="pd-${key}"></pulse-deferred>`).join('')
       }
 
+      writeLine({ type: 'html', html: shellHtml, deferred })
+
+      // 3. Stream each deferred segment as soon as its own fetchers resolve
+      await Promise.all(deferred.map(async (key) => {
+        const segServerState = await awaitFetchersForSegments(spec, [key], fetcherCache)
+        const mergedSegState = mergeStoreKeys(spec, segServerState, ctx.store)
+        const segHtml        = renderNamedSegments(spec, [key], clientState, mergedSegState)
+        writeLine({ type: 'deferred', id: key, html: segHtml })
+      }))
+
+      // 4. Collect all resolved server state then send done
+      const allServerState = fetcherCache.size > 0
+        ? Object.fromEntries(await Promise.all([...fetcherCache.entries()].map(async ([k, p]) => [k, await p])))
+        : {}
+      const mergedAll = mergeStoreKeys(spec, allServerState, ctx.store)
+
+      writeLine({
+        type:        'done',
+        serverState: Object.keys(mergedAll).length > 0 ? mergedAll : undefined,
+        storeState:  ctx.store && Object.keys(ctx.store).length > 0 ? ctx.store : undefined,
+      })
+
       controller.close()
     } catch (err) {
       controller.error(err)
@@ -327,20 +438,54 @@ export async function resolveServerState(spec, ctx) {
 }
 
 /**
- * Resolve server data for a specific set of segments only.
- * Used by the streaming renderer to avoid fetching deferred data
- * before the shell is sent.
+ * Await the subset of already-started fetcher promises that the given
+ * segment group needs. Uses spec.stream.scope when declared; falls back
+ * to all fetchers when a segment has no scope annotation.
  *
- * Currently resolves all server state — segment-level data dependencies
- * will be an opt-in annotation in a future iteration.
+ * Fetchers are never started here — they were all started eagerly at the
+ * top of renderToStream via the fetcherCache Map.
  *
  * @param {import('../spec/schema.js').PulseSpec} spec
- * @param {Object} ctx
- * @param {string[]} _segments - Segment keys (reserved for future scoping)
+ * @param {string[]} segmentKeys
+ * @param {Map<string, Promise>} fetcherCache
  * @returns {Promise<Object>}
  */
-async function resolveServerStateForSegments(spec, ctx, _segments) {
-  return resolveServerState(spec, ctx)
+async function awaitFetchersForSegments(spec, segmentKeys, fetcherCache) {
+  if (!spec.server || fetcherCache.size === 0) return {}
+
+  const neededKeys = getScopedFetcherKeys(spec, segmentKeys)
+
+  const entries = await Promise.all(
+    neededKeys
+      .filter(key => fetcherCache.has(key))
+      .map(async key => [key, await fetcherCache.get(key)])
+  )
+
+  return Object.fromEntries(entries)
+}
+
+/**
+ * Return the server fetcher keys needed by a set of segments.
+ * Uses spec.stream.scope when declared. Segments not listed in scope
+ * receive all server keys (safe default — same behaviour as before).
+ *
+ * @param {import('../spec/schema.js').PulseSpec} spec
+ * @param {string[]} segmentKeys
+ * @returns {string[]}
+ */
+function getScopedFetcherKeys(spec, segmentKeys) {
+  if (!spec.server) return []
+
+  const scope = spec.stream?.scope
+  if (!scope) return Object.keys(spec.server)  // no annotation → all fetchers
+
+  const needed = new Set()
+  for (const seg of segmentKeys) {
+    const scoped = scope[seg]
+    if (!scoped) return Object.keys(spec.server)  // unscoped segment → all fetchers
+    for (const key of scoped) needed.add(key)
+  }
+  return [...needed]
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/ssr.test.js

@@ -3,7 +3,7 @@
  * run: node src/runtime/ssr.test.js
  */
 
-import { renderToString, renderToStream, wrapDocument, withTimeout } from './ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, withTimeout } from './ssr.js'
 
 // ---------------------------------------------------------------------------
 // Test runner
@@ -245,6 +245,97 @@ await test('stream does not inject __PULSE_SERVER__ when no server data', async
   assert(!html.includes('__PULSE_SERVER__'), `Should not include empty server state: ${html}`)
 })
 
+await test('each server fetcher runs at most once across all segments', async () => {
+  let callCount = 0
+  const spec = {
+    route: '/dedup',
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed', 'sidebar'],
+    },
+    server: {
+      user: async () => { callCount++; return 'user-data' },
+    },
+    state: {},
+    view: {
+      header:  (s, { user }) => `<header>${user}</header>`,
+      feed:    (s, { user }) => `<feed>${user}</feed>`,
+      sidebar: (s, { user }) => `<aside>${user}</aside>`,
+    }
+  }
+
+  await streamToString(renderToStream(spec))
+  assert(callCount === 1, `Expected fetcher called once, got ${callCount}`)
+})
+
+await test('stream.scope: shell does not wait for deferred-only fetchers', async () => {
+  const spec = {
+    route: '/scoped',
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed'],
+      scope: {
+        header: ['user'],   // fast (10ms)
+        feed:   ['posts'],  // slow (80ms)
+      }
+    },
+    server: {
+      user:  async () => { await new Promise(r => setTimeout(r, 10));  return 'user-data' },
+      posts: async () => { await new Promise(r => setTimeout(r, 80)); return 'posts-data' },
+    },
+    state: {},
+    view: {
+      header: (s, { user })  => `<header>${user}</header>`,
+      feed:   (s, { posts }) => `<main>${posts}</main>`,
+    }
+  }
+
+  const chunks = []
+  const stream = renderToStream(spec)
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let shellTime = null
+  const t0 = Date.now()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    const chunk = decoder.decode(value)
+    if (shellTime === null && chunk.includes('<header>')) shellTime = Date.now() - t0
+    chunks.push(chunk)
+  }
+
+  const fullHtml = chunks.join('')
+  assert(fullHtml.includes('user-data'),  'header should contain user-data')
+  assert(fullHtml.includes('posts-data'), 'feed should contain posts-data')
+  // Shell should arrive ~10ms (user fetcher), not ~80ms (posts fetcher)
+  assert(shellTime !== null && shellTime < 40, `Shell arrived too late: ${shellTime}ms (expected ~10ms)`)
+})
+
+await test('stream.scope: __PULSE_SERVER__ includes state from all scoped fetchers', async () => {
+  const spec = {
+    route: '/scoped-state',
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed'],
+      scope: { header: ['user'], feed: ['posts'] }
+    },
+    server: {
+      user:  async () => ({ name: 'Andy' }),
+      posts: async () => [{ title: 'Hello' }],
+    },
+    state: {},
+    view: {
+      header: (s, { user })  => `<header>${user.name}</header>`,
+      feed:   (s, { posts }) => `<main>${posts[0].title}</main>`,
+    }
+  }
+
+  const html = await streamToString(renderToStream(spec))
+  assert(html.includes('"name":"Andy"'),   `Expected user state serialised: ${html}`)
+  assert(html.includes('"title":"Hello"'), `Expected posts state serialised: ${html}`)
+})
+
 // ---------------------------------------------------------------------------
 
 console.log('\nwrapDocument\n')
@@ -415,6 +506,169 @@ await test('renderToString: resolves normally when fetcher completes within time
   assert(html.includes('quick'), `Expected rendered data, got: ${html}`)
 })
 
+// ---------------------------------------------------------------------------
+// renderToNavStream
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect all NDJSON messages from a renderToNavStream response.
+ * Returns them as an array of parsed objects in arrival order.
+ */
+async function collectNavMessages(stream) {
+  const reader  = stream.getReader()
+  const decoder = new TextDecoder()
+  let buf = ''
+  const messages = []
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buf += decoder.decode(value, { stream: true })
+    const lines = buf.split('\n')
+    buf = lines.pop()
+    for (const line of lines) {
+      if (line.trim()) messages.push(JSON.parse(line))
+    }
+  }
+  if (buf.trim()) messages.push(JSON.parse(buf))
+  return messages
+}
+
+console.log('\nrenderToNavStream\n')
+
+await test('sends meta as the first message with no data fetching', async () => {
+  const spec = {
+    route:   '/nav',
+    state:   {},
+    view:    () => '<main id="main-content">hello</main>',
+    hydrate: '/nav.js',
+  }
+  const stream   = renderToNavStream(spec, {}, { title: 'Nav Page', styles: ['/app.css'] })
+  const messages = await collectNavMessages(stream)
+  const meta     = messages[0]
+  assert(meta.type === 'meta',       `First message should be meta, got ${meta.type}`)
+  assert(meta.title === 'Nav Page',  `Expected title 'Nav Page', got ${meta.title}`)
+  assert(meta.hydrate === '/nav.js', `Expected hydrate '/nav.js', got ${meta.hydrate}`)
+  assert(meta.styles[0] === '/app.css', 'styles should be forwarded')
+})
+
+await test('sends html message with shell content', async () => {
+  const spec = {
+    route: '/nav',
+    state: {},
+    view:  () => '<main id="main-content">shell</main>',
+  }
+  const messages = await collectNavMessages(renderToNavStream(spec))
+  const html     = messages.find(m => m.type === 'html')
+  assert(html, 'should have html message')
+  assert(html.html.includes('shell'), 'html should contain view output')
+})
+
+await test('sends done message with serverState', async () => {
+  const spec = {
+    route:  '/nav',
+    state:  {},
+    server: { items: async () => [1, 2, 3] },
+    view:   (s, srv) => `<main id="main-content">${srv.items.length}</main>`,
+  }
+  const messages  = await collectNavMessages(renderToNavStream(spec))
+  const done      = messages.find(m => m.type === 'done')
+  assert(done, 'should have done message')
+  assert(Array.isArray(done.serverState?.items), 'serverState.items should be present')
+  assert(done.serverState.items.length === 3, 'serverState.items should have 3 entries')
+})
+
+await test('sends deferred messages for each deferred segment', async () => {
+  const spec = {
+    route:  '/nav',
+    state:  {},
+    server: { user: async () => ({ name: 'Alice' }), posts: async () => ['a', 'b'] },
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed'],
+    },
+    view: {
+      header: ()         => '<header>nav</header>',
+      feed:   (s, srv)   => `<aside>${srv.posts.length} posts</aside>`,
+    },
+  }
+  const messages  = await collectNavMessages(renderToNavStream(spec))
+  const types     = messages.map(m => m.type)
+  assert(types[0] === 'meta',     `First should be meta, got ${types[0]}`)
+  assert(types.includes('html'),      'should include html')
+  assert(types.includes('deferred'),  'should include deferred')
+  assert(types[types.length - 1] === 'done', 'last should be done')
+
+  const deferred = messages.find(m => m.type === 'deferred')
+  assert(deferred.id === 'feed',           `Expected deferred id 'feed', got ${deferred.id}`)
+  assert(deferred.html.includes('2 posts'), `Expected feed content, got: ${deferred.html}`)
+})
+
+await test('shell html includes <pulse-deferred> placeholders for deferred segments', async () => {
+  const spec = {
+    route:  '/nav',
+    state:  {},
+    server: { posts: async () => [] },
+    stream: { shell: ['header'], deferred: ['feed'] },
+    view: {
+      header: () => '<header>top</header>',
+      feed:   () => '<aside>feed</aside>',
+    },
+  }
+  const messages = await collectNavMessages(renderToNavStream(spec))
+  const html     = messages.find(m => m.type === 'html')
+  assert(html.html.includes('pd-feed'), 'shell html should include <pulse-deferred id="pd-feed"> placeholder')
+  assert(Array.isArray(html.deferred),  'html message should list deferred key names')
+  assert(html.deferred[0] === 'feed',   `Expected deferred[0]='feed', got ${html.deferred[0]}`)
+})
+
+await test('stream.scope: meta arrives before slow deferred fetcher resolves', async () => {
+  const spec = {
+    route:  '/nav',
+    state:  {},
+    server: {
+      fast: async () => 'quick',
+      slow: async () => { await new Promise(r => setTimeout(r, 80)); return 'late' },
+    },
+    stream: {
+      shell:    ['header'],
+      deferred: ['feed'],
+      scope:    { header: ['fast'], feed: ['slow'] },
+    },
+    view: {
+      header: (s, srv) => `<header>${srv.fast}</header>`,
+      feed:   (s, srv) => `<aside>${srv.slow}</aside>`,
+    },
+  }
+  const t0       = Date.now()
+  const stream   = renderToNavStream(spec)
+  const reader   = stream.getReader()
+  const decoder  = new TextDecoder()
+  let buf = ''
+  let metaTime = null
+  let shellTime = null
+
+  outer: while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buf += decoder.decode(value, { stream: true })
+    const lines = buf.split('\n')
+    buf = lines.pop()
+    for (const line of lines) {
+      if (!line.trim()) continue
+      const msg = JSON.parse(line)
+      if (msg.type === 'meta')  metaTime  = Date.now() - t0
+      if (msg.type === 'html')  { shellTime = Date.now() - t0; break outer }
+    }
+  }
+  reader.cancel()
+
+  assert(metaTime  !== null,  'meta should have arrived')
+  assert(shellTime !== null,  'shell should have arrived')
+  assert(metaTime  < 20,  `meta should arrive <20ms (fast), got ${metaTime}ms`)
+  assert(shellTime < 40,  `shell should arrive <40ms (only awaits 'fast'), got ${shellTime}ms`)
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)