@webjsdev/core 0.7.64 → 0.8.0

package/src/router-client/snapshot-cache.js

@@ -9,7 +9,7 @@
 import { SNAPSHOT_CAP } from './constants.js';
 
 /** @typedef {{ html: string, scrollX: number, scrollY: number, scrollHeight: number }} Snapshot */
-/** @type {Map<string, Snapshot | string>} */
+/** @type {Map<string, Snapshot>} */
 export const snapshotCache = new Map();
 
 /**
@@ -59,9 +59,7 @@ export function snapshotCurrent(url) {
 }
 
 /**
- * Look up a cached snapshot by URL. Returns a normalized Snapshot or
- * null. Tolerates legacy string entries (e.g. from test fixtures that
- * `_snapshotCache.set('/x', 'snap')`).
+ * Look up a cached snapshot by URL, or null on a miss.
  *
  * @param {string} url
  * @returns {Snapshot | null}
@@ -73,14 +71,6 @@ export function snapshotGet(url) {
   // Move-to-front.
   snapshotCache.delete(key);
   snapshotCache.set(key, v);
-  // A legacy string entry carries no offsets and no height. `scrollHeight: 0`
-  // is stated rather than left undefined so the returned object satisfies the
-  // `Snapshot` typedef, and because `reserveRestoredHeight` treats a
-  // non-positive height as "nothing to reserve" and no-ops: there is no
-  // recorded height to hold, so reserving is not merely skippable, it is
-  // meaningless. Such an entry restores with no reservation, which is the
-  // pre-#1428 behaviour and correct for a snapshot that never recorded one.
-  if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0, scrollHeight: 0 };
   return v;
 }
 

package/src/router-client/stylesheets.js

@@ -0,0 +1,191 @@
+// @ts-check
+/**
+ * Stylesheets a navigation brings with it are loaded BEFORE the swap (#1666).
+ *
+ * A soft navigation parses the response and applies it in the same task, so a
+ * `<link rel="stylesheet">` the incoming page carries starts loading only once
+ * it is in the live document, and the new content paints for a frame or more
+ * without it: a flash of the page in the wrong styles. Turbo Drive closes the
+ * same gap by appending each new head stylesheet and awaiting its `load`
+ * before it renders, Remix v2 preloads a route's links and awaits them before
+ * it commits the transition, and the Next.js app router holds a commit until
+ * new route CSS has loaded.
+ *
+ * WebJs reads the BODY as well as the head, because a section's stylesheet can
+ * only ride the body on a soft navigation: only the root layout may write
+ * `<head>`, and the `X-Webjs-Have` short-circuit never re-renders it, so a
+ * nested layout or a page that needs a stylesheet emits its link inline. On a
+ * frame navigation only the frame's own subtree is read, since nothing else in
+ * the response is swapped in.
+ *
+ * The router adds no stylesheet state of its own; it only bridges the load
+ * gap, Remix's preload-then-render shape. Each stylesheet the live document
+ * does not already link gets a TEMPORARY copy in `<head>`, marked
+ * `data-webjs-preload-style`, and the swap waits for it. Once the swap has
+ * committed, `releaseIncomingStylesheets` removes each copy as soon as the
+ * page's own link to the same file has loaded (from the HTTP cache by then),
+ * so some copy of the sheet applies on every frame and none outlives it. A
+ * copy whose file the swapped-in page does not link is removed at once, and
+ * so is every copy of a navigation that was superseded or discarded. A sheet
+ * that fails or stalls never holds a navigation hostage: an `error` resolves
+ * the wait, and so does a timeout, Turbo's 2 seconds.
+ */
+import { PRELOAD_ATTR, relIsStylesheet } from './constants.js';
+import { HELD_MEDIA_ATTR, OWNER_ATTR, holdMedia, placeOwnedLink } from './owned-styles.js';
+import { getCspNonce } from './head-merge.js';
+
+/** How long a navigation waits for one stylesheet before it swaps anyway. */
+export const STYLESHEET_TIMEOUT_MS = 2000;
+
+/** The attribute that marks the router's temporary copies (defined in the leaf). */
+export { PRELOAD_ATTR };
+
+/**
+ * Is `el` a stylesheet that applies now: a `<link>` whose `rel` names
+ * `stylesheet` but not `alternate` (an alternate sheet is off until chosen),
+ * that is not `disabled`, has an `href`, and has no `media` query that does
+ * not match.
+ * @param {Element} el
+ */
+function isActiveStylesheet(el) {
+  if (!relIsStylesheet(el)) return false;
+  if (el.hasAttribute('disabled') || !el.getAttribute('href')) return false;
+  // A held link (owned-styles.js) applies under its author's media once released.
+  const media = el.hasAttribute(HELD_MEDIA_ATTR) ? el.getAttribute(HELD_MEDIA_ATTR) : el.getAttribute('media');
+  if (media && typeof matchMedia === 'function') {
+    try { if (!matchMedia(media).matches) return false; } catch { /* an unparseable query applies to nothing */ return false; }
+  }
+  return true;
+}
+
+/**
+ * Resolve when `link` has loaded or failed, or after `timeout` ms.
+ * @param {HTMLLinkElement} link
+ * @param {number} timeout
+ * @returns {Promise<void>}
+ */
+function waitForLoad(link, timeout) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      link.removeEventListener('load', done);
+      link.removeEventListener('error', done);
+      resolve();
+    };
+    const timer = setTimeout(done, timeout);
+    link.addEventListener('load', done);
+    link.addEventListener('error', done);
+  });
+}
+
+/**
+ * @typedef {{ ready: Promise<void>, copies: HTMLLinkElement[] }} IncomingStylesheets
+ */
+
+/**
+ * Start loading every stylesheet the incoming page links that the live
+ * document does not, through a temporary copy in `<head>`. Returns `null` when
+ * there is nothing new, so the caller swaps in the same task as before and a
+ * navigation that brings no stylesheet costs no extra time. Otherwise returns
+ * the copies and a promise that settles when all of them have loaded, failed
+ * or timed out; pass the result to `releaseIncomingStylesheets` once the swap
+ * has committed, or once the navigation is abandoned.
+ *
+ * @param {Document} doc  The parsed incoming page.
+ * @param {string | null | undefined} baseUrl  The URL `doc` was fetched from,
+ *   which a relative `href` in it resolves against.
+ * @param {string | null} [frameId]  On a frame navigation, the frame being
+ *   swapped: only its subtree in `doc` is read.
+ * @param {number} [timeout]
+ * @returns {IncomingStylesheets | null}
+ */
+export function loadIncomingStylesheets(doc, baseUrl, frameId, timeout = STYLESHEET_TIMEOUT_MS) {
+  if (typeof document === 'undefined' || !doc || !document.head) return null;
+  /** @type {ParentNode | null} */
+  let scope = doc;
+  if (frameId) {
+    try { scope = doc.querySelector(`webjs-frame#${CSS.escape(frameId)}`); } catch { scope = null; }
+  }
+  if (!scope) return null;
+  const base = baseUrl || document.baseURI;
+  /** @param {string} href */
+  const resolve = (href) => {
+    try { return new URL(href, base).href; } catch { return null; }
+  };
+  // What the page already links. Another navigation's temporary copies do
+  // not count: they are released on that navigation's own schedule.
+  const live = new Set();
+  for (const el of document.querySelectorAll('link[href]')) {
+    if (el.hasAttribute(PRELOAD_ATTR) || !isActiveStylesheet(el)) continue;
+    const href = /** @type {HTMLLinkElement} */ (el).href;
+    if (href) live.add(href);
+  }
+  const nonce = getCspNonce();
+  /** @type {HTMLLinkElement[]} */
+  const copies = [];
+  /** @type {Promise<void>[]} */
+  const waits = [];
+  for (const el of scope.querySelectorAll('link[href]')) {
+    if (!isActiveStylesheet(el)) continue;
+    const href = resolve(/** @type {string} */ (el.getAttribute('href')));
+    if (!href || live.has(href)) continue;
+    live.add(href);
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.setAttribute(PRELOAD_ATTR, '');
+    // The attributes that change how the file is fetched and applied travel
+    // with it, so the copy loads exactly what the page asked for. The nonce is
+    // the LIVE page's: the browser checks CSP against the nonce of the original
+    // page load, never a later response's (#1050).
+    for (const name of ['media', 'crossorigin', 'integrity', 'referrerpolicy']) {
+      const value = el.getAttribute(name);
+      if (value) link.setAttribute(name, value);
+    }
+    if (nonce) link.setAttribute('nonce', nonce);
+    link.href = href;
+    // Loaded without applying: the outgoing page, and a view transition's
+    // capture of it, must not paint with the incoming CSS. The swap commit
+    // releases it (owned-styles.js `releaseIncomingSheets`).
+    holdMedia(link);
+    copies.push(link);
+    waits.push(waitForLoad(link, timeout));
+    // A sheet a layout owns (#1669) goes where the page's own link belongs,
+    // so the head merge can adopt this copy as that link instead of adding a
+    // second one; any other copy goes at the end of the head.
+    const owner = el.getAttribute(OWNER_ATTR);
+    if (owner) {
+      link.setAttribute(OWNER_ATTR, owner);
+      placeOwnedLink(link, owner);
+    } else {
+      document.head.appendChild(link);
+    }
+  }
+  if (!copies.length) return null;
+  return { ready: Promise.all(waits).then(() => undefined), copies };
+}
+
+/**
+ * Remove the temporary copies `loadIncomingStylesheets` made. Each one stays
+ * until the live document's own link to the same file has loaded (or failed,
+ * or the timeout passes), so the sheet applies on every frame of the handoff;
+ * a copy with no such link (a discarded response, a frame swap that did not
+ * bring the file, a superseded navigation) goes at once.
+ *
+ * @param {IncomingStylesheets | null} incoming
+ * @param {number} [timeout]
+ */
+export function releaseIncomingStylesheets(incoming, timeout = STYLESHEET_TIMEOUT_MS) {
+  if (!incoming || typeof document === 'undefined') return;
+  for (const copy of incoming.copies) {
+    // Gone already, or adopted by the head merge as the page's own link.
+    if (!copy.isConnected || !copy.hasAttribute(PRELOAD_ATTR)) continue;
+    /** @type {HTMLLinkElement | null} */
+    let twin = null;
+    for (const el of document.querySelectorAll('link[href]')) {
+      if (el === copy || el.hasAttribute(PRELOAD_ATTR) || !isActiveStylesheet(el)) continue;
+      if (/** @type {HTMLLinkElement} */ (el).href === copy.href) { twin = /** @type {HTMLLinkElement} */ (el); break; }
+    }
+    if (!twin || twin.sheet) { copy.remove(); continue; }
+    waitForLoad(twin, timeout).then(() => copy.remove());
+  }
+}

package/src/router-client/swap.js

@@ -11,8 +11,9 @@ import { collectBoundaries, planBoundarySwap } from './boundaries.js';
 import { reportFallback } from './diagnostics.js';
 import { blurOutgoingFocus, diffChildren, replaceBoundaryRange, resyncEnclosingHostSlots, swapMarkerRange } from './dom-differ.js';
 import { trackedReloadSignature } from './frames.js';
-import { addNewHeadElements, mergeHead } from './head-merge.js';
+import { addNewHeadElements, mergeHead, mergeHeadStylesheets } from './head-merge.js';
 import { morphLayoutChrome, planLayoutChrome } from './layout-chrome.js';
+import { primeLiveStylesheetKeys, releaseIncomingSheets, switchOffDepartedStylesheets } from './owned-styles.js';
 import { clearPrefetchRefused, prefetchClearAll } from './prefetch.js';
 import { snapshotCache } from './snapshot-cache.js';
 import { hardNavigate } from './state.js';
@@ -84,6 +85,13 @@ export let _swapCommit = Promise.resolve();
  *   history (a revalidation, a refresh, the popstate restore).
  */
 export function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc, refresh, recordHistoryNow) {
+  // The URL the incoming page came from, which its relative stylesheet hrefs
+  // resolve against, and the live sheets' keys taken NOW, while the document
+  // still has the outgoing page's URL: every commit point below records the
+  // new history entry before it merges the head (#1669).
+  let incomingBase = typeof location !== 'undefined' ? location.href : '';
+  if (href) { try { incomingBase = new URL(href, incomingBase).href; } catch { /* keep the live url */ } }
+  primeLiveStylesheetKeys();
   // SSR action seeding (#472): ingest the incoming page's seed payload BEFORE
   // its components are grafted into the live DOM and upgrade, so a
   // soft-navigated async component resolves from the seed instead of
@@ -279,7 +287,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ADD-ONLY head merge: preserve runtime-generated head content
       // (Tailwind CSS injection, etc.) that the outer layout's scripts
       // already produced.
-      addNewHeadElements(doc.head);
+      addNewHeadElements(doc.head, { base: incomingBase, frame: true });
       // `diffChildren` -> `reconcileChildren` regrafts permanent elements
       // by node identity (it imports the incoming children first, then
       // swaps the live permanent node into the imported tree), so the live
@@ -288,6 +296,8 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ALSO progressively streams a Suspense boundary gates its resolves on the
       // committed frame swap, not a stale prior _swapCommit (#1048).
       _swapCommit = runWithTransition(() => {
+        // The frame's incoming sheets loaded held; they apply with the swap.
+        releaseIncomingSheets();
         diffChildren(target, source);
         reactivateScripts(target);
         upgradeCustomElements(target);
@@ -334,7 +344,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     // commit point without a reader having to prove reachability first, which
     // is what stops the next person adding a commit point from omitting it.
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -361,7 +371,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   if (plan && refresh === 'layouts' && !chrome) {
     ingestSeeds();
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -375,11 +385,32 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     if (recordHistoryNow) recordHistoryNow();
     const { mode, live, incoming } = plan;
     // ADD-ONLY head merge: the outer layout stays mounted, so its head-bound
-    // runtime state (Tailwind injection, etc.) must not be invalidated.
-    addNewHeadElements(doc.head);
+    // runtime state (Tailwind injection, etc.) must not be invalidated. It runs
+    // ahead of the commit, as the incoming sheets' load-before-swap copies
+    // already do (#1666, Turbo's order), so the new page's sheets apply from
+    // the swap's first frame.
+    // Its stylesheets wait for the commit (#1669, below).
+    addNewHeadElements(doc.head, { base: incomingBase, styles: false });
+    // A live element inside the range this swap replaces is on its way out,
+    // so a stylesheet link there does not count as one the page keeps.
+    /** @param {Element} el */
+    const leaving = (el) => !!(live.start.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+      && !!(live.end.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING);
     _swapCommit = runWithTransition(() => {
+      // Everything stylesheet-related happens inside the commit, so the
+      // outgoing page, and a view transition's capture of it, keep exactly the
+      // sheets that page used, and the crossing restyles once (#1669): the
+      // incoming sheets (loaded held, stylesheets.js) are adopted, switched
+      // back on or inserted, then released, before the new markup lands.
+      mergeHeadStylesheets(doc.head, { base: incomingBase, segment: plan.segment, leaving });
+      releaseIncomingSheets();
       if (mode === 'replace') replaceBoundaryRange(live, incoming);
       else swapMarkerRange(live, incoming, doc);
+      // The swapped range's own stylesheets go with it unless the incoming
+      // page links them, in its head or its body, on a replace and on a morph
+      // alike: the server re-rendered the whole range either way, so a sheet a
+      // searchParams change dropped is retired too.
+      switchOffDepartedStylesheets(plan.segment, doc, incomingBase);
       // No key sync is needed on the anchor's own comments: the plan's anchor
       // carries EQUAL live/incoming route-keys in every tier (a changed-key
       // REPLACE anchors at a parent already compared equal; the other tiers
@@ -438,7 +469,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   // because the user is already viewing the page).
   ingestSeeds();   // committed: past both discard branches above
   if (recordHistoryNow) recordHistoryNow();
-  swapFullBody(doc);
+  swapFullBody(doc, incomingBase, false);
 }
 
 /**
@@ -460,9 +491,12 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
  * it only past their own discard branches.
  *
  * @param {Document} doc
+ * @param {string} incomingBase  the URL the incoming page came from
+ * @param {boolean} complete  the response rendered every layout (no X-Webjs-Have), so it can retire a departed section's sheets
  */
-function swapFullBody(doc) {
-  mergeHead(doc.head);
+function swapFullBody(doc, incomingBase, complete) {
+  // Its stylesheets wait for the commit, as on a boundary swap (#1669).
+  mergeHead(doc.head, { base: incomingBase, styles: false });
   // Persist permanent elements by node identity across the full-body
   // swap: move each live [data-webjs-permanent][id] node into the matching
   // position in the incoming body BEFORE replaceChildren reads it, so the
@@ -470,7 +504,13 @@ function swapFullBody(doc) {
   regraftPermanentElements(document.body, doc.body);
   const newChildren = [...doc.body.childNodes];
   const doSwap = () => {
+    // The whole body is replaced, so every live body link is leaving.
+    mergeHeadStylesheets(doc.head, { base: incomingBase, segment: '/', leaving: () => true });
+    releaseIncomingSheets();
     document.body.replaceChildren(...newChildren);
+    // Only a response known to be complete can say a section's sheet is gone:
+    // the background restore path's head can be a reduced one (#936).
+    if (complete) switchOffDepartedStylesheets('/', doc, incomingBase);
     reactivateScripts(document.body);
     upgradeCustomElements(document.body);
     blurOutgoingFocus();

package/src/sentinels.d.ts

@@ -0,0 +1,2 @@
+export const nothing: unique symbol;
+export const noChange: unique symbol;

package/src/sentinels.js

@@ -0,0 +1,4 @@
+/** Clear a rendered value using Lit's position-specific rules. */
+export const nothing = Symbol.for('webjs.nothing');
+/** Keep the previously committed value. */
+export const noChange = Symbol.for('webjs.noChange');

package/src/slot.js

@@ -74,7 +74,7 @@
  *
  * SSR. This module is import-safe in Node (DOM access is guarded on
  * `typeof HTMLSlotElement !== 'undefined'`). Server-side slot substitution
- * lives in render-server.js (injectDSD); slot.js drives the client runtime.
+ * lives in render-server/expand.js (`finishSlot`); slot.js drives the client runtime.
  */
 
 // ---------------------------------------------------------------------------

package/src/webjs-config.d.ts

@@ -94,7 +94,7 @@ export interface WebjsRegenerateRule {
   output: string;
   /** The shell command that rebuilds `output` (the same command prod uses in `start.before`, so dev and prod cannot diverge). */
   command: string;
-  /** Source files/directories whose newest mtime is compared to `output`'s; a newer one (or a missing output) triggers the rebuild. */
+  /** Source files/directories the output is built from. Every build records a fingerprint of the files under them (path, size, mtime) in `.webjs/regenerate.json`, and the output is rebuilt when that fingerprint, the command, or the output itself no longer matches the record, or the output is missing (#1672). `webjs regenerate` builds and records outside the dev server. */
   inputs?: string[];
 }
 

package/src/render-server/slots.js

@@ -1,213 +0,0 @@
-import { escapeAttr } from '../escape.js';
-import {
-  endOfComment, escapeRegex, findClosingTagInString, inertAt, inertRanges, isVoidElement,
-} from './html-scan.js';
-
-/**
- * SSR light-DOM slot projection: partition a component's authored children by
- * their `slot=""` attribute, then substitute each `<slot>` in the rendered
- * template with the projected children or the authored fallback.
- *
- * String-level throughout, so it depends on `html-scan.js` and nothing else in
- * this directory.
- */
-
-/**
- * Extract the `slot` attribute value from an attribute string. Returns
- * null when the attribute is absent.
- *
- * @param {string} attrsRaw
- * @returns {string | null}
- */
-function extractSlotAttr(attrsRaw) {
-  const m = /\bslot\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(attrsRaw);
-  if (!m) return null;
-  const value = m[1] ?? m[2] ?? m[3] ?? '';
-  // Per shadow DOM spec, slot="" (empty) and missing slot attribute both
-  // route to the default slot. `default` is the framework's reserved alias
-  // for it (#1015: the client record normalizes it identically, so both
-  // sides agree end to end).
-  return value === '' || value === 'default' ? null : value;
-}
-
-/**
- * Partition authored inner HTML by each top-level child's `slot=""`
- * attribute. Text nodes, comment nodes, and elements without `slot=""`
- * all route to the default-slot key (null).
- *
- * Returns a Map keyed by slot name (null for default) whose values are
- * the concatenated HTML strings for that slot in source order.
- *
- * @param {string} html
- * @returns {Map<string|null, string>}
- */
-export function partitionAuthoredBySlot(html) {
-  /** @type {Map<string|null, string>} */
-  const groups = new Map();
-  let defaultBuf = '';
-  let cursor = 0;
-  while (cursor < html.length) {
-    const lt = html.indexOf('<', cursor);
-    if (lt === -1) {
-      defaultBuf += html.slice(cursor);
-      break;
-    }
-    if (lt > cursor) defaultBuf += html.slice(cursor, lt);
-    const rest = html.slice(lt);
-    if (rest.startsWith('<!--')) {
-      // Find the comment's end the same way inertRanges does, rather than with
-      // a bare `indexOf('-->')`. The two helpers both decide where a comment
-      // stops, so a bare search makes them DISAGREE on the spec short forms
-      // (`--!>`, `<!-->`, `<!--->`): this one would run past the real end and
-      // swallow the slotted children that follow, silently routing a
-      // `slot="head"` child into the default slot.
-      const commentEnd = endOfComment(html, lt);
-      if (commentEnd === -1) {
-        defaultBuf += rest;
-        cursor = html.length;
-        break;
-      }
-      defaultBuf += html.slice(lt, commentEnd);
-      cursor = commentEnd;
-      continue;
-    }
-    if (rest.startsWith('<!') || rest.startsWith('</')) {
-      const end = html.indexOf('>', lt);
-      if (end === -1) {
-        defaultBuf += rest;
-        cursor = html.length;
-        break;
-      }
-      defaultBuf += html.slice(lt, end + 1);
-      cursor = end + 1;
-      continue;
-    }
-    const tagMatch = /^<([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>])*?)(\/?)>/.exec(rest);
-    if (!tagMatch) {
-      defaultBuf += '<';
-      cursor = lt + 1;
-      continue;
-    }
-    const [tagFull, tagName, attrsRaw, selfCloseSlash] = tagMatch;
-    const lower = tagName.toLowerCase();
-    const isSelfClose = !!selfCloseSlash || isVoidElement(lower);
-    const slotAttr = extractSlotAttr(attrsRaw);
-    let elemEnd;
-    if (isSelfClose) {
-      elemEnd = lt + tagFull.length;
-    } else {
-      const innerStart = lt + tagFull.length;
-      const closeIdx = findClosingTagInString(html, innerStart, lower);
-      if (closeIdx === -1) {
-        // Unclosed element. Take to end of html.
-        const elementHTML = html.slice(lt);
-        if (slotAttr !== null) appendStringToMap(groups, slotAttr, elementHTML);
-        else defaultBuf += elementHTML;
-        cursor = html.length;
-        continue;
-      }
-      const closeRe = new RegExp(`</${escapeRegex(lower)}\\s*>`, 'i');
-      const tail = html.slice(closeIdx);
-      const closeMatch = closeRe.exec(tail);
-      const closeLen = closeMatch ? closeMatch[0].length : `</${lower}>`.length;
-      elemEnd = closeIdx + closeLen;
-    }
-    const elementHTML = html.slice(lt, elemEnd);
-    if (slotAttr !== null) appendStringToMap(groups, slotAttr, elementHTML);
-    else defaultBuf += elementHTML;
-    cursor = elemEnd;
-  }
-  if (defaultBuf.length > 0) groups.set(null, defaultBuf);
-  return groups;
-}
-
-/** Append a string to a Map<K, string>, concatenating if the key exists. */
-function appendStringToMap(map, key, value) {
-  const existing = map.get(key);
-  if (existing !== undefined) map.set(key, existing + value);
-  else map.set(key, value);
-}
-
-/**
- * Substitute every `<slot>` tag in `rendered` with a framework-marked
- * `<slot data-webjs-light data-projection="actual|fallback">` element
- * carrying either the projected children for that slot (from
- * `partitioned`) or the slot's authored fallback content. Multiple
- * slots with the same name follow the first-wins rule per spec; later
- * same-named slots fall back regardless of available projection.
- *
- * The `ownerTag` (the tag of the component whose template rendered these
- * slots) is emitted as `data-wj-slot-owner` so the client resolves template
- * ownership on hydration the same way the client renderer stamps SLOT_OWNER,
- * which is what makes a FORWARDED slot (rendered by this component but nested
- * inside a child) route to this component and not the child (#1023).
- *
- * @param {string} rendered
- * @param {Map<string|null, string>} partitioned
- * @param {string} ownerTag
- * @returns {string}
- */
-export function substituteSlotsInRender(rendered, partitioned, ownerTag) {
-  const ownerAttr = ownerTag ? ` data-wj-slot-owner="${escapeAttr(ownerTag)}"` : '';
-  /** @type {Set<string|null>} */
-  const consumedNames = new Set();
-  let result = '';
-  let cursor = 0;
-  const slotRe = /<slot((?:"[^"]*"|'[^']*'|[^>])*?)(\/?)>/gi;
-  // A `<slot>` written inside a comment is documentation, not a slot (#1128).
-  // Substituting one is worse here than in the element walk: a commented slot
-  // has no `</slot>`, so the fallback scan below swallows the rest of the
-  // template, the component's REAL slot is never substituted, and the authored
-  // children are dropped from the page entirely.
-  const inert = inertRanges(rendered);
-  const isInert = inertAt(inert);
-  let m;
-  while ((m = slotRe.exec(rendered)) !== null) {
-    if (isInert(m.index)) continue;
-    result += rendered.slice(cursor, m.index);
-    const [fullOpen, attrsRaw, selfCloseSlash] = m;
-    const isSelfClose = !!selfCloseSlash;
-    const nameMatch = /\bname\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(attrsRaw);
-    const name = nameMatch ? (nameMatch[1] ?? nameMatch[2] ?? nameMatch[3]) : null;
-    // Strip the `name` attribute from the carried-through attribute
-    // string so we can re-add it (with escaping) on the framework slot.
-    const otherAttrs = attrsRaw.replace(/\bname\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/i, '').trim();
-    let fallback = '';
-    let totalEnd;
-    if (isSelfClose) {
-      totalEnd = m.index + fullOpen.length;
-    } else {
-      const innerStart = m.index + fullOpen.length;
-      const closeIdx = findClosingTagInString(rendered, innerStart, 'slot', inert);
-      if (closeIdx === -1) {
-        fallback = rendered.slice(innerStart);
-        totalEnd = rendered.length;
-      } else {
-        fallback = rendered.slice(innerStart, closeIdx);
-        const closeRe = /<\/slot\s*>/i;
-        const tail = rendered.slice(closeIdx);
-        const closeMatch = closeRe.exec(tail);
-        const closeLen = closeMatch ? closeMatch[0].length : '</slot>'.length;
-        totalEnd = closeIdx + closeLen;
-      }
-    }
-    // `default` and `''` are the reserved aliases for the default slot
-    // (#1015), matching the client's keyOfName exactly: the LOOKUP key
-    // normalizes, while the emitted name attribute stays as authored so the
-    // output bytes are unchanged for every other app.
-    const slotKey = name === 'default' || name === '' ? null : name;
-    const projected = partitioned.get(slotKey);
-    const nameAttr = name !== null ? ` name="${escapeAttr(name)}"` : '';
-    const extraAttrs = otherAttrs ? ` ${otherAttrs}` : '';
-    if (projected !== undefined && !consumedNames.has(slotKey)) {
-      consumedNames.add(slotKey);
-      result += `<slot data-webjs-light data-projection="actual"${ownerAttr}${nameAttr}${extraAttrs}>${projected}</slot>`;
-    } else {
-      result += `<slot data-webjs-light data-projection="fallback"${ownerAttr}${nameAttr}${extraAttrs}>${fallback}</slot>`;
-    }
-    cursor = totalEnd;
-    slotRe.lastIndex = totalEnd;
-  }
-  result += rendered.slice(cursor);
-  return result;
-}