@takazudo/zudo-doc 5.5.1 → 5.5.2

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.5.2] - 2026-08-16
+
+### Bug Fixes
+
+- Preserve the sidebar scroll position across SPA navigation and island remounts. (7e8130f4b, 63629e73e, 7fadc3308)
+- Suppress GFM task-list markers in rendered documentation. (4d9dbf941)
+
+### Other Changes
+
+- Added regression coverage for stale sidebar snapshots and sidebar timing. (5632de06f, 360857d79)
+
 ## [5.5.1] - 2026-08-15
 
 ### Bug Fixes

package/dist/content.css

@@ -164,6 +164,19 @@
   color: var(--color-muted);
 }
 
+/* GFM task-list inputs are emitted as disabled direct children of a tight
+ * item, or as children of the item's paragraph in a loose list. The
+ * component-rendered ancestor `ul` carries an inline disc marker, so reset
+ * only those generated task rows on the `li` itself. Keep the direct-child
+ * shape and disabled constraint narrow so authored/nested checkboxes remain
+ * ordinary list content. */
+.zd-content :where(
+  li:has(> input[type="checkbox"][disabled]),
+  li:has(> p > input[type="checkbox"][disabled])
+) {
+  list-style-type: none;
+}
+
 .zd-content :where(li > ul, li > ol) {
   margin-top: var(--spacing-vsp-xs);
   margin-bottom: 0;

package/dist/sidebar-tree-island/index.js

@@ -9,6 +9,8 @@ import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
+import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
+ensureSidebarScrollPreserve();
 function ToggleChevron({ isExpanded, className }) {
   return /* @__PURE__ */ jsx(
     ChevronRight,
@@ -58,35 +60,6 @@ function useActiveSlug(nodes, initial) {
   }, [nodes]);
   return slug;
 }
-function useSidebarScrollPreserve() {
-  useEffect(() => {
-    let savedScrollTop = 0;
-    let restoreTimer;
-    const onBefore = () => {
-      if (restoreTimer !== void 0) {
-        clearTimeout(restoreTimer);
-        restoreTimer = void 0;
-      }
-      const aside = document.querySelector("#desktop-sidebar");
-      if (aside) savedScrollTop = aside.scrollTop;
-    };
-    const onAfter = () => {
-      const aside = document.querySelector("#desktop-sidebar");
-      if (!aside) return;
-      restoreTimer = setTimeout(() => {
-        restoreTimer = void 0;
-        aside.scrollTop = savedScrollTop;
-      }, 50);
-    };
-    document.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
-    document.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-    return () => {
-      document.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
-      document.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-      if (restoreTimer !== void 0) clearTimeout(restoreTimer);
-    };
-  }, []);
-}
 function RootMenuItemEntry({ item }) {
   const [expanded, setExpanded] = useState(false);
   const hasChildren = item.children && item.children.length > 0;
@@ -141,7 +114,6 @@ function SidebarFooter({ links, themeDefaultMode }) {
 }
 function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }) {
   const activeSlug = useActiveSlug(nodes, currentSlug);
-  useSidebarScrollPreserve();
   const [query, setQuery] = useState("");
   const [showingRootMenu, setShowingRootMenu] = useState(false);
   const filterRef = useRef(null);

package/dist/sidebar-tree-island/sidebar-scroll-preserve.d.ts

@@ -0,0 +1,21 @@
+interface SidebarScrollPreserveOptions {
+    document: Document;
+    requestAnimationFrame: (callback: FrameRequestCallback) => number;
+    cancelAnimationFrame: (handle: number) => void;
+}
+/**
+ * Install the scroll-preservation state machine on a document.
+ *
+ * This low-level entrypoint owns an explicit cleanup for focused tests and
+ * non-singleton hosts. The sidebar's browser module uses the durable,
+ * duplicate-safe `ensureSidebarScrollPreserve` wrapper below instead.
+ */
+export declare function installSidebarScrollPreserve({ document, requestAnimationFrame, cancelAnimationFrame, }: SidebarScrollPreserveOptions): () => void;
+/**
+ * Install exactly one module-lifetime controller for a browser document.
+ * Repeated calls from component renders or duplicate boot paths are no-ops.
+ */
+export declare function ensureSidebarScrollPreserve(options?: SidebarScrollPreserveOptions): void;
+/** Test/HMR teardown for a controller installed through the singleton wrapper. */
+export declare function disposeSidebarScrollPreserve(document: Document): void;
+export {};

package/dist/sidebar-tree-island/sidebar-scroll-preserve.js

@@ -0,0 +1,63 @@
+import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
+const installedControllers = /* @__PURE__ */ new WeakMap();
+function installSidebarScrollPreserve({
+  document: document2,
+  requestAnimationFrame,
+  cancelAnimationFrame
+}) {
+  let snapshot;
+  let restoreFrame;
+  const cancelPendingRestore = () => {
+    if (restoreFrame === void 0) return;
+    cancelAnimationFrame(restoreFrame);
+    restoreFrame = void 0;
+  };
+  const onBefore = () => {
+    cancelPendingRestore();
+    const element = document2.querySelector("#desktop-sidebar");
+    snapshot = element ? { element, scrollTop: element.scrollTop } : void 0;
+  };
+  const onAfter = () => {
+    if (!snapshot) return;
+    const saved = snapshot;
+    snapshot = void 0;
+    restoreFrame = requestAnimationFrame(() => {
+      restoreFrame = void 0;
+      const current = document2.querySelector("#desktop-sidebar");
+      if (current === saved.element) current.scrollTop = saved.scrollTop;
+    });
+  };
+  document2.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+  document2.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+  return () => {
+    document2.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+    document2.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+    cancelPendingRestore();
+    snapshot = void 0;
+  };
+}
+function ensureSidebarScrollPreserve(options) {
+  const resolved = options ?? resolveBrowserOptions();
+  if (!resolved || installedControllers.has(resolved.document)) return;
+  installedControllers.set(
+    resolved.document,
+    installSidebarScrollPreserve(resolved)
+  );
+}
+function resolveBrowserOptions() {
+  if (typeof document === "undefined" || typeof window === "undefined") return void 0;
+  return {
+    document,
+    requestAnimationFrame: window.requestAnimationFrame.bind(window),
+    cancelAnimationFrame: window.cancelAnimationFrame.bind(window)
+  };
+}
+function disposeSidebarScrollPreserve(document2) {
+  installedControllers.get(document2)?.();
+  installedControllers.delete(document2);
+}
+export {
+  disposeSidebarScrollPreserve,
+  ensureSidebarScrollPreserve,
+  installSidebarScrollPreserve
+};

package/eject/sidebar-tree-island/index.tsx

@@ -18,6 +18,13 @@ import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
+import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
+
+// The persisted aside can transiently tear down and re-mount its SidebarTree
+// effect during a body swap. Keep navigation snapshot ownership at browser
+// module/document lifetime so that island lifecycle cannot discard it between
+// before-preparation and after-swap. SSR evaluation is a safe no-op.
+ensureSidebarScrollPreserve();
 
 function ToggleChevron({ isExpanded, className }: { isExpanded: boolean; className?: string }) {
   return (
@@ -90,42 +97,6 @@ function useActiveSlug(nodes: SidebarNavNode[], initial?: string): string | unde
   return slug;
 }
 
-/**
- * Preserve `#desktop-sidebar` scrollTop across SPA navigations.
- */
-function useSidebarScrollPreserve() {
-  useEffect(() => {
-    let savedScrollTop = 0;
-    let restoreTimer: ReturnType<typeof setTimeout> | undefined;
-
-    const onBefore = () => {
-      if (restoreTimer !== undefined) {
-        clearTimeout(restoreTimer);
-        restoreTimer = undefined;
-      }
-      const aside = document.querySelector<HTMLElement>("#desktop-sidebar");
-      if (aside) savedScrollTop = aside.scrollTop;
-    };
-
-    const onAfter = () => {
-      const aside = document.querySelector<HTMLElement>("#desktop-sidebar");
-      if (!aside) return;
-      restoreTimer = setTimeout(() => {
-        restoreTimer = undefined;
-        aside.scrollTop = savedScrollTop;
-      }, 50);
-    };
-
-    document.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
-    document.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-    return () => {
-      document.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
-      document.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-      if (restoreTimer !== undefined) clearTimeout(restoreTimer);
-    };
-  }, []);
-}
-
 function RootMenuItemEntry({ item }: { item: SidebarRootMenuItem }) {
   const [expanded, setExpanded] = useState(false);
   const hasChildren = item.children && item.children.length > 0;
@@ -202,7 +173,6 @@ function SidebarFooter({ links, themeDefaultMode }: { links?: SidebarLocaleLink[
 
 export function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps) {
   const activeSlug = useActiveSlug(nodes, currentSlug);
-  useSidebarScrollPreserve();
   const [query, setQuery] = useState("");
   const [showingRootMenu, setShowingRootMenu] = useState(false);
   const filterRef = useRef<HTMLInputElement>(null);

package/eject/sidebar-tree-island/sidebar-scroll-preserve.ts

@@ -0,0 +1,88 @@
+import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
+
+interface SidebarScrollPreserveOptions {
+  document: Document;
+  requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  cancelAnimationFrame: (handle: number) => void;
+}
+
+const installedControllers = new WeakMap<Document, () => void>();
+
+/**
+ * Install the scroll-preservation state machine on a document.
+ *
+ * This low-level entrypoint owns an explicit cleanup for focused tests and
+ * non-singleton hosts. The sidebar's browser module uses the durable,
+ * duplicate-safe `ensureSidebarScrollPreserve` wrapper below instead.
+ */
+export function installSidebarScrollPreserve({
+  document,
+  requestAnimationFrame,
+  cancelAnimationFrame,
+}: SidebarScrollPreserveOptions): () => void {
+  let snapshot: { element: HTMLElement; scrollTop: number } | undefined;
+  let restoreFrame: number | undefined;
+
+  const cancelPendingRestore = () => {
+    if (restoreFrame === undefined) return;
+    cancelAnimationFrame(restoreFrame);
+    restoreFrame = undefined;
+  };
+
+  const onBefore = () => {
+    cancelPendingRestore();
+    const element = document.querySelector<HTMLElement>("#desktop-sidebar");
+    snapshot = element ? { element, scrollTop: element.scrollTop } : undefined;
+  };
+
+  const onAfter = () => {
+    if (!snapshot) return;
+    const saved = snapshot;
+    snapshot = undefined;
+    restoreFrame = requestAnimationFrame(() => {
+      restoreFrame = undefined;
+      const current = document.querySelector<HTMLElement>("#desktop-sidebar");
+      if (current === saved.element) current.scrollTop = saved.scrollTop;
+    });
+  };
+
+  document.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+  document.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+
+  return () => {
+    document.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+    document.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+    cancelPendingRestore();
+    snapshot = undefined;
+  };
+}
+
+/**
+ * Install exactly one module-lifetime controller for a browser document.
+ * Repeated calls from component renders or duplicate boot paths are no-ops.
+ */
+export function ensureSidebarScrollPreserve(
+  options?: SidebarScrollPreserveOptions,
+): void {
+  const resolved = options ?? resolveBrowserOptions();
+  if (!resolved || installedControllers.has(resolved.document)) return;
+  installedControllers.set(
+    resolved.document,
+    installSidebarScrollPreserve(resolved),
+  );
+}
+
+function resolveBrowserOptions(): SidebarScrollPreserveOptions | undefined {
+  if (typeof document === "undefined" || typeof window === "undefined") return undefined;
+  return {
+    document,
+    requestAnimationFrame: window.requestAnimationFrame.bind(window),
+    cancelAnimationFrame: window.cancelAnimationFrame.bind(window),
+  };
+}
+
+/** Test/HMR teardown for a controller installed through the singleton wrapper. */
+export function disposeSidebarScrollPreserve(document: Document): void {
+  installedControllers.get(document)?.();
+  installedControllers.delete(document);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.5.1",
+  "version": "5.5.2",
   "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",
@@ -663,7 +663,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.5.1"
+    "@takazudo/zudo-doc-history-server": "5.5.2"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",