@takazudo/zudo-doc 6.2.0 → 7.1.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [7.1.0] - 2026-10-23
+
+### Bug Fixes
+
+- Inline code inside table cells no longer breaks mid-word. The narrow-width `overflow-wrap: anywhere` from 7.0.0 collapsed the min-content width of table columns, so short identifiers such as `slug` were split instead of the table wrapper scrolling. Code in `th` / `td` goes back to `overflow-wrap: break-word`. (9d36a247, a30cdd85)
+
+### Other Changes
+
+- Requires the published zfb 4.7.0 family: the `@takazudo/zfb`, `zfb-runtime` and `zfb-md-wasm` peer floors move from `^4.5.2` to `^4.7.0`. This picks up the 4.5.3 MDX compile fixes: multiline expressions such as HtmlPreview template-literal props keep their authored whitespace, and a template string that contains a decimal comparison no longer fails to compile with `Unexpected numeric literal`. It also picks up the 4.5.4 islands fix: edits outside the browser graph, such as a page title or a Markdown body, no longer change the shipped islands JavaScript. 4.6.0 adds the RUSTSEC-2026-0381 and RUSTSEC-2026-0382 fixes in the CLI's HTTPS client, stages only the pnpm store packages a page can actually reach into the build shadow, and fixes two Windows path bugs in the SSR shadow and plugin virtual modules. 4.7.0 makes Rolldown the page/SSR and island bundler in place of esbuild, so shipped island asset hashes change on the first build after upgrading (set `ZFB_BUNDLER=esbuild` to go back); it also applies a project's tsconfig JSX options to TSX shipped inside packages (zfb#4407), and fixes Windows island builds that import a `?url` resource such as `@takazudo/zfb-md-wasm/highlight` (zfb#4413). Under Rolldown the optional `katex` and `diff` peers stay optional: a new `optional-peers` plugin shadows a peer that is not installed, or whose `math` / `docHistory` feature is off, so the project still builds and an enabled feature shows its usual "install the peer" message (workaround for zfb#4429). Upgrade the zfb family (and `zfb-adapter-cloudflare` when used) together. (f118e4e0, 2b222e31, 957c252d, 81fcc982, 39f1e8a8, 2e6676db)
+
+## [7.0.0] - 2026-10-15
+
+### Breaking Changes
+
+- The supported Node.js runtime moves to the current production LTS line, Node 24 (`>=24 <25`). Node 22 is no longer supported. (98c94df73)
+- Raises the optional KaTeX peer floor to `^0.18.2 || ^0.19.0` for the GHSA-238p-pmpm-9mq7 patch; 0.16.x is no longer supported. Updates the internal KaTeX color selector while preserving server-only rendering, error fallback and math-disabled builds without KaTeX. Math-enabled hosts must install a supported version and import its local CSS. (9ee3950c9)
+- Requires the published zfb 4.5.2 family: the `@takazudo/zfb`, `zfb-runtime` and `zfb-md-wasm` peer floors move from `^4.5.0` to `^4.5.2`. This picks up live `public/assets/` development serving, explicit and compact one-line MDX table fixes, and a `zfb dev` ready banner that waits until routes are published. Upgrade the zfb family (and `zfb-adapter-cloudflare` when used) together. (e5b7de457, d5e0d7078)
+- The `@takazudo/zudo-doc-history-server` peer floor moves from `^6.0.0` to `^7.0.0` with this major release.
+
+### Bug Fixes
+
+- Keep the header stationary during dynamic page transitions, including when destination markup replaces it, and keep the desktop sidebar stationary within the same navigation category and locale/version/tree context. Fresh destination content and existing sidebar state handling are preserved; changing articles and table-of-contents content still animate. Sidebar entry and exit also cover `hide_sidebar` pages. Loading feedback now covers the content area without dimming the header or desktop sidebar, stays out of the page animation, and clears on the content swap or navigation cancellation. (ae7152ad5, 6abeadf5f, 479309f1f)
+- Ordinary documentation prose and navigation labels now wrap at narrow widths instead of overflowing horizontally (`overflow-wrap: anywhere` on content). Preformatted code keeps its local scrolling. (648e38da8)
+
 ## [6.2.0] - 2026-10-14
 
 ### Features

package/README.md

@@ -109,7 +109,7 @@ If your project renders **semi-trusted or user-submitted** HTML in a preview, ov
 
 **6.0.0** is the coordinated major release of `@takazudo/zudo-doc`,
 `@takazudo/zudo-doc-history-server` and `create-zudo-doc`. The current workspace
-targets the published **zfb 4.5.0** family (peer floor **^4.5.0**).
+targets the published **zfb 4.7.0** family (peer floor **^4.7.0**).
 [Upstream #4097](https://github.com/Takazudo/zudo-front-builder/issues/4097) is
 resolved; its strict published 4.3.1 consumer control passed 3/3 with no skips or
 retries in the [source-bound verification](../../docs/findings/zfb-4.3.1/verification.md).
@@ -160,3 +160,18 @@ zfb CSS generation. Do not use physical package `dist/*.css` import paths.
 This package is published to npm as `@takazudo/zudo-doc` (since `0.2.0`, `latest` tracks the current line). Inside this repo the host site consumes it as a workspace package through its compiled `dist/` — `pnpm dev` at the repo root runs two watchers in parallel, `tsup --watch` for the JS and `tsc -p tsconfig.build.json --watch` for the `.d.ts`, so edits under `src/` rebuild both halves automatically; for a one-off rebuild use `pnpm --filter @takazudo/zudo-doc build`.
 
 zfb itself comes from npm (versions pinned in the root `package.json`). To develop against a local zfb checkout, use the temporary `pnpm.overrides` link escape hatch documented in root `CONTRIBUTING.md` — do not commit the override.
+
+### Optional math peer (unreleased compatibility floor)
+
+Math-enabled consumers install `katex@^0.19.0` (supported peer range:
+`^0.18.2 || ^0.19.0`) and import `katex/dist/katex.min.css` before
+`@takazudo/zudo-doc/features.css` in their CSS entry. CSS and fonts are bundled
+locally. The consumer matrix covers 0.18.2, 0.18.11 and 0.19.0. The old 0.16
+branch is excluded because GHSA-238p-pmpm-9mq7 is patched from 0.18.2.
+KaTeX 0.18's `.katex-base` selector replaces `.base` in the package color rule.
+
+`MathBlock` remains server-rendered, with inline/display wrappers, safe defaults
+and visible malformed-input fallback. A math-disabled consumer needs neither
+KaTeX nor its stylesheet; module evaluation succeeds without it, and explicit
+`MathBlock` rendering reports a useful missing-peer error. This source change
+raises the compatibility floor and is not yet published to npm.

package/dist/compiled.css

@@ -626,6 +626,7 @@ body {
   color: var(--color-fg);
   font-size: var(--text-body);
   line-height: var(--leading-relaxed);
+  overflow-wrap: anywhere;
 }
 
 @layer zd-flow {
@@ -750,6 +751,10 @@ body {
   overflow-wrap: break-word;
 }
 
+.zd-content :where(th code, td code) {
+  overflow-wrap: break-word;
+}
+
 .zd-content :where(th) {
   font-weight: var(--font-weight-semibold);
   text-align: left;
@@ -1045,6 +1050,7 @@ a.text-accent.underline {
 
 .page-loading-overlay {
   position: fixed;
+  view-transition-name: zfb-loading;
   inset: 0;
   z-index: var(--z-index-modal, 100);
   display: flex;
@@ -1053,11 +1059,12 @@ a.text-accent.underline {
   background: var(--color-page-loading-overlay, color-mix(in oklch, var(--color-overlay, #000) 60%, transparent));
   opacity: 0;
   pointer-events: none;
-  transition: opacity .15s ease-out;
+  transition: none;
 }
 
 .page-loading-overlay[data-visible] {
   opacity: 1;
+  transition: opacity .15s ease-out;
 }
 
 a[data-zd-nav-pending], button[data-zd-nav-pending] {
@@ -1100,6 +1107,14 @@ a[data-zd-nav-pending], button[data-zd-nav-pending] {
   }
 }
 
+::view-transition-group(zfb-loading) {
+  animation: none;
+}
+
+::view-transition-old(zfb-loading), ::view-transition-new(zfb-loading) {
+  display: none;
+}
+
 header[data-header] {
   background-color: var(--color-surface, var(--color-bg));
   z-index: var(--z-index-toolbar, 20);
@@ -1294,7 +1309,7 @@ pre.hi-root .line .highlighted-word {
   white-space: nowrap;
 }
 
-.katex .base {
+.katex .katex-base {
   color: var(--zd-fg);
 }
 
@@ -1403,11 +1418,11 @@ pre.hi-root .line .highlighted-word {
   }
 }
 
-[data-zfb-transition-persist^="header-"] {
+body > header {
   view-transition-name: zfb-header;
 }
 
-[data-zfb-transition-persist^="sidebar-"] {
+#desktop-sidebar:not(.sr-only) {
   view-transition-name: zfb-sidebar;
 }
 
@@ -1415,26 +1430,34 @@ pre.hi-root .line .highlighted-word {
   view-transition-name: zfb-footer;
 }
 
-[data-zfb-transition-persist="desktop-sidebar-toggle"] {
+.zd-desktop-sidebar-toggle {
   view-transition-name: zfb-sidebar-toggle;
 }
 
-[data-zfb-transition-persist="desktop-toc-toggle"] {
+.zd-desktop-toc-toggle {
   view-transition-name: zfb-toc-toggle;
 }
 
-::view-transition-old(zfb-header), ::view-transition-new(zfb-header), ::view-transition-group(zfb-header), ::view-transition-old(zfb-sidebar), ::view-transition-new(zfb-sidebar), ::view-transition-group(zfb-sidebar), ::view-transition-old(zfb-footer), ::view-transition-new(zfb-footer), ::view-transition-group(zfb-footer), ::view-transition-old(zfb-sidebar-toggle), ::view-transition-new(zfb-sidebar-toggle), ::view-transition-group(zfb-sidebar-toggle), ::view-transition-old(zfb-toc-toggle), ::view-transition-new(zfb-toc-toggle), ::view-transition-group(zfb-toc-toggle) {
+::view-transition-old(zfb-header), ::view-transition-new(zfb-header), ::view-transition-group(zfb-header), ::view-transition-group(zfb-sidebar), ::view-transition-old(zfb-footer), ::view-transition-new(zfb-footer), ::view-transition-group(zfb-footer), ::view-transition-old(zfb-sidebar-toggle), ::view-transition-new(zfb-sidebar-toggle), ::view-transition-group(zfb-sidebar-toggle), ::view-transition-old(zfb-toc-toggle), ::view-transition-new(zfb-toc-toggle), ::view-transition-group(zfb-toc-toggle) {
   animation: none;
 }
 
-::view-transition-old(zfb-header):only-child, ::view-transition-old(zfb-sidebar):only-child, ::view-transition-old(zfb-footer):only-child, ::view-transition-old(zfb-sidebar-toggle):only-child, ::view-transition-old(zfb-toc-toggle):only-child {
+::view-transition-group(zfb-header) {
+  z-index: var(--z-index-toolbar, 20);
+}
+
+::view-transition-old(zfb-sidebar), ::view-transition-old(zfb-footer):only-child, ::view-transition-old(zfb-sidebar-toggle):only-child, ::view-transition-old(zfb-toc-toggle):only-child {
   animation: var(--default-transition-duration) ease-in both contentFadeOut;
 }
 
-::view-transition-new(zfb-header):only-child, ::view-transition-new(zfb-sidebar):only-child, ::view-transition-new(zfb-footer):only-child, ::view-transition-new(zfb-sidebar-toggle):only-child, ::view-transition-new(zfb-toc-toggle):only-child {
+::view-transition-new(zfb-sidebar), ::view-transition-new(zfb-footer):only-child, ::view-transition-new(zfb-sidebar-toggle):only-child, ::view-transition-new(zfb-toc-toggle):only-child {
   animation: var(--zd-transition-slower) ease-out both contentFadeIn;
 }
 
+:root[data-zd-sidebar-transition="stationary"]::view-transition-old(zfb-sidebar), :root[data-zd-sidebar-transition="stationary"]::view-transition-new(zfb-sidebar) {
+  animation: none;
+}
+
 ::view-transition-old(root) {
   animation: var(--default-transition-duration) ease-in both contentFadeOut;
 }
@@ -1444,7 +1467,7 @@ pre.hi-root .line .highlighted-word {
 }
 
 @media (prefers-reduced-motion: reduce) {
-  ::view-transition-old(root), ::view-transition-new(root), ::view-transition-group(root), ::view-transition-old(zfb-header):only-child, ::view-transition-old(zfb-sidebar):only-child, ::view-transition-old(zfb-footer):only-child, ::view-transition-old(zfb-sidebar-toggle):only-child, ::view-transition-old(zfb-toc-toggle):only-child, ::view-transition-new(zfb-header):only-child, ::view-transition-new(zfb-sidebar):only-child, ::view-transition-new(zfb-footer):only-child, ::view-transition-new(zfb-sidebar-toggle):only-child, ::view-transition-new(zfb-toc-toggle):only-child {
+  ::view-transition-old(root), ::view-transition-new(root), ::view-transition-group(root), ::view-transition-old(zfb-sidebar), ::view-transition-old(zfb-footer):only-child, ::view-transition-old(zfb-sidebar-toggle):only-child, ::view-transition-old(zfb-toc-toggle):only-child, ::view-transition-new(zfb-sidebar), ::view-transition-new(zfb-footer):only-child, ::view-transition-new(zfb-sidebar-toggle):only-child, ::view-transition-new(zfb-toc-toggle):only-child {
     animation: none;
   }
 }

package/dist/content.css

@@ -52,6 +52,9 @@
   color: var(--color-fg);
   font-size: var(--text-body);
   line-height: var(--leading-relaxed);
+  /* Let ordinary prose and navigation labels reflow at narrow widths (#4585).
+   * Preformatted code keeps its white-space contract and local scrolling. */
+  overflow-wrap: anywhere;
 }
 
 /* ── Flow spacing (vertical rhythm) ── */
@@ -233,6 +236,12 @@
   overflow-wrap: break-word;
 }
 
+/* `anywhere` collapses min-content width, so table layout would shrink columns
+ * and split identifiers mid-word instead of scrolling the wrapper (#4594). */
+.zd-content :where(th code, td code) {
+  overflow-wrap: break-word;
+}
+
 .zd-content :where(th) {
   font-weight: var(--font-weight-semibold);
   text-align: left;

package/dist/doclayout/doc-layout.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { ClientRouter } from "@takazudo/zfb-runtime";
+import { buildChromeTransitionBootstrap } from "../transitions/chrome-transition-bootstrap.js";
 const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
 function DocLayout(props) {
   const {
@@ -70,6 +71,7 @@ function DocLayout(props) {
     );
   }
   if (head !== void 0) headChildren.push(head);
+  if (enableClientRouter !== false) headChildren.push(/* @__PURE__ */ jsx("script", { rawHtml: buildChromeTransitionBootstrap() }));
   return /* @__PURE__ */ jsxs("html", { ...htmlAttrs, children: [
     /* @__PURE__ */ jsx("head", { children: headChildren }),
     /* @__PURE__ */ jsxs("body", { class: "min-h-screen antialiased", children: [

package/dist/features.css

@@ -283,7 +283,7 @@ pre.hi-root .line .highlighted-word {
 }
 
 /* Make KaTeX respect our color scheme */
-.katex .base {
+.katex .katex-base {
   color: var(--zd-fg);
 }
 
@@ -457,56 +457,22 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
   }
 }
 
-/* Root cross-fade for same-document View Transitions (Strategy B).
- *
- * @view-transition { navigation: auto; } (Strategy A, cross-document) is
- * deleted — Strategy B uses <ClientRouter /> which drives same-document
- * transitions via document.startViewTransition on each navigation.
- *
- * Chrome extraction via view-transition-name (Strategy B+, zudolab/zudo-doc#1558):
- * <header>, <aside id="desktop-sidebar">, <footer>, the desktop-sidebar-toggle
- * button, and (since #3254) the desktop-toc-toggle button each carry a
- * data-zfb-transition-persist attribute whose value is keyed by locale and
- * nav-section. The five attribute selectors below assign a stable
- * view-transition-name based on the attribute value prefix, extracting those
- * elements from the root snapshot into their own named layers:
- *   - header-{lang}          → zfb-header
- *   - sidebar-{locale}-…     → zfb-sidebar
- *   - footer-{lang}          → zfb-footer
- *   - desktop-sidebar-toggle → zfb-sidebar-toggle
- *   - desktop-toc-toggle     → zfb-toc-toggle
- *
- * Once extracted, the root cross-fade animates only non-chrome content (main,
- * article, TOC, etc.). The ::view-transition-{old,new,group}(<name>) rules
- * disable animation for all five chrome layers. The group pseudo must be
- * neutralised too — even when old/new are static the group container can still
- * produce a geometry-morph animation when snapshot size/position differs.
- *
- * Entry/exit cross-fade (zudolab/zudo-doc#2072): animation: none is only
- * correct when the chrome element exists on BOTH pages of a navigation.
- * When it exists on one side only (docs page with sidebar → top page
- * without), the named group holds a single snapshot — frozen at full
- * opacity for the whole transition, then dropped abruptly at finish. The
- * :only-child rules below detect that one-sided case and cross-fade the
- * lone snapshot in sync with the root content fade (spec-standard
- * entry/exit pattern; :only-child outranks the animation: none rules via
- * the extra pseudo-class specificity). */
-
-/* Chrome extraction — assign view-transition-name from data-zfb-transition-persist */
-[data-zfb-transition-persist^="header-"]               { view-transition-name: zfb-header; }
-[data-zfb-transition-persist^="sidebar-"]              { view-transition-name: zfb-sidebar; }
+/* Visual region identity is independent of persistence/remount policy. The
+ * layout's header slot is a direct body header, including consumer overrides.
+ * A sidebar keeps its name even when incoming island props require replacement.
+ * Never name an ancestor of these regions: it would move their whole layer.
+ */
+body > header                                        { view-transition-name: zfb-header; }
+#desktop-sidebar:not(.sr-only)                       { view-transition-name: zfb-sidebar; }
 [data-zfb-transition-persist^="footer-"]               { view-transition-name: zfb-footer; }
-[data-zfb-transition-persist="desktop-sidebar-toggle"] { view-transition-name: zfb-sidebar-toggle; }
-[data-zfb-transition-persist="desktop-toc-toggle"]     { view-transition-name: zfb-toc-toggle; }
+.zd-desktop-sidebar-toggle                          { view-transition-name: zfb-sidebar-toggle; }
+.zd-desktop-toc-toggle                              { view-transition-name: zfb-toc-toggle; }
 
-/* Disable animation for all four chrome layers (old, new, and group), plus
- * the desktop-toc-toggle button (#3254 — mirrors desktop-sidebar-toggle so
- * it doesn't animate on SPA swaps). */
+/* Header snapshots and every chrome group stay at their authored geometry.
+ * Footer and toggle pairs keep their established stationary policy. */
 ::view-transition-old(zfb-header),
 ::view-transition-new(zfb-header),
 ::view-transition-group(zfb-header),
-::view-transition-old(zfb-sidebar),
-::view-transition-new(zfb-sidebar),
 ::view-transition-group(zfb-sidebar),
 ::view-transition-old(zfb-footer),
 ::view-transition-new(zfb-footer),
@@ -518,24 +484,35 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
 ::view-transition-new(zfb-toc-toggle),
 ::view-transition-group(zfb-toc-toggle) { animation: none; }
 
-/* Entry/exit: chrome element present on one side only (#2072).
- * Exit — lone old snapshot fades out with the content cross-fade. */
-::view-transition-old(zfb-header):only-child,
-::view-transition-old(zfb-sidebar):only-child,
+/* A translating incoming sidebar/root must not paint over the header's lower
+ * edge. Named snapshot groups have their own stacking order above the live DOM. */
+::view-transition-group(zfb-header) { z-index: var(--z-index-toolbar, 20); }
+
+/* A category/context change or a one-sided sidebar uses the content animation.
+ * The header remains stationary even when replaced or present on only one side.
+ * Other chrome retains its established entry/exit behavior. */
+::view-transition-old(zfb-sidebar),
 ::view-transition-old(zfb-footer):only-child,
 ::view-transition-old(zfb-sidebar-toggle):only-child,
 ::view-transition-old(zfb-toc-toggle):only-child {
   animation: var(--default-transition-duration) ease-in both contentFadeOut;
 }
 /* Entry — lone new snapshot fades in with the content cross-fade. */
-::view-transition-new(zfb-header):only-child,
-::view-transition-new(zfb-sidebar):only-child,
+::view-transition-new(zfb-sidebar),
 ::view-transition-new(zfb-footer):only-child,
 ::view-transition-new(zfb-sidebar-toggle):only-child,
 ::view-transition-new(zfb-toc-toggle):only-child {
   animation: var(--zd-transition-slower) ease-out both contentFadeIn;
 }
 
+/* Resolved navSection AND the existing navigation context must agree. The
+ * context already isolates locale, version and custom-tree topology; article,
+ * focused subtree and DOM identity are deliberately irrelevant here. */
+:root[data-zd-sidebar-transition="stationary"]::view-transition-old(zfb-sidebar),
+:root[data-zd-sidebar-transition="stationary"]::view-transition-new(zfb-sidebar) {
+  animation: none;
+}
+
 /* Root cross-fade rules — animate only the non-chrome snapshot */
 ::view-transition-old(root) {
   animation: var(--default-transition-duration) ease-in both contentFadeOut;
@@ -559,13 +536,11 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
   ::view-transition-old(root),
   ::view-transition-new(root),
   ::view-transition-group(root),
-  ::view-transition-old(zfb-header):only-child,
-  ::view-transition-old(zfb-sidebar):only-child,
+  ::view-transition-old(zfb-sidebar),
   ::view-transition-old(zfb-footer):only-child,
   ::view-transition-old(zfb-sidebar-toggle):only-child,
   ::view-transition-old(zfb-toc-toggle):only-child,
-  ::view-transition-new(zfb-header):only-child,
-  ::view-transition-new(zfb-sidebar):only-child,
+  ::view-transition-new(zfb-sidebar),
   ::view-transition-new(zfb-footer):only-child,
   ::view-transition-new(zfb-sidebar-toggle):only-child,
   ::view-transition-new(zfb-toc-toggle):only-child {

package/dist/page-loading/page-loading-overlay.d.ts

@@ -15,13 +15,13 @@ export interface PageLoadingOverlayProps {
  */
 export declare function buildPageLoadingOverlayBootstrap(overlayId: string): string;
 /**
- * Full-page loading overlay shown during view-transition navigations.
+ * Content loading overlay shown while a dynamic navigation is pending.
  *
  * Mount this once per layout (typically inside `DocLayoutWithDefaults`'s
  * `bodyEnd` slot, alongside the existing body-end providers). It is
  * server-rendered and self-wires its visibility — no hydration needed.
  *
- * CSS lives in the host project's `src/styles/global.css` (`.page-loading-overlay`,
+ * CSS ships in `@takazudo/zudo-doc/page-loading.css` (`.page-loading-overlay`,
  * `.page-loading-spinner`, `[data-zd-nav-pending]` rules) rather than in an
  * inline `<style>` block here — a `<style>` inside `<body>` violates HTML5
  * element-permitted-content and fails html-validate (same fix applied to the

package/dist/page-loading/page-loading-overlay.js

@@ -1,7 +1,8 @@
 import { Fragment, jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import {
   AFTER_NAVIGATE_EVENT,
-  BEFORE_NAVIGATE_EVENT
+  BEFORE_NAVIGATE_EVENT,
+  NAVIGATION_ABORTED_EVENT
 } from "../transitions/page-events.js";
 const PAGE_LOADING_OVERLAY_ID = "page-loading-overlay";
 function buildPageLoadingOverlayBootstrap(overlayId) {
@@ -10,7 +11,7 @@ function buildPageLoadingOverlayBootstrap(overlayId) {
   const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
   return `(function(){
 var id=${id};
-function show(){var el=document.getElementById(id);if(!el)return;el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
+function show(){var el=document.getElementById(id);if(!el)return;var content=document.querySelector(".zd-sidebar-content-wrapper");var header=document.querySelector("body > header");el.style.left=Math.max(0,content?content.getBoundingClientRect().left:0)+"px";el.style.top=Math.max(0,header?header.getBoundingClientRect().bottom:0)+"px";el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
 function hide(){var el=document.getElementById(id);if(!el)return;el.removeAttribute("data-visible");el.setAttribute("aria-hidden","true");}
 function setPending(ev){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});var src=ev&&ev.sourceElement;if(src&&src instanceof Element)src.setAttribute("data-zd-nav-pending","");}
 function clearPending(){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});}
@@ -18,6 +19,7 @@ document.addEventListener(${before},show);
 document.addEventListener(${after},hide);
 document.addEventListener(${before},setPending);
 document.addEventListener(${after},clearPending);
+document.addEventListener(${JSON.stringify(NAVIGATION_ABORTED_EVENT)},function(){hide();clearPending();});
 })();`;
 }
 function PageLoadingOverlay({

package/dist/page-loading.css

@@ -31,8 +31,9 @@
 
 .page-loading-overlay {
   position: fixed;
+  view-transition-name: zfb-loading;
   inset: 0;
-  /* Full-screen blocking load overlay — modal tier.
+  /* Pending-content overlay — the bootstrap excludes the layout's chrome.
      --z-index-modal fallback (100) ensures the overlay stacks on top even for
      bare consumers that have not defined the token. */
   z-index: var(--z-index-modal, 100);
@@ -45,11 +46,13 @@
   );
   opacity: 0;
   pointer-events: none;
-  transition: opacity 150ms ease-out;
+  /* Hidden loading feedback must disappear synchronously. */
+  transition: none;
 }
 
 .page-loading-overlay[data-visible] {
   opacity: 1;
+  transition: opacity 150ms ease-out;
 }
 
 a[data-zd-nav-pending],
@@ -90,3 +93,11 @@ button[data-zd-nav-pending] {
     border-bottom-color: var(--color-page-loading-spinner, #fff);
   }
 }
+
+/* Pending feedback belongs to the fetch, not the page cross-fade. Extract it
+ * from the root snapshot, then suppress its snapshot layer. This also avoids
+ * an unscoped after-preparation event from an older fetch hiding newer feedback.
+ */
+::view-transition-group(zfb-loading) { animation: none; }
+::view-transition-old(zfb-loading),
+::view-transition-new(zfb-loading) { display: none; }

package/dist/plugins/optional-peers.d.ts

@@ -0,0 +1,3 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/optional-peers.js

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+function shadowSource(specifier) {
+  const message = `Optional peer "${specifier}" is shadowed: it is not installed or the zudo-doc feature that uses it is off.`;
+  return `throw new Error(${JSON.stringify(message)});
+export {};
+`;
+}
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function isResolvable(specifier) {
+  try {
+    createRequire(import.meta.url).resolve(specifier);
+    return true;
+  } catch {
+    return false;
+  }
+}
+const plugin = {
+  name: "optional-peers",
+  setup(ctx) {
+    const shadow = [
+      ...stringList(ctx.options["shadow"]),
+      ...stringList(ctx.options["shadowIfMissing"]).filter((s) => !isResolvable(s))
+    ];
+    for (const specifier of shadow) {
+      ctx.addVirtualModule(specifier, () => shadowSource(specifier));
+    }
+  }
+};
+var optional_peers_default = plugin;
+export {
+  optional_peers_default as default
+};

package/dist/preset.d.ts

@@ -115,6 +115,8 @@ export interface PresetSettings {
     trailingSlash: boolean;
     minifyHtml?: boolean;
     mermaid: boolean;
+    /** KaTeX math rendering; when off, the optional `katex` peer is shadowed. */
+    math?: boolean;
     /** Enable transclusion of other Markdown/MDX files. */
     transclude?: boolean;
     onBrokenMarkdownLinks: "warn" | "error" | "ignore";

package/dist/preset.js

@@ -130,6 +130,16 @@ function buildMarkdownFeatures(settings, directiveVocabulary) {
     headingIds: { strategy: "hierarchical" }
   };
 }
+function optionalPeerShadows(settings) {
+  const peers = [
+    ["katex", Boolean(settings.math)],
+    ["diff", Boolean(settings.docHistory)]
+  ];
+  return {
+    shadow: peers.filter(([, on]) => !on).map(([name]) => name),
+    shadowIfMissing: peers.filter(([, on]) => on).map(([name]) => name)
+  };
+}
 function buildPlugins(settings, routeContext) {
   const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({
     code,
@@ -337,7 +347,10 @@ function buildPlugins(settings, routeContext) {
     // `design-token-panel-bootstrap` (#4261). Preset-level rather than inside
     // the routes plugin because the bootstrap is reachable from chrome even
     // when packageOwnedRoutes is off.
-    ...resolvesBundleZdtp(settings) ? [] : [{ name: "@takazudo/zudo-doc/plugins/zdtp-loader", options: {} }]
+    ...resolvesBundleZdtp(settings) ? [] : [{ name: "@takazudo/zudo-doc/plugins/zdtp-loader", options: {} }],
+    // Absent or disabled katex/diff → throwing shadows, so they cannot fail a
+    // Rolldown build (Takazudo/zudo-front-builder#4429).
+    { name: "@takazudo/zudo-doc/plugins/optional-peers", options: optionalPeerShadows(settings) }
   ];
 }
 export {

package/dist/transitions/chrome-transition-bootstrap.d.ts

@@ -0,0 +1,2 @@
+/** Visual snapshot policy only; persistence and sidebar state keep their owners. */
+export declare function buildChromeTransitionBootstrap(): string;

package/dist/transitions/chrome-transition-bootstrap.js

@@ -0,0 +1,23 @@
+import { BEFORE_SWAP_EVENT } from "./page-events.js";
+function buildChromeTransitionBootstrap() {
+  return `(function(){
+if(document.__zdChromeTransitionPolicy)return;
+document.__zdChromeTransitionPolicy=true;
+function identity(doc){
+var sidebar=doc.getElementById("desktop-sidebar");
+var context=sidebar&&sidebar.querySelector("[data-sidebar-context]");
+var band=doc.querySelector("[data-zd-nav-section]");
+return {section:band&&band.getAttribute("data-zd-nav-section"),context:band&&!band.hasAttribute("data-zd-nosidebar")&&context&&context.getAttribute("data-sidebar-context")};
+}
+document.addEventListener(${JSON.stringify(BEFORE_SWAP_EVENT)},function(ev){
+var incoming=ev.newDocument;
+if(!incoming||incoming.nodeType!==9)return;
+var from=identity(document),to=identity(incoming);
+var stationary=!!from.section&&!!from.context&&from.section===to.section&&from.context===to.context;
+incoming.documentElement.setAttribute("data-zd-sidebar-transition",stationary?"stationary":"changing");
+});
+})();`;
+}
+export {
+  buildChromeTransitionBootstrap
+};

package/dist/transitions/page-events.d.ts

@@ -7,6 +7,10 @@
  * the v2 vocabulary.
  */
 export declare const BEFORE_NAVIGATE_EVENT = "zfb:before-preparation";
+/** Fetch/preparation finished, before the native old snapshot is captured. */
+export declare const AFTER_PREPARATION_EVENT = "zfb:after-preparation";
+/** A navigation was abandoned before committing the destination DOM. */
+export declare const NAVIGATION_ABORTED_EVENT = "zfb:navigation-aborted";
 /**
  * Event name fired after a SPA body swap. Today resolves to
  * `"zfb:after-swap"`. The initial page load uses `zfb:page-load` instead;

package/dist/transitions/page-events.js

@@ -1,4 +1,6 @@
 const BEFORE_NAVIGATE_EVENT = "zfb:before-preparation";
+const AFTER_PREPARATION_EVENT = "zfb:after-preparation";
+const NAVIGATION_ABORTED_EVENT = "zfb:navigation-aborted";
 const AFTER_NAVIGATE_EVENT = "zfb:after-swap";
 const BEFORE_SWAP_EVENT = "zfb:before-swap";
 function onBeforeNavigate(handler) {
@@ -15,8 +17,10 @@ function onAfterNavigate(handler) {
 }
 export {
   AFTER_NAVIGATE_EVENT,
+  AFTER_PREPARATION_EVENT,
   BEFORE_NAVIGATE_EVENT,
   BEFORE_SWAP_EVENT,
+  NAVIGATION_ABORTED_EVENT,
   onAfterNavigate,
   onBeforeNavigate
 };

package/eject/page-loading/page-loading-overlay.tsx

@@ -1,5 +1,5 @@
 /** @jsxRuntime automatic */
-// Server-rendered, zero-hydration full-page loading overlay.
+// Server-rendered, zero-hydration content loading overlay.
 //
 // Renders the overlay and its bootstrap into the document:
 //
@@ -15,12 +15,13 @@
 //      `zfb:after-swap` (AFTER_NAVIGATE_EVENT); see
 //      `transitions/page-events.ts` for rationale.
 //
-// Its CSS stays in the host's global stylesheet, and the component is not
+// Its package CSS is imported by the host, and the component is not
 // hydrated: the static script owns its navigation listeners.
 
 import {
   AFTER_NAVIGATE_EVENT,
   BEFORE_NAVIGATE_EVENT,
+  NAVIGATION_ABORTED_EVENT,
 } from "../transitions/page-events.js";
 
 /** Default `id` for the overlay element. Stable so test rigs can target it. */
@@ -52,7 +53,7 @@ export function buildPageLoadingOverlayBootstrap(overlayId: string): string {
   const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
   return `(function(){
 var id=${id};
-function show(){var el=document.getElementById(id);if(!el)return;el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
+function show(){var el=document.getElementById(id);if(!el)return;var content=document.querySelector(".zd-sidebar-content-wrapper");var header=document.querySelector("body > header");el.style.left=Math.max(0,content?content.getBoundingClientRect().left:0)+"px";el.style.top=Math.max(0,header?header.getBoundingClientRect().bottom:0)+"px";el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
 function hide(){var el=document.getElementById(id);if(!el)return;el.removeAttribute("data-visible");el.setAttribute("aria-hidden","true");}
 function setPending(ev){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});var src=ev&&ev.sourceElement;if(src&&src instanceof Element)src.setAttribute("data-zd-nav-pending","");}
 function clearPending(){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});}
@@ -60,17 +61,18 @@ document.addEventListener(${before},show);
 document.addEventListener(${after},hide);
 document.addEventListener(${before},setPending);
 document.addEventListener(${after},clearPending);
+document.addEventListener(${JSON.stringify(NAVIGATION_ABORTED_EVENT)},function(){hide();clearPending();});
 })();`;
 }
 
 /**
- * Full-page loading overlay shown during view-transition navigations.
+ * Content loading overlay shown while a dynamic navigation is pending.
  *
  * Mount this once per layout (typically inside `DocLayoutWithDefaults`'s
  * `bodyEnd` slot, alongside the existing body-end providers). It is
  * server-rendered and self-wires its visibility — no hydration needed.
  *
- * CSS lives in the host project's `src/styles/global.css` (`.page-loading-overlay`,
+ * CSS ships in `@takazudo/zudo-doc/page-loading.css` (`.page-loading-overlay`,
  * `.page-loading-spinner`, `[data-zd-nav-pending]` rules) rather than in an
  * inline `<style>` block here — a `<style>` inside `<body>` violates HTML5
  * element-permitted-content and fails html-validate (same fix applied to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "6.2.0",
+  "version": "7.1.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -14,6 +14,9 @@
   "bugs": {
     "url": "https://github.com/zudolab/zudo-doc/issues"
   },
+  "engines": {
+    "node": ">=24 <25"
+  },
   "keywords": [
     "zudo-doc",
     "documentation",
@@ -203,6 +206,10 @@
       "types": "./dist/plugins/zdtp-loader.d.ts",
       "default": "./dist/plugins/zdtp-loader.js"
     },
+    "./plugins/optional-peers": {
+      "types": "./dist/plugins/optional-peers.d.ts",
+      "default": "./dist/plugins/optional-peers.js"
+    },
     "./content-admonition": {
       "types": "./dist/content-admonition/index.d.ts",
       "default": "./dist/content-admonition/index.js"
@@ -733,12 +740,12 @@
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
     "@takazudo/zdtp": "^0.5.2 || ^0.6.0 || ^0.7.0 || ^0.8.0",
-    "@takazudo/zfb": "^4.5.0",
-    "@takazudo/zfb-md-wasm": "^4.5.0",
-    "@takazudo/zfb-runtime": "^4.5.0",
-    "@takazudo/zudo-doc-history-server": "^6.0.0",
+    "@takazudo/zfb": "^4.7.0",
+    "@takazudo/zfb-md-wasm": "^4.7.0",
+    "@takazudo/zfb-runtime": "^4.7.0",
+    "@takazudo/zudo-doc-history-server": "^7.0.0",
     "diff": "^8.0.0",
-    "katex": "^0.16.0",
+    "katex": "^0.18.2 || ^0.19.0",
     "zod": "^4.3.6"
   },
   "peerDependenciesMeta": {
@@ -776,9 +783,9 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
     "@takazudo/mdx-formatter": "1.3.0",
-    "@takazudo/zfb": "4.5.0",
-    "@takazudo/zfb-md-wasm": "4.5.0",
-    "@takazudo/zfb-runtime": "4.5.0",
+    "@takazudo/zfb": "4.7.0",
+    "@takazudo/zfb-md-wasm": "4.7.0",
+    "@takazudo/zfb-runtime": "4.7.0",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
@@ -788,7 +795,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "6.2.0"
+    "@takazudo/zudo-doc-history-server": "7.1.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",