@webjsdev/core 0.7.15 → 0.7.16

package/src/router-client.js

@@ -8,6 +8,9 @@ import './webjs-frame.js';
 // live-channel `connectWS` handler.
 import './webjs-stream.js';
 import { renderStream } from './webjs-stream.js';
+// Register <webjs-suspense> (the element-level streaming boundary, #471) so it
+// is layout-neutral and available for the progressive soft-nav streaming apply.
+import './webjs-suspense.js';
 
 /** The content type a content-negotiated stream-action response carries (#248). */
 const STREAM_MIME = 'text/vnd.webjs-stream.html';
@@ -1438,6 +1441,10 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
   method = method || 'GET';
   const myToken = typeof token === 'number' ? token : currentNavigationToken;
   let html;
+  // Set when the response streams Suspense boundaries (#473): holds the open
+  // reader + leftover buffer so the boundaries apply progressively after the
+  // shell swap. Null for a buffered (non-streaming) or prefetched response.
+  let streamCtx = null;
   let incomingBuild = null;
   /** @type {number | null} */
   let respStatus = null;
@@ -1556,7 +1563,13 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     // tag to compare. The applySwap importmap-mismatch guard reads
     // this to detect deploys that bumped the vendor pin.
     incomingBuild = resp.headers.get('x-webjs-build');
-    html = await resp.text();
+    // Progressive streaming (#473): read only up to the first streamed Suspense
+    // boundary so the shell (with fallbacks) swaps in immediately; the rest
+    // streams in after the swap. A body with no boundaries reads to completion,
+    // so a non-streaming nav is identical to the old `resp.text()`.
+    const shellRead = await readStreamedShell(resp);
+    html = shellRead.shell;
+    if (shellRead.streaming) streamCtx = shellRead;
     }
   } catch (err) {
     // Aborted by a newer navigation: let it run, don't fall back. An
@@ -1577,7 +1590,10 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
 
   // A newer navigation started while we awaited the response body -
   // bail before we overwrite its work.
-  if (myToken !== currentNavigationToken) return { ok: false, status: respStatus, aborted: true };
+  if (myToken !== currentNavigationToken) {
+    if (streamCtx && streamCtx.reader) { try { streamCtx.reader.cancel(); } catch { /* ignore */ } }
+    return { ok: false, status: respStatus, aborted: true };
+  }
 
   const doc = parseHTML(html);
   // The body claimed text/html but didn't parse into a document (a
@@ -1610,6 +1626,20 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     }
   }
 
+  // Progressive streaming (#473): the shell (with its Suspense fallbacks) is
+  // now live, so stream the resolved boundaries in fast-before-slow. Detached
+  // (fire-and-forget) so the URL advance + navigate event do not wait on the
+  // slow boundary; each apply is guarded by the nav token so a newer navigation
+  // stops it.
+  if (streamCtx && (streamCtx.reader || streamCtx.rest)) {
+    streamBoundariesProgressively(
+      streamCtx.reader,
+      streamCtx.dec,
+      streamCtx.rest,
+      () => myToken === currentNavigationToken,
+    );
+  }
+
   document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url: finalUrl, frameId, from: 'navigate' } }));
   return { ok: respOk, status: respStatus, aborted: false };
   } finally {
@@ -2832,6 +2862,160 @@ function forwardSuspenseResolvers(fetchedBody) {
   }
 }
 
+/**
+ * Read a navigation response body progressively (#473). Returns the SHELL
+ * (the HTML up to the first streamed Suspense boundary template) as soon as it
+ * is available, so the router can swap it in immediately and the user sees the
+ * fallbacks without waiting for the slow boundary. When the body carries
+ * streamed boundaries it also returns the still-open `reader` + leftover buffer
+ * so the caller applies each boundary progressively AFTER the shell swap. A body
+ * with no boundaries reads to completion and returns the whole thing, so a
+ * non-streaming navigation is behaviourally identical to `resp.text()`.
+ *
+ * @param {Response} resp
+ * @returns {Promise<{ shell: string, streaming: boolean, reader?: ReadableStreamDefaultReader<Uint8Array>, dec?: TextDecoder, rest?: string }>}
+ */
+async function readStreamedShell(resp) {
+  if (!resp.body || typeof resp.body.getReader !== 'function') {
+    return { shell: await resp.text(), streaming: false };
+  }
+  const reader = resp.body.getReader();
+  const dec = new TextDecoder();
+  let buf = '';
+  const MARK = '<template data-webjs-resolve';
+  // The SSR stream flushes the whole shell (prefix + body with fallbacks)
+  // followed by a `<!--wj-stream-shell-->` sentinel in the SAME chunk, then
+  // PAUSES for the slow data before streaming each boundary template and the
+  // `</body></html>` closer. The sentinel is what lets the shell swap in
+  // immediately instead of blocking until the slow boundary arrives. Fallbacks
+  // for robustness: an already-buffered boundary marker (a fast boundary), or
+  // `</html>` (a fully-buffered response that happens to carry boundaries).
+  const SHELL = '<!--wj-stream-shell-->';
+  const HTML_CLOSE = /<\/html\s*>/i;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (value) buf += dec.decode(value, { stream: true });
+    if (done) buf += dec.decode();
+    const si = buf.indexOf(SHELL);
+    if (si !== -1) {
+      return { shell: buf.slice(0, si), streaming: true, reader: done ? null : reader, dec, rest: buf.slice(si + SHELL.length) };
+    }
+    const mi = buf.indexOf(MARK);
+    if (mi !== -1) {
+      return { shell: buf.slice(0, mi), streaming: true, reader: done ? null : reader, dec, rest: buf.slice(mi) };
+    }
+    if (done) {
+      // Stream ended with no streaming markers: the whole body is the shell.
+      return { shell: buf, streaming: false };
+    }
+    const hm = HTML_CLOSE.exec(buf);
+    if (hm) {
+      const end = hm.index + hm[0].length;
+      return { shell: buf.slice(0, end), streaming: true, reader, dec, rest: buf.slice(end) };
+    }
+  }
+}
+
+/**
+ * Extract the next complete top-level
+ * `<template data-webjs-resolve="ID">...</template>` unit from `buf`,
+ * depth-tracking NESTED `<template>` tags (a streamed shadow component carries a
+ * `<template shadowrootmode>` inside). Returns `{ id, content, rest }` for the
+ * first complete unit, or null when the closing tag has not streamed in yet.
+ *
+ * @param {string} buf
+ * @returns {{ id: string, content: string, rest: string } | null}
+ */
+function takeResolveUnit(buf) {
+  const m = /<template\s+data-webjs-resolve="([^"]+)"\s*>/i.exec(buf);
+  if (!m) return null;
+  const id = m[1];
+  const contentStart = m.index + m[0].length;
+  const tagRe = /<(\/?)template\b[^>]*>/gi;
+  tagRe.lastIndex = contentStart;
+  let depth = 1;
+  let mm;
+  while ((mm = tagRe.exec(buf))) {
+    if (mm[1] === '/') {
+      depth--;
+      if (depth === 0) {
+        return { id, content: buf.slice(contentStart, mm.index), rest: buf.slice(mm.index + mm[0].length) };
+      }
+    } else {
+      depth++;
+    }
+  }
+  return null;
+}
+
+/**
+ * Apply one streamed Suspense resolution to the live DOM (#473). REPLACES the
+ * boundary element (its fallback) with the resolved content and upgrades any
+ * custom elements inside. This mirrors the initial-load boot resolver
+ * (`b.replaceWith(template.content)`) and the prefetched-buffered path exactly,
+ * so a streamed boundary settles to the SAME DOM shape (the transient
+ * `<webjs-boundary>` / `<webjs-suspense>` wrapper removed) however the page was
+ * reached, in JS so a soft-nav apply does not depend on the inline swap script.
+ *
+ * @param {string} id
+ * @param {string} content
+ */
+function applyStreamedResolve(id, content) {
+  const boundary = document.getElementById(id);
+  if (!boundary) return;
+  const tpl = document.createElement('template');
+  tpl.innerHTML = content;
+  const inserted = [...tpl.content.childNodes];
+  boundary.replaceWith(tpl.content);
+  // Upgrade any custom elements now that they are connected (belt-and-braces:
+  // a connected, defined element upgrades on insertion, but a fragment that was
+  // built before its module loaded would not).
+  for (const n of inserted) if (n.nodeType === 1) upgradeTree(/** @type {Element} */ (n));
+}
+
+/**
+ * Progressively apply streamed Suspense boundaries from an open response reader
+ * to the live DOM AFTER the shell has been swapped in (#473). Runs detached
+ * (fire-and-forget); each apply is guarded by `isCurrent` so a newer navigation
+ * stops it (and cancels the reader). A mid-stream transport failure leaves the
+ * already-applied boundaries in place and the rest showing their fallback,
+ * which is non-destructive.
+ *
+ * @param {ReadableStreamDefaultReader<Uint8Array>} reader
+ * @param {TextDecoder} dec
+ * @param {string} initialBuf
+ * @param {() => boolean} isCurrent
+ */
+async function streamBoundariesProgressively(reader, dec, initialBuf, isCurrent) {
+  let buf = initialBuf;
+  const flush = () => {
+    let unit;
+    while ((unit = takeResolveUnit(buf))) {
+      if (!isCurrent()) return false;
+      applyStreamedResolve(unit.id, unit.content);
+      buf = unit.rest;
+    }
+    return true;
+  };
+  // The whole response was already buffered (the stream ended before the shell
+  // delimiter): just apply whatever boundaries are in hand.
+  if (!reader) { flush(); return; }
+  try {
+    for (;;) {
+      if (!flush()) { try { await reader.cancel(); } catch { /* ignore */ } return; }
+      const { value, done } = await reader.read();
+      if (value) buf += dec.decode(value, { stream: true });
+      if (done) {
+        buf += dec.decode();
+        flush();
+        return;
+      }
+    }
+  } catch {
+    /* transport drop mid-stream: leave applied boundaries + remaining fallbacks */
+  }
+}
+
 /** @param {Element} container */
 function reactivateScripts(container) {
   for (const old of container.querySelectorAll('script')) {
@@ -2879,6 +3063,10 @@ export {
   prefetch as _prefetch,
   prefetchTake as _prefetchTake,
   prefetchSaysSaveData as _prefetchSaysSaveData,
+  readStreamedShell as _readStreamedShell,
+  takeResolveUnit as _takeResolveUnit,
+  applyStreamedResolve as _applyStreamedResolve,
+  streamBoundariesProgressively as _streamBoundariesProgressively,
 };
 
 /** Test-only: peek the speculative cache for a href without consuming it. */

package/src/webjs-suspense.js

@@ -0,0 +1,42 @@
+/**
+ * `<webjs-suspense>`: the client side of the element-level streaming boundary
+ * (#471).
+ *
+ * The SSR pipeline (render-server.js) does the real work: in a streaming
+ * render each `<webjs-suspense .fallback=${...}>` flushes its fallback
+ * immediately as `<webjs-suspense id="sN">FALLBACK</webjs-suspense>` and streams
+ * the resolved children later as a `<template data-webjs-resolve="sN">` plus a
+ * tiny inline swap `<script>` (the same mechanism page-level `Suspense` uses).
+ * On initial load that swap script REPLACES the boundary element with the
+ * resolved children (the transient `<webjs-suspense id>` wrapper is removed),
+ * and the custom elements inside upgrade natively. So NO client runtime is
+ * required for first-load streaming.
+ *
+ * This element exists for two reasons:
+ *
+ *   1. Layout neutrality. An unknown element defaults to `display: inline`,
+ *      which would wrap a block-level fallback/content oddly. `display:
+ *      contents` makes the boundary box disappear so its children lay out as
+ *      if the wrapper were not there.
+ *   2. A registration home. The client router imports this module so the
+ *      element is defined app-wide; the SOFT-NAVIGATION streaming path
+ *      (router-client.js) reuses the same `data-webjs-resolve` swap to apply a
+ *      streamed response progressively (#473).
+ *
+ * SSR-inert: `renderToString` emits the plain `<webjs-suspense>` tag and never
+ * touches this class (it is defined only when `HTMLElement` exists).
+ */
+const WebjsSuspense = (typeof HTMLElement !== 'undefined')
+  ? class WebjsSuspense extends HTMLElement {
+      connectedCallback() {
+        // Layout-transparent wrapper. Set inline so no stylesheet is needed.
+        if (!this.style.display) this.style.display = 'contents';
+      }
+    }
+  : /** @type {any} */ (null);
+
+if (typeof customElements !== 'undefined' && WebjsSuspense && !customElements.get('webjs-suspense')) {
+  customElements.define('webjs-suspense', WebjsSuspense);
+}
+
+export { WebjsSuspense };