@takazudo/zudo-doc 5.6.0 → 5.8.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.8.0] - 2026-08-20
+
+### Features
+
+- Added strict anchor validation to the showcase and generated-project link checkers, including source-first validation for scaffolded sites. (`b50bd9aac`, `59127e7fe`)
+- Added a published-version guard that prevents release scaffolds from pinning first-party packages that are not yet available from npm. (`4bdc37132`, `8c234c08e`)
+- Shipped a complete nav-overflow regeneration path with ejected headers, preserving stable CSP bytes while allowing local nav behavior and class-token customization. (`1b3d501c3`, `721ff37d3`)
+
+### Bug Fixes
+
+- Made nested island props preservation explicit with `data-zd-props-preserve`, preventing opted-out islands from receiving props updates or remount flags during client navigation. (`e75cff084`)
+
+### Other Changes
+
+- Strengthened `docTags` regression coverage so an unselected feature cannot emit either a `true` or `false` config field. (`37dec787c`)
+- Updated `@takazudo/zdtp` to 0.4.12 across the package, showcase, and generated scaffold.
+
+## [5.7.0] - 2026-08-20
+
+### Features
+
+- `NAV_OVERFLOW_SCRIPT` is now shipped as a committed, drift-gated literal generated at package build time — its bytes no longer depend on the consumer's bundler, so one published CSP inline-script hash covers every rendering. The frozen output is byte-identical to the previous render-time assembly, so no hash changes with this release (93865aac)
+- A `check:nav-overflow-drift` guard now runs in b4push (step 14 of the 29-step suite), CI, the b4push/CI parity manifest, and `prepack`, so any future change to the script's sources fails loudly instead of silently shifting consumer CSP hashes (a9440c2e)
+
+### Bug Fixes
+
+- The mobile drawer no longer keeps a stale section tree and active marker after a same-locale cross-section soft navigation: nested-island `data-props` inside persisted elements are refreshed at the `zfb:before-swap` seam, generalizing zfb's top-level persisted-island refresh. Locale-toggle behavior and header persistence are unchanged (9dd1b77c)
+- Islands whose dynamic import is still in flight across a swap now remount from the refreshed props (`data-zfb-island-remount` is set on change), closing a race where the drawer could mount from the pre-navigation snapshot (797e9a8c)
+- `prepack` now also gates on `check:search-widget-drift`, so packing from a drifted tree can no longer publish CSP-breaking `SEARCH_WIDGET_SCRIPT` bytes (5103feb3)
+
+### Other Changes
+
+- New mobile cross-section soft-navigation e2e regression spec for the drawer (smoke fixture), with shared drawer helpers (5ac8f536)
+- Route-injection parity snapshots re-baselined with full attribution; the file now documents that a further unexplained hash move must be treated as live non-determinism and diagnosed rather than re-pinned (7a607cd5)
+- Testing docs aligned with the test-hardening retiering: fast/slow lanes clarified and post-retiering counts corrected (07fff398)
+
+## [5.6.1] - 2026-08-19
+
+### Bug Fixes
+
+- `stripMarkdown` now decodes numeric and common named HTML character references while preserving intraword underscores in identifiers, preventing corrupted plain text in the search index and `llms.txt` output. (634458d2)
+
 ## [5.6.0] - 2026-08-19
 
 ### Features

package/README.md

@@ -67,6 +67,23 @@ pnpm add @takazudo/zfb-md-wasm
 
 Projects scaffolded by `create-zudo-doc` already include it. If you never render `<HtmlPreview>` / `<HighlightedCode>`, you can omit it.
 
+## Ejected header customization
+
+`zudo-doc eject header` copies a complete frozen-script regeneration path into
+`src/components/zudo-doc/header`. After changing the ejected `nav-active.ts` or
+`nav-class-tokens.ts`, regenerate the local client controller and commit the
+result:
+
+```sh
+node ./src/components/zudo-doc/header/gen-nav-overflow-script.mjs
+```
+
+The command uses the two local customization inputs plus the installed
+package's current-path and page-event inputs. Its `esbuild` transformer is
+provided by `@takazudo/zudo-doc`; no additional project dependency is needed.
+The resulting `nav-overflow-generated-script.ts` stays frozen for stable CSP
+hashes across consumer bundlers.
+
 ## ⚠️ HTML preview iframe sandbox — trust assumption
 
 `<HtmlPreview>` / `<HtmlPreviewWrapper>` render their preview inside an `<iframe srcdoc>` whose `sandbox` attribute **defaults** to:

package/dist/eject/index.js

@@ -340,6 +340,15 @@ ${status} from @takazudo/zudo-doc@${installedVersion}
 `
     )
   );
+  if (component === "header") {
+    console.log(
+      pc.bold("Header frozen-script regeneration:") + `
+  After editing ${localDir}/nav-active.ts or nav-class-tokens.ts, run:
+  node ./${localDir}/gen-nav-overflow-script.mjs
+  Commit ${localDir}/nav-overflow-generated-script.ts with your edits.
+`
+    );
+  }
 }
 export {
   EJECTABLE,

package/dist/header/nav-active.d.ts

@@ -40,18 +40,21 @@ export declare function pathForMatch(pathWithoutBase: string, lang: string | und
  * Segment-aware prefix test: nav path `/docs/guides` matches `/docs/guides`
  * and `/docs/guides/...` but NOT `/docs/guideship`.
  *
- * Exported (not just module-private) so `nav-overflow-script.ts` can embed it
- * verbatim via `.toString()` alongside `computeActiveNavPath` — that function
- * closes over this one, so a bare `computeActiveNavPath.toString()` embed
- * would reference an undefined `pathMatchesNavPath` in the browser (see the
- * caution note on `computeActiveNavPath` below). Kept self-contained (no
- * outer references) for the same reason.
+ * Exported (not just module-private) so `scripts/gen-nav-overflow-script.mjs`
+ * can embed it verbatim via `.toString()` alongside `computeActiveNavPath` —
+ * that function closes over this one, so a bare `computeActiveNavPath.toString()`
+ * embed would reference an undefined `pathMatchesNavPath` in the browser (see
+ * the caution note on `computeActiveNavPath` below). Kept self-contained (no
+ * outer references) for the same reason. The generator freezes both into the
+ * committed `nav-overflow-generated-script.ts` literal at package build time
+ * (zudolab/zudo-doc#3534) — this is no longer a live per-module-eval embed.
  */
 export declare function pathMatchesNavPath(currentPath: string, navPath: string): boolean;
 /**
  * CAUTION (zudolab/zudo-doc#3398): this closes over `pathMatchesNavPath`
- * above. `nav-overflow-script.ts` embeds both via `.toString()` (never this
- * one alone) so the generated browser script is self-contained.
+ * above. `scripts/gen-nav-overflow-script.mjs` embeds both via `.toString()`
+ * (never this one alone) so the frozen browser script (`./nav-overflow-generated-script.ts`,
+ * zudolab/zudo-doc#3534) is self-contained.
  */
 export declare function computeActiveNavPath(navItems: readonly NavItemLike[], pathForMatchValue: string): string | undefined;
 /**

package/dist/header/nav-overflow-generated-script.d.ts

@@ -0,0 +1,11 @@
+/** Returns the frozen desktop-nav overflow controller IIFE script. NOTE: the
+ * vitest drift guard imports buildNavOverflowScript from
+ * scripts/gen-nav-overflow-script.mjs (a fresh re-generation) — NEVER from
+ * this module: comparing NAV_OVERFLOW_SCRIPT below against this same file's
+ * function would be a vacuous self-comparison. */
+export declare function buildNavOverflowScript(): string;
+/** Client-side script string for the desktop header nav overflow controller.
+ * See the module header of this generator for the embedding contract; see
+ * current-path/index.ts / header/nav-active.ts / header/nav-class-tokens.ts /
+ * transitions/page-events.ts for the frozen sources. */
+export declare const NAV_OVERFLOW_SCRIPT: string;

package/dist/header/nav-overflow-generated-script.js

@@ -0,0 +1,302 @@
+function buildNavOverflowScript() {
+  return `(function () {
+  var cleanupNavOverflow = null;
+
+  function trimSlashes(p) {
+    while (p.length > 1 && p.charAt(p.length - 1) === "/") p = p.slice(0, -1);
+    return p || "/";
+  }
+
+  function navPathname(a) {
+    try { return trimSlashes(new URL(a.href, location.href).pathname); }
+    catch (e) { return ""; }
+  }
+
+  // Explicit current-route override, embedded from current-path/index.ts so
+  // this script cannot drift from the three other read sites
+  // (zudolab/zudo-doc#3398, #3408).
+  var CURRENT_PATH_DATASET_KEY="zdCurrentPath";var readCurrentPath=function readCurrentPath(datasetKey, explicit) {
+  const override = typeof document === "undefined" ? void 0 : document.documentElement.dataset[datasetKey];
+  return explicit || override || (typeof window === "undefined" ? void 0 : window.location.pathname);
+};
+
+  // Shared matching core (zudolab/zudo-doc#3398): embedded verbatim from
+  // nav-active.ts so this script's longest-match walk cannot drift from the
+  // SSR header's own computeActiveNavPath call (header.tsx). computeActiveNavPath
+  // closes over pathMatchesNavPath, so both are embedded together.
+  var pathMatchesNavPath = function pathMatchesNavPath(currentPath, navPath) {
+  if (currentPath === navPath) return true;
+  const prefix = navPath.endsWith("/") ? navPath : \`\${navPath}/\`;
+  return currentPath.startsWith(prefix);
+};
+  var computeActiveNavPath = function computeActiveNavPath(navItems, pathForMatchValue) {
+  const allNavPaths = navItems.flatMap((item) => {
+    const paths = [item.path];
+    if (item.children) {
+      paths.push(...item.children.map((child) => child.path));
+    }
+    return paths;
+  });
+  return allNavPaths.filter((p) => pathMatchesNavPath(pathForMatchValue, p)).sort((a, b) => b.length - a.length)[0];
+};
+
+  // Recompute which header nav item is "active" from the CURRENT URL and
+  // repaint the highlight. SSR sets the active item on first paint, but the
+  // header is persisted across same-locale client-router swaps
+  // (data-zfb-transition-persist), so without this the highlight would stay
+  // frozen on the page where the header was first rendered. Mirrors the
+  // sidebar island's client-side approach (match the current path against
+  // each entry's href) and the SSR longest-match + dropdown-parent rules.
+  // URL-based: hrefs and the current path both carry the base + locale
+  // prefix, so they compare directly without stripping.
+  function applyActiveNav() {
+    var nav = document.querySelector("[data-header-nav]");
+    if (!nav) return;
+    var topItems = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
+    if (topItems.length === 0) return;
+
+    var cur = trimSlashes(readCurrentPath(CURRENT_PATH_DATASET_KEY));
+
+    // Build NavItemLike-shaped entries from the live DOM so the shared
+    // computeActiveNavPath can do the deepest-match walk \u2014 the same call
+    // shape the SSR header uses (matches computeActiveNavPath). A dropdown
+    // missing its own top-level anchor is skipped entirely (path "" would
+    // otherwise match every current path \u2014 pathMatchesNavPath treats "" as
+    // the root "/"), mirroring the parentLink guard used below for the same
+    // malformed-markup case.
+    var navItems = [];
+    topItems.forEach(function (it) {
+      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
+      var topA = isDropdown ? it.querySelector(":scope > a") : it;
+      if (!topA) return;
+      var children = [];
+      if (isDropdown) {
+        it.querySelectorAll(":scope > div a").forEach(function (c) {
+          children.push({ path: navPathname(c) });
+        });
+      }
+      navItems.push({ path: navPathname(topA), children: children });
+    });
+
+    var activePath = computeActiveNavPath(navItems, cur) || "";
+
+    function setTopActive(a, active) {
+      if (!a) return;
+      if (active) {
+        a.classList.add("bg-fg", "text-bg");
+        a.classList.remove("text-muted", "hover:text-accent", "hover:underline", "focus:underline", "focus:text-accent");
+        a.setAttribute("aria-current", "page");
+      } else {
+        a.classList.remove("bg-fg", "text-bg");
+        a.classList.add("text-muted", "hover:text-accent", "hover:underline", "focus:underline", "focus:text-accent");
+        a.removeAttribute("aria-current");
+      }
+    }
+
+    topItems.forEach(function (it) {
+      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
+      var topA = isDropdown ? it.querySelector(":scope > a") : it;
+      var topActive = false;
+
+      if (isDropdown) {
+        var parentMatch = !!topA && navPathname(topA) === activePath && activePath !== "";
+        var anyChild = false;
+        it.querySelectorAll(":scope > div a").forEach(function (c) {
+          var childActive = navPathname(c) === activePath && activePath !== "";
+          if (childActive) {
+            anyChild = true;
+            c.setAttribute("data-active", "");
+            c.classList.add("font-bold", "text-accent");
+            c.classList.remove("text-fg", "hover:text-accent", "focus-visible:text-accent");
+          } else {
+            c.removeAttribute("data-active");
+            c.classList.remove("font-bold", "text-accent");
+            c.classList.add("text-fg", "hover:text-accent", "focus-visible:text-accent");
+          }
+        });
+        topActive = parentMatch || anyChild;
+        var svg = topA ? topA.querySelector("svg") : null;
+        if (svg) {
+          if (topActive) { svg.classList.add("text-bg"); svg.classList.remove("text-muted"); }
+          else { svg.classList.add("text-muted"); svg.classList.remove("text-bg"); }
+        }
+      } else {
+        topActive = activePath !== "" && navPathname(topA) === activePath;
+      }
+
+      setTopActive(topA, topActive);
+    });
+  }
+
+  function initNavOverflow() {
+    if (cleanupNavOverflow) cleanupNavOverflow();
+
+    // Repaint the active highlight for the current URL before measuring /
+    // cloning, so the overflow "\xB7\xB7\xB7" menu mirrors the correct active state.
+    applyActiveNav();
+
+    var nav = document.querySelector("[data-header-nav]");
+    var moreContainer = document.querySelector("[data-nav-more]");
+    var moreMenu = document.querySelector("[data-nav-more-menu]");
+    var moreToggle = document.querySelector("[data-nav-more-toggle]");
+    if (!nav || !moreContainer || !moreMenu || !moreToggle) return;
+
+    var items = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
+    if (items.length === 0) return;
+
+    var controller = new AbortController();
+
+    function update() {
+      items.forEach(function (el) { el.style.display = ""; });
+      moreContainer.style.display = "";
+      moreMenu.innerHTML = "";
+      moreMenu.classList.add("hidden");
+      moreToggle.setAttribute("aria-expanded", "false");
+
+      var itemWidths = items.map(function (el) { return el.offsetWidth; });
+      var moreWidth = moreContainer.offsetWidth;
+      var navGap = parseFloat(getComputedStyle(nav).columnGap) || 0;
+      var available = nav.clientWidth;
+
+      if (available <= 0) {
+        moreContainer.style.display = "none";
+        return;
+      }
+
+      var total = 0;
+      for (var i = 0; i < itemWidths.length; i++) {
+        total += itemWidths[i] + (i > 0 ? navGap : 0);
+      }
+
+      if (total <= available) {
+        moreContainer.style.display = "none";
+        return;
+      }
+
+      var used = 0;
+      var cutoffIndex = 0;
+
+      for (var i2 = 0; i2 < items.length; i2++) {
+        var w = itemWidths[i2] + (i2 > 0 ? navGap : 0);
+        if (used + w > available - moreWidth - navGap) break;
+        used += w;
+        cutoffIndex = i2 + 1;
+      }
+
+      for (var i3 = cutoffIndex; i3 < items.length; i3++) {
+        items[i3].style.display = "none";
+      }
+
+      for (var i4 = cutoffIndex; i4 < items.length; i4++) {
+        var el = items[i4];
+        var isDropdown = el.hasAttribute("data-nav-item-dropdown");
+
+        if (isDropdown) {
+          var parentLink = el.querySelector(":scope > a");
+          var childLinks = el.querySelectorAll(":scope > div a");
+          if (parentLink) {
+            var li = document.createElement("li");
+            var a = document.createElement("a");
+            a.href = parentLink.href;
+            var parentText = parentLink.textContent ? parentLink.textContent.trim().replace(/\\s+/g, " ") : "";
+            a.textContent = parentText;
+            a.className = "block px-hsp-md py-vsp-2xs text-small font-bold hover:bg-accent/10 hover:underline focus-visible:underline focus-visible:text-accent text-fg hover:text-accent";
+            if (parentLink.getAttribute("aria-current") === "page") {
+              a.className += " text-accent";
+            }
+            li.appendChild(a);
+            moreMenu.appendChild(li);
+          }
+          childLinks.forEach(function (child) {
+            var li = document.createElement("li");
+            var a = document.createElement("a");
+            a.href = child.href;
+            a.textContent = child.textContent ? child.textContent.trim() : "";
+            var isChildActive = child.hasAttribute("data-active");
+            a.className = isChildActive
+              ? "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small font-bold text-accent hover:bg-accent/10 hover:underline focus-visible:underline"
+              : "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:underline focus-visible:text-accent";
+            li.appendChild(a);
+            moreMenu.appendChild(li);
+          });
+        } else {
+          var anchor = el;
+          var li2 = document.createElement("li");
+          var a2 = document.createElement("a");
+          a2.href = anchor.href;
+          a2.textContent = anchor.textContent ? anchor.textContent.trim() : "";
+          a2.className = "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline focus-visible:text-accent text-fg hover:text-accent";
+          if (anchor.getAttribute("aria-current") === "page") {
+            a2.className += " font-bold text-accent";
+          }
+          li2.appendChild(a2);
+          moreMenu.appendChild(li2);
+        }
+      }
+    }
+
+    moreToggle.addEventListener("click", function () {
+      var isOpen = !moreMenu.classList.contains("hidden");
+      moreMenu.classList.toggle("hidden", isOpen);
+      moreToggle.setAttribute("aria-expanded", String(!isOpen));
+    }, { signal: controller.signal });
+
+    document.addEventListener("click", function (e) {
+      if (!moreContainer.contains(e.target)) {
+        moreMenu.classList.add("hidden");
+        moreToggle.setAttribute("aria-expanded", "false");
+      }
+    }, { signal: controller.signal });
+
+    document.addEventListener("keydown", function (e) {
+      if (e.key !== "Escape") return;
+      if (!moreMenu.classList.contains("hidden")) {
+        moreMenu.classList.add("hidden");
+        moreToggle.setAttribute("aria-expanded", "false");
+        moreToggle.focus();
+        return;
+      }
+      var active = document.activeElement;
+      var dropdown = active && active.closest ? active.closest("[data-nav-item-dropdown]") : null;
+      if (dropdown && active && active.blur) {
+        active.blur();
+      }
+    }, { signal: controller.signal });
+
+    var dropdowns = nav.querySelectorAll("[data-nav-item-dropdown]");
+    dropdowns.forEach(function (dd) {
+      var trigger = dd.querySelector(":scope > a");
+      if (!trigger) return;
+      function setExpanded(v) {
+        trigger.setAttribute("aria-expanded", String(v));
+      }
+      dd.addEventListener("mouseenter", function () { setExpanded(true); }, { signal: controller.signal });
+      dd.addEventListener("mouseleave", function () { setExpanded(false); }, { signal: controller.signal });
+      dd.addEventListener("focusin", function () { setExpanded(true); }, { signal: controller.signal });
+      dd.addEventListener("focusout", function (e) {
+        if (!dd.contains(e.relatedTarget)) {
+          setExpanded(false);
+        }
+      }, { signal: controller.signal });
+    });
+
+    var ro = new ResizeObserver(update);
+    ro.observe(nav);
+    controller.signal.addEventListener("abort", function () { ro.disconnect(); });
+
+    document.fonts.ready.then(update);
+
+    update();
+
+    cleanupNavOverflow = function () { controller.abort(); };
+  }
+
+  initNavOverflow();
+  document.addEventListener("zfb:after-swap", initNavOverflow);
+})();`;
+}
+const NAV_OVERFLOW_SCRIPT = buildNavOverflowScript();
+export {
+  NAV_OVERFLOW_SCRIPT,
+  buildNavOverflowScript
+};

package/dist/header/nav-overflow-script.d.ts

@@ -1 +1 @@
-export declare const NAV_OVERFLOW_SCRIPT: string;
+export { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-generated-script.js";