@webjsdev/core 0.7.34 → 0.7.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.34",
+  "version": "0.7.36",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.js

@@ -779,6 +779,16 @@ class WebComponentBase extends Base {
     // hydrated element (whose attribute already arrived from SSR) is unchanged.
     this._reflectDeclaredAttributes();
     const Ctor = /** @type any */ (this.constructor);
+    // Mark LIGHT-DOM component hosts so the framework default host rule
+    // (`@layer webjs-host { :where([data-wj-host]) { display: block } }`)
+    // applies. SSR already stamps this on server-rendered light hosts
+    // (idempotent here); this also covers a client-only light component (never
+    // SSR'd) so it does not collapse. Shadow hosts are NOT marked: a document
+    // rule would override the shadow author's own `:host { display: … }`, so
+    // shadow components control their host display via `:host` in `static styles`.
+    if (Ctor.shadow !== true && !this.hasAttribute('data-wj-host')) {
+      this.setAttribute('data-wj-host', '');
+    }
     if (Ctor.shadow === true) {
       const hadSSRShadow = !!this.shadowRoot;
       if (!this.shadowRoot) {

package/src/render-server.js

@@ -502,6 +502,24 @@ async function injectDSD(html, ctx, ancestors = [], dev) {
       // this.hidden on the host). Reading after render() captures all three.
       // Appending keeps the original tag byte-identical when nothing changed.
       opening = appendReflectedAttrs(opening, instance, presentAttrNames);
+      // Mark LIGHT-DOM component hosts so the framework default
+      // `@layer webjs-host { :where([data-wj-host]) { display: block } }`
+      // (injected once in the document head) applies at first paint. A custom
+      // element is `display:inline` by default, which collapses a component used
+      // as a block container (a board / card) until an author style intervenes.
+      // The low-priority `@layer` keeps it overridable by any author style,
+      // INCLUDING Tailwind's layered utilities (`class="flex"` wins). Emitted
+      // uniformly regardless of elision, so the elision on-vs-off differential is
+      // preserved.
+      //
+      // Shadow hosts are NOT marked: a document-level rule targeting the host
+      // beats the shadow tree's own `:host { display: … }` (the encapsulation-
+      // context criterion outranks both layer and specificity for normal
+      // declarations), so marking them would silently override the shadow
+      // author's `:host` display. Shadow components set their own host display
+      // via `:host` in `static styles` (the idiomatic mechanism), which the
+      // framework must not clobber.
+      if (!isShadow) opening = withHostMarker(opening);
       // Render the template to HTML. injectDSD recurses on the result so
       // nested custom elements (e.g. <theme-toggle> inside <blog-shell>)
       // get their own DSD pass.
@@ -635,6 +653,14 @@ async function injectDSD(html, ctx, ancestors = [], dev) {
       // path), not land in light DOM. Otherwise the client renders the error
       // into the shadow root while the light error box lingers underneath.
       const isShadowErr = /** @type any */ (Cls).shadow === true;
+      // Mark the LIGHT host here too, so a component whose SSR render() throws
+      // paints its error state as display:block (not the inline default),
+      // matching the success path. When an `async render()` rejects, it throws
+      // before the success-path withHostMarker (above) ran, so `opening` is still
+      // unmarked; when a later template render throws, the success marker already
+      // ran and this call is a no-op (withHostMarker is idempotent). Shadow hosts
+      // stay unmarked (their :host must win).
+      if (!isShadowErr) opening = withHostMarker(opening);
       let text;
       if (isShadowErr) {
         const rawStyles = /** @type any */ (Cls).styles;
@@ -1032,6 +1058,18 @@ function seedServerAttrs(instance, attrs) {
  * @param {Set<string>} presentAttrNames  lowercased names already in the source tag
  * @returns {string}
  */
+/**
+ * Add the component host marker (`data-wj-host`) to an opening tag, unless it
+ * is already present. Insert before the closing `>` the same way
+ * `appendReflectedAttrs` does. Idempotent so a re-processed tag is unchanged.
+ * @param {string} opening  the element's opening tag, ending in `>`
+ * @returns {string}
+ */
+function withHostMarker(opening) {
+  if (/\sdata-wj-host(?=[\s>=])/i.test(opening)) return opening;
+  return `${opening.slice(0, -1)} data-wj-host>`;
+}
+
 function appendReflectedAttrs(opening, instance, presentAttrNames) {
   if (!instance || typeof instance.getAttributeNames !== 'function') return opening;
   let extra = '';

package/src/router-client.js

@@ -14,6 +14,12 @@ import './webjs-suspense.js';
 // Ingest SSR action seeds (#472) from an incoming soft-nav document before its
 // components hydrate, so a navigated async component resolves from the seed.
 import { scanSeeds } from './action-seed-client.js';
+// Slot-runtime constants for re-projecting page-authored slotted content of a
+// reused hydrated light-DOM component across a soft nav (#908).
+import {
+  SLOT_STATE, LIGHT_SLOT_ATTR, PROJECTION_ATTR, PROJECTION_ACTUAL,
+  applyActualAssignment, applyFallback, fireSlotChange,
+} from './slot.js';
 
 /** The content type a content-negotiated stream-action response carries (#248). */
 const STREAM_MIME = 'text/vnd.webjs-stream.html';
@@ -76,10 +82,40 @@ const STREAM_MIME = 'text/vnd.webjs-stream.html';
  * Parse HTML into a Document. Prefers Document.parseHTMLUnsafe (processes
  * Declarative Shadow DOM) over DOMParser (does NOT process DSD).
  *
+ * A partial-nav response (#936) is an INNER fragment that BEGINS with the
+ * `<!--wj:children:<path>-->` layout marker and carries no `<!doctype>`/`<html>`.
+ * Parsing such a fragment as a DOCUMENT hoists that leading comment OUT of
+ * `<body>` (the HTML parser's "before html" insertion mode makes a leading
+ * comment a child of the document, before `<html>`), so
+ * `collectChildrenSlots(doc.body)` never sees the opening marker, finds no
+ * shared slot, and `applySwap` falls to the destructive full-body swap that
+ * strips the head stylesheets and the outer layout. So a fragment is parsed in
+ * BODY (fragment) context instead, keeping the marker with its content.
+ * `body.setHTMLUnsafe` also processes Declarative Shadow DOM, so a shadow
+ * component inside the swapped content still re-attaches its root; the
+ * `<template>` path is the fallback for browsers without it (markers preserved,
+ * DSD not, which matches the pre-`setHTMLUnsafe` baseline).
+ *
  * @param {string} html
  * @returns {Document | null}
  */
 function parseHTML(html) {
+  const isFragment = !/^\s*(?:<!doctype|<html)/i.test(html);
+  if (isFragment && typeof document !== 'undefined' && document.implementation) {
+    try {
+      const doc = document.implementation.createHTMLDocument();
+      if (typeof doc.body.setHTMLUnsafe === 'function') {
+        doc.body.setHTMLUnsafe(html);
+      } else {
+        const t = doc.createElement('template');
+        t.innerHTML = html;
+        doc.body.appendChild(t.content);
+      }
+      return doc;
+    } catch {
+      // Fall through to a document parse (still functional, just the #936 path).
+    }
+  }
   if (typeof Document !== 'undefined' && typeof Document.parseHTMLUnsafe === 'function') {
     return Document.parseHTMLUnsafe(html);
   }
@@ -1273,9 +1309,19 @@ function prefetch(href) {
     return;
   }
 
+  const have = buildHaveHeader();
+  // #936: while the document is still parsing, the closing `<!--/wj:children-->`
+  // marker at the bottom of the body may not exist yet, so `buildHaveHeader()`
+  // returns '' meaning "markers not parsed yet", NOT "this page has no layout".
+  // A touch-device viewport prefetch fires early enough (mid-parse) to hit this
+  // window on real Android Chrome. Caching that empty-`have` response (a full
+  // page) would later drive the destructive full-body swap fallback. Skip the
+  // speculative fetch; the click path re-fetches with a correct `have` once the
+  // document has parsed (and applySwap now falls back to a full load anyway).
+  if (!have && typeof document !== 'undefined' && document.readyState === 'loading') return;
+
   prefetchInflight.add(key);
   const headers = { 'x-webjs-router': '1', 'x-webjs-prefetch': '1' };
-  const have = buildHaveHeader();
   if (have) headers['x-webjs-have'] = have;
 
   fetch(href, { method: 'GET', headers, credentials: 'same-origin' })
@@ -2464,8 +2510,14 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc)
     return;
   }
 
-  // 3. Full body swap fallback. Use full head merge: different root
-  // layout, so stale head elements should be removed.
+  // 3. Full body swap fallback: no shared layout marker (a genuine root-layout
+  // change, or a same-layout nav whose markers could not be paired). Full head
+  // merge, so a real root-layout change removes stale head elements. `mergeHead`
+  // now PRESERVES stylesheets and `<style>` unconditionally (#936): even if the
+  // client reaches this path with an incoming head that lacks the app's
+  // `<link rel=stylesheet>` (a partial or mangled response, e.g. from a
+  // mid-parse empty-`have` prefetch), the live CSS is never stripped, so the
+  // swap can no longer leave the page unstyled.
   mergeHead(doc.head);
   // Persist permanent elements by node identity across the full-body
   // swap: move each live [data-webjs-permanent][id] node into the matching
@@ -2677,7 +2729,16 @@ function diffElementInPlace(dst, src) {
   // property change through `attributeChangedCallback`, so the component
   // re-renders ITSELF; the router must not touch its internals. This mirrors
   // Turbo/morphdom, which leave custom elements alone by default.
-  if (isHydratedComponent(dst)) return;
+  //
+  // One carve-out (#908): a light-DOM component's projected <slot> content is
+  // page-authored (moved into the slot by the slot runtime), NOT render-owned,
+  // so a reused component would otherwise keep showing STALE slotted content
+  // when the nav supplies different content. Re-project ONLY those slot
+  // children; the render-owned nodes stay untouched, so #906 does not regress.
+  if (isHydratedComponent(dst)) {
+    reprojectSlottedContent(dst, src);
+    return;
+  }
 
   // Recurse into children: collect both sides, run reconcileSiblings on
   // them with synthetic boundary markers. Cheap implementation: use
@@ -2702,6 +2763,161 @@ function isHydratedComponent(el) {
   return /** @type {any} */ (el)[Symbol.for('webjs.instance')] != null;
 }
 
+/**
+ * True when `slot` belongs directly to `host`, i.e. no OTHER custom element
+ * sits between them. A slot nested inside a child custom element belongs to
+ * THAT component (its own slot state owns it), so the host must not touch it.
+ *
+ * @param {Element} slot
+ * @param {Element} host
+ * @returns {boolean}
+ */
+function isOwnLightSlot(slot, host) {
+  for (let p = slot.parentElement; p && p !== host; p = p.parentElement) {
+    if (p.tagName.includes('-')) return false;
+  }
+  return true;
+}
+
+/**
+ * Group a component's own `data-projection="actual"` light slots by name,
+ * first-wins (mirroring the slot runtime + SSR first-wins rule). Slots nested
+ * inside a child custom element are excluded (they belong to that child).
+ *
+ * @param {Element} host
+ * @returns {Map<string|null, HTMLSlotElement>}
+ */
+function ownActualLightSlots(host) {
+  /** @type {Map<string|null, HTMLSlotElement>} */
+  const byName = new Map();
+  const sel = `slot[${LIGHT_SLOT_ATTR}][${PROJECTION_ATTR}="${PROJECTION_ACTUAL}"]`;
+  for (const slot of host.querySelectorAll(sel)) {
+    const s = /** @type {HTMLSlotElement} */ (slot);
+    if (!isOwnLightSlot(s, host)) continue;
+    const name = s.getAttribute('name') || null;
+    if (!byName.has(name)) byName.set(name, s);
+  }
+  return byName;
+}
+
+/**
+ * The component's own light slot for `name`, whatever its projection state
+ * (first-wins by document order). Used to resolve the slot to fill on a
+ * fallback->actual transition, where the target slot is currently `fallback`
+ * so it is absent from `ownActualLightSlots`. Nested-child slots are excluded.
+ *
+ * @param {Element} host
+ * @param {string|null} name
+ * @returns {HTMLSlotElement | null}
+ */
+function ownLightSlotForName(host, name) {
+  for (const slot of host.querySelectorAll(`slot[${LIGHT_SLOT_ATTR}]`)) {
+    const s = /** @type {HTMLSlotElement} */ (slot);
+    if (!isOwnLightSlot(s, host)) continue;
+    if ((s.getAttribute('name') || null) === name) return s;
+  }
+  return null;
+}
+
+/**
+ * Per-index node-identity equality of two node lists. Used to decide whether a
+ * slot's assigned-node SET actually changed (so `slotchange` should fire); an
+ * in-place text edit that reuses the same node is NOT a set change.
+ *
+ * @param {ArrayLike<Node>} a
+ * @param {ArrayLike<Node>} b
+ * @returns {boolean}
+ */
+function sameNodeList(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Re-project the page-authored slotted content of a REUSED hydrated light-DOM
+ * component across a soft nav (#908), without touching its render-owned
+ * subtree.
+ *
+ * The #906 guard treats a hydrated component as opaque so the router never
+ * corrupts its lit-html-owned nodes. But the projected children inside a
+ * light-DOM `<slot data-webjs-light data-projection="actual">` are
+ * page-authored (moved there by the slot runtime), NOT held by lit-html parts,
+ * so reconciling ONLY those children is safe and cannot reintroduce #906. Both
+ * the live DOM and the incoming SSR HTML carry the same slot markers
+ * (render-server emits them), so slots pair up by name + document order.
+ *
+ * Three cases, by how a slot's projection state changes across the nav:
+ *   - actual->actual (content changed): identity-preserving `reconcileChildren`
+ *     on the page-authored slot children, exactly as #908 shipped.
+ *   - actual->fallback (content REMOVED) and fallback->actual (content ADDED):
+ *     a slot's fallback is RENDER-OWNED (the compiled fallback template held by
+ *     the slot-part), so these are NOT a raw reconcile. Drive them through the
+ *     slot runtime's own primitives (`applyFallback` / `applyActualAssignment`)
+ *     on the ONE resolved own slot, which restore or swap the render-owned
+ *     fallback without reconciling any lit-html part (#912). This is applied
+ *     surgically to the target slot, NOT via a whole-host `projectChildren`
+ *     pass: `projectChildren` selects EVERY `data-webjs-light` slot in the
+ *     subtree (including a nested child component's), so running it here would
+ *     let this component's assignment reach into a nested child's same-named
+ *     slot and clobber its render-owned nodes (the #906 hazard, one level down).
+ *
+ * @param {Element} dst  Live hydrated component host.
+ * @param {Element} src  Incoming SSR copy of the same component.
+ */
+function reprojectSlottedContent(dst, src) {
+  // Only a light-DOM component that tracks slot assignments has projected
+  // page-authored content to update. No slot state (no <slot>, or a shadow-DOM
+  // component whose slotted nodes are ordinary light children) means nothing
+  // to re-project here.
+  const state = /** @type {any} */ (dst)[SLOT_STATE];
+  if (!state) return;
+
+  const liveSlots = ownActualLightSlots(dst);
+  const incSlots = ownActualLightSlots(src);
+  if (liveSlots.size === 0 && incSlots.size === 0) return;
+
+  // A slot name is `actual` on the live side, the incoming side, or both. Walk
+  // the union so a boundary transition (present on only one side) is handled.
+  const names = new Set([...liveSlots.keys(), ...incSlots.keys()]);
+  for (const name of names) {
+    const liveSlot = liveSlots.get(name);
+    const incSlot = incSlots.get(name);
+    if (liveSlot && incSlot) {
+      // actual->actual: the slot's children are page-authored, so
+      // reconcileChildren is safe: it preserves node identity where it can and
+      // never touches lit-html parts. Keep the slot runtime's assignment
+      // bookkeeping in sync so a later re-render materialises THESE nodes.
+      const prevAssigned = state.lastSnapshot.get(liveSlot) || [];
+      reconcileChildren(liveSlot, incSlot);
+      const children = [...liveSlot.childNodes];
+      state.assignedByName.set(name, children);
+      state.lastSnapshot.set(liveSlot, children.slice());
+      // Fire slotchange on an assigned-node-SET change (add / remove / reorder),
+      // not an in-place text edit that reuses the same node: that matches the
+      // spec and keeps this branch uniform with the boundary branches below.
+      if (!sameNodeList(prevAssigned, children)) fireSlotChange(liveSlot);
+    } else if (liveSlot && !incSlot) {
+      // actual->fallback: incoming REMOVED this slot's content. Clear the
+      // assignment and flip THIS slot to fallback; applyFallback restores the
+      // render-owned fallback from the slot-part holding fragment.
+      state.assignedByName.delete(name);
+      if (applyFallback(state, liveSlot)) fireSlotChange(liveSlot);
+    } else {
+      // fallback->actual: incoming ADDED content where the live slot shows
+      // fallback. The target slot is currently fallback, so resolve it directly
+      // (it is absent from the actual-only map) and fill it with the imported
+      // page-authored nodes; applyActualAssignment tucks the render-owned
+      // fallback into the holding fragment first.
+      const targetSlot = ownLightSlotForName(dst, name);
+      if (!targetSlot) continue;
+      const nodes = [...incSlot.childNodes].map((n) => document.importNode(n, true));
+      state.assignedByName.set(name, nodes);
+      if (applyActualAssignment(state, targetSlot, nodes)) fireSlotChange(targetSlot);
+    }
+  }
+}
+
 /**
  * Reconcile dst's children to match src's children, in-place.
  *
@@ -3044,6 +3260,31 @@ function addNewHeadElements(newHead) {
   }
 }
 
+/**
+ * Is `el` a stylesheet the head merge must never remove: a `<style>` or a
+ * `<link rel~="stylesheet">`. WebJs ALWAYS keeps these on a soft nav, with no
+ * opt-out, and that is a deliberate divergence from Turbo. Turbo removes a
+ * stylesheet absent from the new head when it is tagged
+ * `data-turbo-track="dynamic"`, which is sound in Turbo because a Turbo visit
+ * always compares a COMPLETE old head to a COMPLETE new head, so "absent" means
+ * "this page removed it". WebJs's `X-Webjs-Have` optimization returns a REDUCED
+ * head (the shared app stylesheet is omitted because the client already has it),
+ * so "absent from the incoming head" means "optimized away", NOT "removed". A
+ * dynamic-removal opt-out would therefore re-introduce #936 (it would strip a
+ * still-needed sheet on any partial response), and WebJs is Tailwind-first (one
+ * global sheet, no page-specific sheets to drop), so the knob would be unsafe
+ * and unused. Keeping every stylesheet is correct here; a genuinely changed one
+ * is dropped by the deploy-level hard reload (build-id mismatch), not a soft swap.
+ *
+ * @param {Element} el
+ * @returns {boolean}
+ */
+function isPersistentHeadStyle(el) {
+  if (el.tagName === 'STYLE') return true;
+  return el.tagName === 'LINK' &&
+    (el.getAttribute('rel') || '').toLowerCase().split(/\s+/).includes('stylesheet');
+}
+
 /** @param {HTMLHeadElement} newHead */
 function mergeHead(newHead) {
   const currentHead = document.head;
@@ -3069,6 +3310,14 @@ function mergeHead(newHead) {
     if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') continue;
     if (el.tagName === 'BASE') continue;
     if (el.tagName === 'TITLE') continue;
+    // #936: NEVER remove a stylesheet or a `<style>` on a soft nav (Turbo's
+    // persistent-CSS model). The incoming head of a full-body-swap fallback can
+    // legitimately lack the app's `<link rel=stylesheet>` (a partial or mangled
+    // response, e.g. from a mid-parse empty-`have` prefetch): removing the live
+    // one there leaves the whole page unstyled until a manual refresh, the
+    // headline #936 symptom. Keeping it is safe: a genuinely stale sheet is
+    // dropped by the deploy-level hard reload (build-id mismatch), not here.
+    if (isPersistentHeadStyle(el)) continue;
     if (!newSet.has(outerHTMLForDiff(el))) el.remove();
   }
 
@@ -3303,11 +3552,13 @@ export {
   clearFormBusy as _clearFormBusy,
   collectChildrenSlots as _collectChildrenSlots,
   longestSharedPath as _longestSharedPath,
+  parseHTML as _parseHTML,
   keyOf as _keyOf,
   diffElementInPlace as _diffElementInPlace,
   reconcileChildren as _reconcileChildren,
   onPopState as _onPopState,
   applySwap as _applySwap,
+  buildHaveHeader as _buildHaveHeader,
   snapshotCache as _snapshotCache,
   prefetchCache as _prefetchCache,
   LIVE_ATTRS as _LIVE_ATTRS,

package/src/slot.js

@@ -709,7 +709,7 @@ function handleSlotRemoved(state, slot) {
  * @returns {boolean} True if the slot's assignment changed compared to
  *   its last snapshot (so slotchange should fire).
  */
-function applyActualAssignment(state, slot, assigned) {
+export function applyActualAssignment(state, slot, assigned) {
   const wasFallback = slot.getAttribute(PROJECTION_ATTR) !== PROJECTION_ACTUAL;
   const prev = state.lastSnapshot.get(slot) || [];
   const equal = !wasFallback && arraysEqual(prev, assigned);
@@ -747,7 +747,7 @@ function applyActualAssignment(state, slot, assigned) {
  * @returns {boolean} True if the slot transitioned from actual to
  *   fallback this pass.
  */
-function applyFallback(state, slot) {
+export function applyFallback(state, slot) {
   const wasActual = slot.getAttribute(PROJECTION_ATTR) === PROJECTION_ACTUAL;
   slot.setAttribute(PROJECTION_ATTR, PROJECTION_FALLBACK);
   if (!wasActual) {
@@ -841,7 +841,7 @@ export function moveSlotChildrenToPending(host, slot) {
 // ---------------------------------------------------------------------------
 
 /** Fire a `slotchange` event on the slot (bubbles, not composed; per spec). */
-function fireSlotChange(slot) {
+export function fireSlotChange(slot) {
   slot.dispatchEvent(new Event('slotchange', { bubbles: true, composed: false }));
 }