@takazudo/zudo-doc 6.1.1 → 7.0.0

package/CHANGELOG.md

@@ -8,6 +8,39 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [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
+
+- Adds optional `SidebarDefinition.scopeRoot?: "configured" | "editorial"` (default `"editorial"`, unchanged behavior). `"configured"` caps Broaden, branch focus, Restore, and route reconciliation at the authored forest: empty `items` stop at the category-filtered tree, one `autogenerated` directory stops at that directory, and an explicit list stops at that list. `initialPath` remains the starting view and the Restore baseline. At the cap the scope toolbar is omitted. An unsupported value fails the build. An omitted entry or an array stays editorial. (418b2f29c)
+
+### Bug Fixes
+
+- The shared `tsconfig.base.json` no longer sets `baseUrl`, which TypeScript 7 rejects with TS5102 in every project that extends it. Projects that relied on the inherited `baseUrl` for bare `paths` targets should write them as explicitly relative paths (for example `"@/*": ["./src/*"]`), which TypeScript 5.9 and 7 both resolve against the declaring tsconfig. (4d5e801ed)
+- `buildSidebarForSection` now applies `initialPath` and `initialPathMode` to an object sidebar definition with empty `items`, matching `buildSidebarNavigation`. Previously the empty-items case returned the plain category-filtered tree and ignored those options. (31fe01015)
+- Updates the lazy browser Mermaid URL from 11.15.0 to the exact 11.17.2 release, including the advisory fixes introduced in 11.16.1. Local npm audit does not cover the separately delivered CDN graph. (76d637663)
+- The desktop sidebar and the mobile drawer each keep their scroll offset across client navigation, a full document load, reload, and Back/Forward, including after Broaden. Restoration runs after the destination tree can hold the offset, so a replaced sidebar or a temporary empty tree does not snap back to the top. A saved zero is restored. A missing snapshot is not written as zero. A closed drawer keeps its saved offset in history until it opens again. Article scroll, focus, filtering, and disclosure are left unchanged. (418b2f29c, 2b38ccf0a)
+- The Appearance menu is a compact list of three rows (Light, Dark, System). The visible heading and the bottom helper are removed. The System row shows the device's current Light/Dark mode inline, and that status stays truthful while a manual Light or Dark preference is selected. The full localized helper remains the System option's accessible description. The popup is sized from its natural height at its final width, so its border no longer creates a spurious inner scrollbar. It opens above the trigger near the bottom edge and repositions when its content size changes. Opening, arrow keys, and focus return no longer scroll the page, and Tab / Shift+Tab leave the menu instead of cycling its rows. (37e3b8b42, 7aba63e28)
+
+### Other Changes
+
+- Requires zfb 4.5.0: the `@takazudo/zfb`, `zfb-runtime` and `zfb-md-wasm` peer floors move from `^4.3.3` to `^4.5.0`. zfb 4.4.0 updates its YAML frontmatter parser and fixes fragment Back/Forward navigation. zfb 4.5.0 also restores a previously rendered same-path query entry on Back/Forward, fixes sibling radio-group state on form reset, and adds opt-in CSS compiler and `ErrorBoundary` APIs. Upgrade the zfb family (and `zfb-adapter-cloudflare` when used) to 4.5.0 together with this release. (48a224468, 4f9d0c26f)
+- Updates the Codex resource TOML parser to smol-toml `^1.9.1`, preserving configuration dates and agent metadata while including its bounded key-scanning fix. (05e3fb5e7)
+
 ## [6.1.1] - 2026-10-12
 
 ### Other Changes

package/README.md

@@ -108,8 +108,8 @@ If your project renders **semi-trusted or user-submitted** HTML in a preview, ov
 ## 6.0 migration and peers
 
 **6.0.0** is the coordinated major release of `@takazudo/zudo-doc`,
-`@takazudo/zudo-doc-history-server` and `create-zudo-doc`. It targets the
-published **zfb 4.3.3** family (peer floor **^4.3.3**).
+`@takazudo/zudo-doc-history-server` and `create-zudo-doc`. The current workspace
+targets the published **zfb 4.5.2** family (peer floor **^4.5.2**).
 [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/code-syntax/mermaid-init-script.d.ts

@@ -3,7 +3,7 @@
  * resolves npm package specifiers to publishable ESM modules.
  *
  * Pinned to a specific minor.patch (not the bare `@11` major) so the
- * runtime version is byte-stable across deploys; floating on the major
+ * top-level package version is stable across deploys; floating on the major
  * would silently pull in upstream theme-API or behaviour changes. Bump
  * policy: there is no `mermaid` package.json dependency to keep in sync
  * with — this constant is the sole source of truth for the mermaid
@@ -15,7 +15,7 @@
  * tests can override the URL — e.g. self-hosted mirrors, version-
  * locked deployments — without re-templating the whole script.
  */
-export declare const MERMAID_CDN_MODULE_URL = "https://esm.sh/mermaid@11.15.0";
+export declare const MERMAID_CDN_MODULE_URL = "https://esm.sh/mermaid@11.17.2";
 /**
  * Build the inline init script with a caller-supplied module URL.
  *

package/dist/code-syntax/mermaid-init-script.js

@@ -1,5 +1,5 @@
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
-const MERMAID_CDN_MODULE_URL = "https://esm.sh/mermaid@11.15.0";
+const MERMAID_CDN_MODULE_URL = "https://esm.sh/mermaid@11.17.2";
 function buildMermaidInitScript(cdnUrl) {
   const safeUrlLiteral = JSON.stringify(cdnUrl).replace(
     /<\/(script)/gi,

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 {
@@ -1045,6 +1046,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 +1055,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 +1103,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 +1305,7 @@ pre.hi-root .line .highlighted-word {
   white-space: nowrap;
 }
 
-.katex .base {
+.katex .katex-base {
   color: var(--zd-fg);
 }
 
@@ -1403,11 +1414,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 +1426,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 +1463,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;
   }
 }
@@ -2375,6 +2394,9 @@ site-search [data-search-results] > :is([data-search-placeholder], p) {
 .w-\[1\.125rem\] {
   width: 1.125rem;
 }
+.w-\[1\.25rem\] {
+  width: 1.25rem;
+}
 .w-\[1\.575rem\] {
   width: 1.575rem;
 }
@@ -3428,6 +3450,11 @@ site-search [data-search-results] > :is([data-search-placeholder], p) {
     background-color: color-mix(in oklab, var(--zw-color-accent) 10%, transparent);
   }
 }
+@media (hover: hover) {
+  .hover\:bg-accent\/5:hover {
+    background-color: color-mix(in oklab, var(--zw-color-accent) 5%, transparent);
+  }
+}
 @media (hover: hover) {
   .hover\:bg-bg\/10:hover {
     background-color: color-mix(in oklab, var(--zw-color-bg) 10%, transparent);

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) ── */

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/sidebar-toggle-island/index.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { computed, getScope, signal } from "@takazudo/zfb/zudo-react";
 import { AFTER_NAVIGATE_EVENT, ensureNestedIslandPropsRefresh } from "../transitions/index.js";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
+import { notifySidebarScrollReady } from "../sidebar-tree-island/sidebar-scroll-preserve.js";
 ensureNestedIslandPropsRefresh();
 const cx = (...classes) => classes.filter(Boolean).join(" ");
 const HIDDEN_ICON_STYLE = "display:none";
@@ -29,6 +30,10 @@ function SidebarToggle({
     document.body.style.overflow = isOpen ? "hidden" : "";
     if (isOpen) closeIconRef.current?.style.removeProperty("display");
     else closeIconRef.current?.style.setProperty("display", "none");
+    if (isOpen) {
+      const scroller = document.querySelector("aside[data-zd-mobile-sidebar] .flex-1.overflow-y-auto");
+      if (scroller) notifySidebarScrollReady(scroller);
+    }
     if (isOpen) menuIconRef.current?.style.setProperty("display", "none");
     else menuIconRef.current?.style.removeProperty("display");
     return () => {