@takazudo/zudo-doc 6.0.2 → 6.1.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [6.1.0] - 2026-10-12
+
+### Features
+
+- Adds `SidebarDefinition.initialPathMode?: "children" | "node"` (default `"children"`, unchanged behavior). With `"node"`, the node selected by `initialPath` is itself the fresh/Restore baseline: a page-backed section keeps its linked overview row together with its pages, while the complete editorial tree stays available, so Broaden moves to its real parent with no duplicate or invented row. Applies equally to `buildSidebarForSection` and `buildSidebarNavigation`, and to the desktop sidebar and mobile drawer. An unknown mode fails the build. (6fc2200a4)
+
+### Bug Fixes
+
+- The sidebar now saves only the reader's explicit expand/collapse choices in `sessionStorage`. Automatically opening the current page's path on soft navigation, Back/Forward or at narrow viewports is no longer persisted, so later hard loads no longer show unrelated branches expanded. The reader can collapse the branch containing the current page; it stays collapsed for that page (hash changes, filtering and same-page reload included) and the next page reveals its own path. Restore clears the selected scope and saved choices, keeps the filter text, and updates the desktop sidebar and mobile drawer together. Expansion saved by earlier versions is discarded once on first load; a saved scope and filter text are kept. (98d1d223b, 1bbaa5f26, fbd694422)
+
 ## [6.0.2] - 2026-10-12
 
 ### Other Changes

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

@@ -555,7 +555,7 @@ function TrayGroupNode({
     () => group.value.items.some((item) => item.slug === currentSlug.value)
   );
   const occurrenceKey = computed(() => `${trayOccurrence.value}#${group.value.key}`);
-  const open = signal(scopeControls?.expansion.value[occurrenceKey.value] ?? (scopeControls?.defaultGroupOpen(group.value.items) ?? containsCurrent.value));
+  const open = signal(scopeControls ? scopeControls.isOpen(occurrenceKey.value, scopeControls.defaultGroupOpen(group.value.items)) : containsCurrent.value);
   const storageKey = computed(
     () => noteTrayGroupStorageKey(traySlug.value, group.value.key)
   );
@@ -566,7 +566,7 @@ function TrayGroupNode({
     if (!scopeControls && getOpenSet().has(storageKey.value)) open.value = true;
   });
   scope.effect(() => {
-    if (containsCurrent.value) open.value = true;
+    if (!scopeControls && containsCurrent.value) open.value = true;
   });
   scope.effect(() => {
     if (!scopeControls && open.value) {
@@ -578,20 +578,18 @@ function TrayGroupNode({
     }
   });
   const toggle = () => {
-    open.value = !open.value;
     if (scopeControls) {
-      scopeControls.expansion.value = { ...scopeControls.expansion.value, [occurrenceKey.value]: open.value };
-      scopeControls.save();
+      scopeControls.setOpen(occurrenceKey.value, !open.value);
       return;
     }
+    open.value = !open.value;
     const stored = getOpenSet();
     if (open.value) stored.add(storageKey.value);
     else stored.delete(storageKey.value);
     saveOpenSet(stored);
   };
   scope.effect(() => {
-    const stored = scopeControls?.expansion.value[occurrenceKey.value];
-    if (scopeControls) open.value = stored ?? scopeControls.defaultGroupOpen(group.value.items);
+    if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey.value, scopeControls.defaultGroupOpen(group.value.items));
   });
   const expanded = computed(() => forceOpen.value || open.value);
   const items = computed(() => group.value.items);
@@ -711,15 +709,13 @@ function CategoryNode({
   );
   const active = computed(() => node.value.slug === currentSlug.value);
   const occurrenceKey = () => node.value.occurrenceId ?? node.value.slug;
-  const open = signal(scopeControls?.expansion.value[occurrenceKey()] ?? (scopeControls?.defaultOpen(node.value) ?? (containsCurrent.value || !node.value.collapsed)));
+  const open = signal(scopeControls ? scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value)) : containsCurrent.value || !node.value.collapsed);
   scope.onActivate(() => {
     if (!scopeControls && getOpenSet().has(node.value.slug)) open.value = true;
   });
   scope.effect(() => {
     const slug = currentSlug.value;
-    const revision = scopeControls?.reveal.value;
-    if (slug !== void 0 && subtreeContainsSlug(node.value, slug)) open.value = true;
-    void revision;
+    if (!scopeControls && slug !== void 0 && subtreeContainsSlug(node.value, slug)) open.value = true;
   });
   scope.effect(() => {
     if (!scopeControls && open.value) {
@@ -731,20 +727,18 @@ function CategoryNode({
     }
   });
   const toggle = () => {
-    open.value = !open.value;
     if (scopeControls) {
-      scopeControls.expansion.value = { ...scopeControls.expansion.value, [occurrenceKey()]: open.value };
-      scopeControls.save();
+      scopeControls.setOpen(occurrenceKey(), !open.value);
       return;
     }
+    open.value = !open.value;
     const stored = getOpenSet();
     if (open.value) stored.add(node.value.slug);
     else stored.delete(node.value.slug);
     saveOpenSet(stored);
   };
   scope.effect(() => {
-    const stored = scopeControls?.expansion.value[occurrenceKey()];
-    if (scopeControls) open.value = stored ?? scopeControls.defaultOpen(node.value);
+    if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value));
   });
   const expanded = computed(() => forceOpen.value || open.value);
   const focusButton = scopeControls ? /* @__PURE__ */ jsx(

package/dist/sidebar-tree-island/scope-state.d.ts

@@ -3,16 +3,19 @@ import type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.
 export interface ScopeControls {
     focus: (node: SidebarNavNode) => void;
     focusLabel: string;
-    expansion: {
-        value: Record<string, boolean>;
-    };
-    reveal: ReadonlySignal<number>;
-    save: () => void;
+    /** Effective disclosure: the user's explicit choice, else revealed/scope root, else `baseline`. */
+    isOpen: (key: string, baseline: boolean) => boolean;
+    /** Records an explicit user disclosure choice. */
+    setOpen: (key: string, open: boolean) => void;
     defaultOpen: (node: SidebarNavNode) => boolean;
     defaultGroupOpen: (items: SidebarNavNode[]) => boolean;
 }
 /** One controller shared by the real desktop tree and mobile drawer. SSR always
- * starts with configured roots; session state is applied only on activation. */
+ * starts with configured roots; session state is applied only on activation.
+ * `expansion` holds explicit user choices only. The active path and the
+ * visible scope's sole root are derived, other scope-change reveal stays in
+ * memory, and a reveal removes conflicting explicit collapses instead of
+ * writing automatic entries. */
 export declare function useSidebarScope({ nodes, navigation, activeSlug, query, locale }: {
     nodes: SidebarNavNode[];
     navigation?: SidebarNavigationContext;
@@ -32,7 +35,7 @@ export declare function useSidebarScope({ nodes, navigation, activeSlug, query,
     };
     canRestore: ReadonlySignal<boolean>;
     changeScope: (id: string | null) => void;
-    save: () => void;
+    save: (broadcast?: boolean) => void;
     navRef: Ref<HTMLElement>;
     scopeControls: ScopeControls | undefined;
 };

package/dist/sidebar-tree-island/scope-state.js

@@ -2,10 +2,12 @@ import { computed, getScope, signal } from "@takazudo/zfb/zudo-react";
 import { broaderSidebarScope, sidebarScopeNodes, reconcileSidebarScope, indexSidebarOccurrences, sidebarInitialExpansion, sidebarBaselineOpen, SIDEBAR_FOREST_SCOPE } from "../sidebar-utils/index.js";
 import { getNoteTrayItems, groupItems } from "../note-tray-model/index.js";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+const STATE_VERSION = 2;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
   const selected = signal(null);
   const expansion = signal({});
-  const reveal = signal(0);
+  const revealed = signal(/* @__PURE__ */ new Set());
   let lastPage = activeSlug.value;
   const navRef = { current: null };
   const stateKey = "zd-sidebar-scope";
@@ -30,47 +32,59 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
   const groupKeys = new Set(trayGroups.map((group) => group.key));
   const defaultOpen = (node) => sidebarBaselineOpen(node, navigation ? sidebarInitialExpansion(navigation, activeSlug.value) : void 0, activeSlug.value);
   const defaultGroupOpen = (items) => items.some((item) => item.slug === activeSlug.value) || !!navigation && sidebarInitialExpansion(navigation, activeSlug.value) === "expanded";
+  const baselineOf = (key) => {
+    const node = occurrenceIndex.get(key);
+    if (node) return node.children.length ? defaultOpen(node) : void 0;
+    const group = trayGroups.find((candidate) => candidate.key === key);
+    return group ? defaultGroupOpen(group.items) : void 0;
+  };
+  const scopeRoot = computed(() => selectedNodes.value.length === 1 ? selectedNodes.value[0].occurrenceId : void 0);
+  const automaticOpen = (key, baseline) => revealed.value.has(key) || key === scopeRoot.value || baseline;
   const canRestore = computed(() => {
     if (JSON.stringify(selectedNodes.value) !== JSON.stringify(nodes)) return true;
-    for (const [id, node] of occurrenceIndex) {
-      if (node.children.length && (expansion.value[id] ?? defaultOpen(node)) !== defaultOpen(node)) return true;
-    }
-    return trayGroups.some((group) => (expansion.value[group.key] ?? defaultGroupOpen(group.items)) !== defaultGroupOpen(group.items));
+    const differs = Object.entries(expansion.value).some(([key, open]) => {
+      const baseline = baselineOf(key);
+      return baseline !== void 0 && open !== automaticOpen(key, baseline);
+    });
+    return differs || [...revealed.value].some((key) => expansion.value[key] === void 0 && baselineOf(key) === false);
   });
-  const revealPath = (id) => {
-    if (!navigation) return;
+  const canonicalScope = (id) => id !== null && navigation && (nodes.length === 1 && nodes[0].occurrenceId === id || JSON.stringify(sidebarScopeNodes(navigation, nodes, id)) === JSON.stringify(nodes)) ? null : id;
+  const withAncestors = (id) => {
+    const chain = [];
+    for (let ancestor = id; ancestor && ancestor !== SIDEBAR_FOREST_SCOPE; ancestor = navigation?.parents[ancestor] ?? null) chain.push(ancestor);
+    return chain;
+  };
+  const withoutCollapses = (keys) => {
     const next = { ...expansion.value };
-    for (const [key, node] of occurrenceIndex) {
-      if (node.slug !== activeSlug.value && key !== id) continue;
-      let ancestor = key;
-      while (ancestor) {
-        next[ancestor] = true;
-        ancestor = navigation.parents[ancestor];
-      }
-    }
-    for (const group of trayGroups) {
-      if (group.items.some((item) => item.slug === activeSlug.value)) next[group.key] = true;
-    }
+    for (const key of keys) if (next[key] === false) delete next[key];
     expansion.value = next;
-    reveal.value++;
   };
-  const save = () => {
+  const arrive = () => {
+    revealed.value = /* @__PURE__ */ new Set();
+    withoutCollapses([
+      ...[...occurrenceIndex].filter(([, node]) => node.slug === activeSlug.value).flatMap(([key]) => withAncestors(key)),
+      ...trayGroups.filter((group) => group.items.some((item) => item.slug === activeSlug.value)).map((group) => group.key),
+      ...scopeRoot.value ? [scopeRoot.value] : []
+    ]);
+  };
+  const save = (broadcast = true) => {
     if (!navigation) return;
+    const state = { version: STATE_VERSION, context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value };
     try {
-      sessionStorage.setItem(stateKey, JSON.stringify({ context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value }));
+      sessionStorage.setItem(stateKey, JSON.stringify(state));
     } catch {
     }
-    document.dispatchEvent(new CustomEvent(syncEvent, { detail: { context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value } }));
+    if (broadcast) document.dispatchEvent(new CustomEvent(syncEvent, { detail: { ...state, revealed: [...revealed.value] } }));
   };
   const changeScope = (id) => {
     const previous = selected.value;
-    selected.value = navigation && JSON.stringify(sidebarScopeNodes(navigation, nodes, id)) === JSON.stringify(nodes) ? null : id;
+    selected.value = canonicalScope(id);
     if (id === null) {
       expansion.value = {};
-      revealPath();
+      revealed.value = /* @__PURE__ */ new Set();
     } else {
-      revealPath(previous);
-      revealPath(id);
+      withoutCollapses(withAncestors(id));
+      revealed.value = /* @__PURE__ */ new Set([...revealed.value, ...withAncestors(previous), ...withAncestors(id)]);
     }
     save();
     queueMicrotask(() => {
@@ -101,40 +115,47 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
       if (node.occurrenceId) changeScope(node.occurrenceId);
     },
     focusLabel: labels.focus,
-    expansion,
-    reveal,
     defaultOpen,
     defaultGroupOpen,
-    save
+    isOpen: (key, baseline) => expansion.value[key] ?? automaticOpen(key, baseline),
+    setOpen: (key, open) => {
+      expansion.value = { ...expansion.value, [key]: open };
+      save();
+    }
   } : void 0;
   getScope().onActivate(() => {
     if (!navigation) return;
     lastPage = activeSlug.value;
+    let samePage = false;
     try {
       const stored = JSON.parse(sessionStorage.getItem(stateKey) ?? "null");
-      if (stored?.context === navigation.id) {
+      if (isRecord(stored) && stored.context === navigation.id) {
         const candidate = typeof stored.selected === "string" ? stored.selected : null;
         const valid = candidate === SIDEBAR_FOREST_SCOPE || candidate !== null && occurrenceIndex.has(candidate) ? candidate : null;
-        selected.value = stored.page === activeSlug.value ? valid : reconcileSidebarScope(navigation, nodes, valid, activeSlug.value);
+        samePage = stored.page === activeSlug.value;
+        selected.value = canonicalScope(samePage ? valid : reconcileSidebarScope(navigation, nodes, valid, activeSlug.value));
         query.value = typeof stored.query === "string" ? stored.query : "";
-        if (stored.expansion && typeof stored.expansion === "object") expansion.value = Object.fromEntries(Object.entries(stored.expansion).filter(([id, value]) => (occurrenceIndex.has(id) || groupKeys.has(id)) && typeof value === "boolean"));
-        if (stored.page !== activeSlug.value) revealPath(selected.value);
+        if (stored.version === STATE_VERSION && isRecord(stored.expansion)) {
+          expansion.value = Object.fromEntries(Object.entries(stored.expansion).filter(([id, value]) => (occurrenceIndex.has(id) || groupKeys.has(id)) && typeof value === "boolean"));
+        }
       }
     } catch {
     }
-    save();
+    if (!samePage) arrive();
+    save(false);
     const sync = (event) => {
       const state = event.detail;
       if (state?.context !== navigation.id || state.page !== activeSlug.value) return;
       selected.value = state.selected;
       query.value = state.query;
       expansion.value = state.expansion;
+      revealed.value = new Set(state.revealed);
     };
     const navigate = () => {
       if (lastPage === activeSlug.value) return;
       lastPage = activeSlug.value;
-      selected.value = reconcileSidebarScope(navigation, nodes, selected.value, activeSlug.value);
-      revealPath(selected.value);
+      selected.value = canonicalScope(reconcileSidebarScope(navigation, nodes, selected.value, activeSlug.value));
+      arrive();
       save();
     };
     document.addEventListener(syncEvent, sync);

package/dist/sidebar-utils/index.d.ts

@@ -30,6 +30,12 @@ export interface SidebarDefinition {
     items: SidebarItem[];
     /** Resolved occurrence indexes from the forest to a category (not URL segments). */
     initialPath?: number[];
+    /**
+     * What `initialPath` selects as the fresh/Restore baseline: the target's
+     * `"children"`, or the target `"node"` itself (its row, link and children).
+     * @default "children"
+     */
+    initialPathMode?: "children" | "node";
     /** Share across sections using the same editorial tree. Locale/version are added by chrome. */
     contextId?: string;
 }

package/dist/sidebar-utils/index.js

@@ -82,12 +82,19 @@ function buildSidebarForSection(docs, lang, categoryMatch, categoryMeta, sidebar
     return filterByCategory(tree, categoryMatch, explicitCategoryPrefixes);
   }
   if (Array.isArray(config)) return resolveItems(config, tree, lang);
-  let nodes = resolveItems(config.items, tree, lang);
-  for (const index of config.initialPath ?? []) {
-    if (!Number.isInteger(index) || index < 0 || !nodes[index]) throw new Error(`Invalid sidebar initialPath for ${sectionKey}`);
-    nodes = nodes[index].children;
+  return followInitialPath(resolveItems(config.items, tree, lang), config, sectionKey).nodes;
+}
+function followInitialPath(forest, definition, sectionKey) {
+  const mode = definition?.initialPathMode;
+  if (mode !== void 0 && mode !== "children" && mode !== "node") throw new Error(`Invalid sidebar initialPathMode for ${sectionKey}`);
+  let nodes = forest;
+  let target;
+  for (const index of definition?.initialPath ?? []) {
+    target = nodes[index];
+    if (!Number.isInteger(index) || index < 0 || !target) throw new Error(`Invalid sidebar initialPath for ${sectionKey}`);
+    nodes = target.children;
   }
-  return nodes;
+  return { nodes: target && definition?.initialPathMode === "node" ? [target] : nodes, target };
 }
 function buildSidebarNavigation(...args) {
   const [docs, lang, categoryMatch, meta, sidebars, buildTree, prefixes] = args;
@@ -158,13 +165,9 @@ function buildSidebarNavigation(...args) {
     roots = result.canonical;
     nodes = result.visible;
   }
-  let localParentId;
-  for (const index of definition?.initialPath ?? []) {
-    const node = nodes[index];
-    if (!Number.isInteger(index) || index < 0 || !node) throw new Error(`Invalid sidebar initialPath for ${categoryMatch ?? "default"}`);
-    localParentId = node.occurrenceId;
-    nodes = node.children;
-  }
+  const { nodes: local, target } = followInitialPath(nodes, definition, categoryMatch ?? "default");
+  nodes = local;
+  const localParentId = definition?.initialPathMode === "node" && target?.occurrenceId ? parents[target.occurrenceId] ?? void 0 : target?.occurrenceId;
   let hash = 2166136261;
   const serialized = JSON.stringify(Object.keys(initialExpansion).length ? [roots, initialExpansion] : roots);
   for (let i = 0; i < serialized.length; i++) hash = Math.imul(hash ^ serialized.charCodeAt(i), 16777619);

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

@@ -659,7 +659,7 @@ function TrayGroupNode({
     group.value.items.some((item) => item.slug === currentSlug.value),
   );
   const occurrenceKey = computed(() => `${trayOccurrence.value}#${group.value.key}`);
-  const open = signal(scopeControls?.expansion.value[occurrenceKey.value] ?? (scopeControls?.defaultGroupOpen(group.value.items) ?? containsCurrent.value));
+  const open = signal(scopeControls ? scopeControls.isOpen(occurrenceKey.value, scopeControls.defaultGroupOpen(group.value.items)) : containsCurrent.value);
   const storageKey = computed(() =>
     noteTrayGroupStorageKey(traySlug.value, group.value.key),
   );
@@ -672,7 +672,7 @@ function TrayGroupNode({
     if (!scopeControls && getOpenSet().has(storageKey.value)) open.value = true;
   });
   scope.effect(() => {
-    if (containsCurrent.value) open.value = true;
+    if (!scopeControls && containsCurrent.value) open.value = true;
   });
   scope.effect(() => {
     if (!scopeControls && open.value) {
@@ -684,20 +684,18 @@ function TrayGroupNode({
     }
   });
   const toggle = () => {
-    open.value = !open.value;
     if (scopeControls) {
-      scopeControls.expansion.value = { ...scopeControls.expansion.value, [occurrenceKey.value]: open.value };
-      scopeControls.save();
+      scopeControls.setOpen(occurrenceKey.value, !open.value);
       return;
     }
+    open.value = !open.value;
     const stored = getOpenSet();
     if (open.value) stored.add(storageKey.value);
     else stored.delete(storageKey.value);
     saveOpenSet(stored);
   };
   scope.effect(() => {
-    const stored = scopeControls?.expansion.value[occurrenceKey.value];
-    if (scopeControls) open.value = stored ?? scopeControls.defaultGroupOpen(group.value.items);
+    if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey.value, scopeControls.defaultGroupOpen(group.value.items));
   });
   const expanded = computed(() => forceOpen.value || open.value);
   const items = computed(() => group.value.items);
@@ -827,15 +825,13 @@ function CategoryNode({
   );
   const active = computed(() => node.value.slug === currentSlug.value);
   const occurrenceKey = () => node.value.occurrenceId ?? node.value.slug;
-  const open = signal(scopeControls?.expansion.value[occurrenceKey()] ?? (scopeControls?.defaultOpen(node.value) ?? (containsCurrent.value || !node.value.collapsed)));
+  const open = signal(scopeControls ? scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value)) : containsCurrent.value || !node.value.collapsed);
   scope.onActivate(() => {
     if (!scopeControls && getOpenSet().has(node.value.slug)) open.value = true;
   });
   scope.effect(() => {
     const slug = currentSlug.value;
-    const revision = scopeControls?.reveal.value;
-    if (slug !== undefined && subtreeContainsSlug(node.value, slug)) open.value = true;
-    void revision;
+    if (!scopeControls && slug !== undefined && subtreeContainsSlug(node.value, slug)) open.value = true;
   });
   scope.effect(() => {
     if (!scopeControls && open.value) {
@@ -847,20 +843,18 @@ function CategoryNode({
     }
   });
   const toggle = () => {
-    open.value = !open.value;
     if (scopeControls) {
-      scopeControls.expansion.value = { ...scopeControls.expansion.value, [occurrenceKey()]: open.value };
-      scopeControls.save();
+      scopeControls.setOpen(occurrenceKey(), !open.value);
       return;
     }
+    open.value = !open.value;
     const stored = getOpenSet();
     if (open.value) stored.add(node.value.slug);
     else stored.delete(node.value.slug);
     saveOpenSet(stored);
   };
   scope.effect(() => {
-    const stored = scopeControls?.expansion.value[occurrenceKey()];
-    if (scopeControls) open.value = stored ?? scopeControls.defaultOpen(node.value);
+    if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value));
   });
   const expanded = computed(() => forceOpen.value || open.value);
   const focusButton = scopeControls ? (

package/eject/sidebar-tree-island/scope-state.ts

@@ -7,15 +7,27 @@ import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 export interface ScopeControls {
   focus: (node: SidebarNavNode) => void;
   focusLabel: string;
-  expansion: { value: Record<string, boolean> };
-  reveal: ReadonlySignal<number>;
-  save: () => void;
+  /** Effective disclosure: the user's explicit choice, else revealed/scope root, else `baseline`. */
+  isOpen: (key: string, baseline: boolean) => boolean;
+  /** Records an explicit user disclosure choice. */
+  setOpen: (key: string, open: boolean) => void;
   defaultOpen: (node: SidebarNavNode) => boolean;
   defaultGroupOpen: (items: SidebarNavNode[]) => boolean;
 }
 
+// Version 1 records (no `version`) mixed automatic reveal into `expansion`
+// without provenance, so their expansion is discarded once on read.
+const STATE_VERSION = 2;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
 /** One controller shared by the real desktop tree and mobile drawer. SSR always
- * starts with configured roots; session state is applied only on activation. */
+ * starts with configured roots; session state is applied only on activation.
+ * `expansion` holds explicit user choices only. The active path and the
+ * visible scope's sole root are derived, other scope-change reveal stays in
+ * memory, and a reveal removes conflicting explicit collapses instead of
+ * writing automatic entries. */
 export function useSidebarScope({ nodes, navigation, activeSlug, query, locale }: {
   nodes: SidebarNavNode[];
   navigation?: SidebarNavigationContext;
@@ -25,7 +37,7 @@ export function useSidebarScope({ nodes, navigation, activeSlug, query, locale }
 }) {
   const selected = signal<string | null>(null);
   const expansion = signal<Record<string, boolean>>({});
-  const reveal = signal(0);
+  const revealed = signal<ReadonlySet<string>>(new Set());
   let lastPage = activeSlug.value;
   const navRef: Ref<HTMLElement> = { current: null };
   const stateKey = "zd-sidebar-scope";
@@ -47,42 +59,63 @@ export function useSidebarScope({ nodes, navigation, activeSlug, query, locale }
   const groupKeys = new Set(trayGroups.map((group) => group.key));
   const defaultOpen = (node: SidebarNavNode) => sidebarBaselineOpen(node, navigation ? sidebarInitialExpansion(navigation, activeSlug.value) : undefined, activeSlug.value);
   const defaultGroupOpen = (items: SidebarNavNode[]) => items.some((item) => item.slug === activeSlug.value) || (!!navigation && sidebarInitialExpansion(navigation, activeSlug.value) === "expanded");
+  const baselineOf = (key: string) => {
+    const node = occurrenceIndex.get(key);
+    if (node) return node.children.length ? defaultOpen(node) : undefined;
+    const group = trayGroups.find((candidate) => candidate.key === key);
+    return group ? defaultGroupOpen(group.items) : undefined;
+  };
+  const scopeRoot = computed(() => selectedNodes.value.length === 1 ? selectedNodes.value[0]!.occurrenceId : undefined);
+  const automaticOpen = (key: string, baseline: boolean) => revealed.value.has(key) || key === scopeRoot.value || baseline;
   const canRestore = computed(() => {
     if (JSON.stringify(selectedNodes.value) !== JSON.stringify(nodes)) return true;
-    for (const [id, node] of occurrenceIndex) {
-      if (node.children.length && (expansion.value[id] ?? defaultOpen(node)) !== defaultOpen(node)) return true;
-    }
-    return trayGroups.some((group) => (expansion.value[group.key] ?? defaultGroupOpen(group.items)) !== defaultGroupOpen(group.items));
+    const differs = Object.entries(expansion.value).some(([key, open]) => {
+      const baseline = baselineOf(key);
+      return baseline !== undefined && open !== automaticOpen(key, baseline);
+    });
+    return differs || [...revealed.value].some((key) => expansion.value[key] === undefined && baselineOf(key) === false);
   });
-  const revealPath = (id?: string | null) => {
-    if (!navigation) return;
+  // A stored or chosen scope whose view equals the destination baseline is the baseline.
+  const canonicalScope = (id: string | null) =>
+    id !== null && navigation && ((nodes.length === 1 && nodes[0]!.occurrenceId === id)
+      || JSON.stringify(sidebarScopeNodes(navigation, nodes, id)) === JSON.stringify(nodes)) ? null : id;
+  const withAncestors = (id: string | null) => {
+    const chain: string[] = [];
+    for (let ancestor = id; ancestor && ancestor !== SIDEBAR_FOREST_SCOPE; ancestor = navigation?.parents[ancestor] ?? null) chain.push(ancestor);
+    return chain;
+  };
+  const withoutCollapses = (keys: Iterable<string>) => {
     const next = { ...expansion.value };
-    for (const [key, node] of occurrenceIndex) {
-      if (node.slug !== activeSlug.value && key !== id) continue;
-      let ancestor: string | null | undefined = key;
-      while (ancestor) { next[ancestor] = true; ancestor = navigation.parents[ancestor]; }
-    }
-    for (const group of trayGroups) {
-      if (group.items.some((item) => item.slug === activeSlug.value)) next[group.key] = true;
-    }
+    for (const key of keys) if (next[key] === false) delete next[key];
     expansion.value = next;
-    reveal.value++;
   };
-  const save = () => {
+  // Destination arrival reveals the active path and scope root by dropping
+  // explicit collapses there. Deterministic, so every controller converges.
+  const arrive = () => {
+    revealed.value = new Set();
+    withoutCollapses([
+      ...[...occurrenceIndex].filter(([, node]) => node.slug === activeSlug.value).flatMap(([key]) => withAncestors(key)),
+      ...trayGroups.filter((group) => group.items.some((item) => item.slug === activeSlug.value)).map((group) => group.key),
+      ...(scopeRoot.value ? [scopeRoot.value] : []),
+    ]);
+  };
+  const save = (broadcast = true) => {
     if (!navigation) return;
-    try { sessionStorage.setItem(stateKey, JSON.stringify({ context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value })); } catch { /* Optional persistence. */ }
-    document.dispatchEvent(new CustomEvent(syncEvent, { detail: { context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value } }));
+    const state = { version: STATE_VERSION, context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value };
+    try { sessionStorage.setItem(stateKey, JSON.stringify(state)); } catch { /* Optional persistence. */ }
+    if (broadcast) document.dispatchEvent(new CustomEvent(syncEvent, { detail: { ...state, revealed: [...revealed.value] } }));
   };
   const changeScope = (id: string | null) => {
     const previous = selected.value;
-    selected.value = navigation && JSON.stringify(sidebarScopeNodes(navigation, nodes, id)) === JSON.stringify(nodes) ? null : id;
+    selected.value = canonicalScope(id);
     if (id === null) {
-      // Restore the authored collapse defaults, then reveal the active path.
+      // Restore the configured baseline; the active path is open by default.
       expansion.value = {};
-      revealPath();
+      revealed.value = new Set();
     } else {
-      revealPath(previous);
-      revealPath(id);
+      // Focus opens its target; the scope being left keeps explicit choices.
+      withoutCollapses(withAncestors(id));
+      revealed.value = new Set([...revealed.value, ...withAncestors(previous), ...withAncestors(id)]);
     }
     save();
     // Scroll only the sidebar's own viewport; never scrollIntoView, which also
@@ -112,38 +145,48 @@ export function useSidebarScope({ nodes, navigation, activeSlug, query, locale }
   };
   const scopeControls: ScopeControls | undefined = navigation ? {
     focus: (node) => { if (node.occurrenceId) changeScope(node.occurrenceId); },
-    focusLabel: labels.focus, expansion, reveal, defaultOpen, defaultGroupOpen,
-    save,
+    focusLabel: labels.focus, defaultOpen, defaultGroupOpen,
+    isOpen: (key, baseline) => expansion.value[key] ?? automaticOpen(key, baseline),
+    setOpen: (key, open) => {
+      expansion.value = { ...expansion.value, [key]: open };
+      save();
+    },
   } : undefined;
   getScope().onActivate(() => {
     if (!navigation) return;
     lastPage = activeSlug.value;
+    let samePage = false;
     try {
-      const stored = JSON.parse(sessionStorage.getItem(stateKey) ?? "null");
-      if (stored?.context === navigation.id) {
+      const stored: unknown = JSON.parse(sessionStorage.getItem(stateKey) ?? "null");
+      if (isRecord(stored) && stored.context === navigation.id) {
         const candidate = typeof stored.selected === "string" ? stored.selected : null;
         const valid = candidate === SIDEBAR_FOREST_SCOPE || (candidate !== null && occurrenceIndex.has(candidate)) ? candidate : null;
-        selected.value = stored.page === activeSlug.value
-          ? valid
-          : reconcileSidebarScope(navigation, nodes, valid, activeSlug.value);
+        samePage = stored.page === activeSlug.value;
+        selected.value = canonicalScope(samePage ? valid : reconcileSidebarScope(navigation, nodes, valid, activeSlug.value));
         query.value = typeof stored.query === "string" ? stored.query : "";
-        if (stored.expansion && typeof stored.expansion === "object") expansion.value = Object.fromEntries(Object.entries(stored.expansion).filter(([id, value]) => (occurrenceIndex.has(id) || groupKeys.has(id)) && typeof value === "boolean")) as Record<string, boolean>;
-        if (stored.page !== activeSlug.value) revealPath(selected.value);
+        if (stored.version === STATE_VERSION && isRecord(stored.expansion)) {
+          expansion.value = Object.fromEntries(Object.entries(stored.expansion).filter(([id, value]) => (occurrenceIndex.has(id) || groupKeys.has(id)) && typeof value === "boolean")) as Record<string, boolean>;
+        }
       }
     } catch { /* Stale or unavailable storage uses the configured baseline. */ }
-    save();
+    // Same-page remount/reload keeps explicit choices, including an active-path collapse.
+    if (!samePage) arrive();
+    // Persist without broadcasting: a late-activating controller must not reset
+    // a live peer's in-memory reveal; peers handle arrival themselves.
+    save(false);
     const sync = (event: Event) => {
       const state = (event as CustomEvent).detail;
       if (state?.context !== navigation.id || state.page !== activeSlug.value) return;
       selected.value = state.selected;
       query.value = state.query;
       expansion.value = state.expansion;
+      revealed.value = new Set(state.revealed);
     };
     const navigate = () => {
       if (lastPage === activeSlug.value) return;
       lastPage = activeSlug.value;
-      selected.value = reconcileSidebarScope(navigation, nodes, selected.value, activeSlug.value);
-      revealPath(selected.value);
+      selected.value = canonicalScope(reconcileSidebarScope(navigation, nodes, selected.value, activeSlug.value));
+      arrive();
       save();
     };
     document.addEventListener(syncEvent, sync);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "6.0.2",
+  "version": "6.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",
@@ -788,7 +788,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "6.0.2"
+    "@takazudo/zudo-doc-history-server": "6.1.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",