@takazudo/zudo-doc 9.0.0 → 9.1.0

package/dist/wind.json

@@ -67,6 +67,7 @@
     "col-span-full",
     "col-start-1",
     "contents",
+    "cursor-default",
     "cursor-not-allowed",
     "cursor-pointer",
     "disabled:cursor-default",
@@ -91,7 +92,6 @@
     "focus-visible:outline-accent",
     "focus-visible:outline-offset-2",
     "focus-visible:text-accent",
-    "focus-visible:text-fg",
     "focus-visible:underline",
     "focus-within:border-accent",
     "focus-within:z-local-1",
@@ -147,9 +147,11 @@
     "h-[0.5rem]",
     "h-[0.625rem]",
     "h-[0.875rem]",
+    "h-[1.0625rem]",
     "h-[1.125rem]",
     "h-[1.25rem]",
     "h-[1.575rem]",
+    "h-[1.875rem]",
     "h-[10rem]",
     "h-[14px]",
     "h-[1em]",
@@ -290,6 +292,7 @@
     "my-vsp-md",
     "no-underline",
     "object-contain",
+    "opacity-50",
     "opacity-60",
     "outline-none",
     "overflow-auto",
@@ -455,11 +458,13 @@
     "w-[0.5rem]",
     "w-[0.625rem]",
     "w-[0.875rem]",
+    "w-[1.0625rem]",
     "w-[1.125rem]",
     "w-[1.25rem]",
     "w-[1.575rem]",
     "w-[1.5rem]",
     "w-[1.75rem]",
+    "w-[1.875rem]",
     "w-[12rem]",
     "w-[14px]",
     "w-[16px]",

package/dist/zdtp-loader.d.ts

@@ -1,7 +1,7 @@
 import type { PanelConfig, PanelInstanceHandle } from "@takazudo/zdtp";
 export * from "@takazudo/zdtp";
 /**
- * Mount zdtp's opaque Preact root only while the activating island still owns
+ * Mount zdtp's opaque panel root only while the activating island still owns
  * the pending import. Once configured, zdtp keeps its document-lifetime root
  * and its existing navigation cleanup semantics.
  */

package/eject/header/gen-nav-overflow-script.mjs

@@ -28,9 +28,9 @@
 // SOURCE, strips TypeScript types deterministically via esbuild's
 // `transformSync()` (same rationale as gen-search-widget-script.mjs — see
 // that file's header comment for the full `ts.transpileModule()` vs esbuild
-// history, zudolab/zudo-doc#3422 / #3430 — identical here: esbuild is only a
+// history, zudolab/zudo-doc#3422 / #3430 — identical here: esbuild is a
 // package dependency (it is also used by the shipped ejected-header generator),
-// and the effective floor tracks the root `pnpm.overrides` range), executes
+// and its range matches the root `pnpm.overrides` entry), executes
 // each transpiled CommonJS module in an isolated sandbox (empty
 // `module`/`exports`; all four source files are import-free), then reads
 // the REAL runtime values off each sandbox's `exports`:

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

@@ -1,5 +1,5 @@
 /** @jsxRuntime automatic */
-// Server-rendered, zero-hydration content loading overlay.
+// Server-rendered, zero-hydration full-viewport loading overlay.
 //
 // Renders the overlay and its bootstrap into the document:
 //
@@ -53,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;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 show(){var el=document.getElementById(id);if(!el)return;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");});}
@@ -66,7 +66,11 @@ document.addEventListener(${JSON.stringify(NAVIGATION_ABORTED_EVENT)},function()
 }
 
 /**
- * Content loading overlay shown while a dynamic navigation is pending.
+ * Full-viewport loading overlay shown while a dynamic navigation is pending.
+ *
+ * Geometry belongs to `page-loading.css` (`position: fixed; inset: 0`); the
+ * bootstrap only toggles visibility. Header and sidebar stay stationary through
+ * their own named View Transition snapshots, not by clipping the scrim.
  *
  * Mount this once per layout (typically inside `DocLayoutWithDefaults`'s
  * `bodyEnd` slot, alongside the existing body-end providers). It is

package/eject/sidebar-tree-island/branch-preview.ts

@@ -0,0 +1,247 @@
+import { computed, signal, type ReadonlySignal, type Ref } from "@takazudo/zfb/zudo-react";
+
+/** Trigger attribute: the tooltip's title text. */
+export const TIP_ATTR = "data-sidebar-tip";
+/** Trigger attribute: optional secondary tooltip line. */
+export const TIP_DETAIL_ATTR = "data-sidebar-tip-detail";
+
+const TRIGGER_SELECTOR = `[${TIP_ATTR}]`;
+const FRAME_SELECTOR = "[data-sidebar-focus]";
+const POINTER_SHOW_DELAY_MS = 250;
+// Long enough to cross the gap from the trigger onto the tooltip.
+const HIDE_DELAY_MS = 120;
+const GAP_PX = 6;
+const VIEWPORT_MARGIN_PX = 8;
+
+let instanceCount = 0;
+
+export interface BranchPreview {
+  /** Occurrence previewed in this sidebar instance, or null. Never persisted or broadcast. */
+  active: ReadonlySignal<string | null>;
+  clear: () => void;
+}
+
+/** Hover preview is mouse/pen only so a touch tap focuses in one step and leaves nothing behind. */
+const isHoverPointer = (event: Event) => {
+  const type = (event as PointerEvent).pointerType;
+  return type === "mouse" || type === "pen";
+};
+
+const isFocusVisible = (element: Element) => {
+  try {
+    return element.matches(":focus-visible");
+  } catch {
+    return true;
+  }
+};
+
+const isActionableFrame = (element: Element) =>
+  element.matches(FRAME_SELECTOR) && element.getAttribute("aria-disabled") !== "true";
+
+const previewKey = (element: Element) =>
+  isActionableFrame(element) ? (element as HTMLElement).dataset.sidebarFocusScope || null : null;
+
+/**
+ * Transient branch preview + tooltip for one sidebar island instance.
+ * Call `activate()` from the island's `onActivate`; it returns the cleanup.
+ * The desktop tree and the mobile drawer are separate instances, so each
+ * visible sidebar owns at most one preview and one tooltip.
+ */
+export function createBranchPreview(navRef: Ref<HTMLElement>): BranchPreview & { activate: () => () => void } {
+  const pointerKey = signal<string | null>(null);
+  const focusKey = signal<string | null>(null);
+  // Pointer hover over an actionable frame wins over the keyboard-focused one.
+  const active = computed(() => pointerKey.value ?? focusKey.value);
+  let tooltip: HTMLElement | null = null;
+  let owner: HTMLElement | null = null;
+  let showTimer: ReturnType<typeof setTimeout> | undefined;
+  let hideTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const hideTooltip = () => {
+    clearTimeout(showTimer);
+    clearTimeout(hideTimer);
+    if (owner?.getAttribute("aria-describedby") === tooltip?.id) owner?.removeAttribute("aria-describedby");
+    owner = null;
+    if (tooltip) tooltip.hidden = true;
+  };
+
+  const clear = () => {
+    pointerKey.value = null;
+    focusKey.value = null;
+    hideTooltip();
+  };
+
+  const place = (trigger: HTMLElement, tip: HTMLElement) => {
+    // Measure from the origin: a stale right-side `left` would shrink-wrap the
+    // fixed tooltip to the remaining viewport width.
+    tip.style.left = "0px";
+    tip.style.top = "0px";
+    const anchor = trigger.getBoundingClientRect();
+    const box = tip.getBoundingClientRect();
+    const maxLeft = window.innerWidth - box.width - VIEWPORT_MARGIN_PX;
+    // Start past the sidebar's edge so the hoverable tooltip never covers the
+    // row's disclosure, which sits right beside the frame.
+    const edge = Math.max(anchor.right, navRef.current?.getBoundingClientRect().right ?? anchor.right);
+    let left = edge + GAP_PX;
+    let top = anchor.top + anchor.height / 2 - box.height / 2;
+    // No room beside the trigger (narrow drawer): drop below it instead.
+    if (left > maxLeft) {
+      left = Math.max(VIEWPORT_MARGIN_PX, Math.min(anchor.left + anchor.width / 2 - box.width / 2, maxLeft));
+      top = anchor.bottom + GAP_PX;
+      if (top + box.height > window.innerHeight - VIEWPORT_MARGIN_PX) top = anchor.top - GAP_PX - box.height;
+    }
+    top = Math.max(VIEWPORT_MARGIN_PX, Math.min(top, window.innerHeight - box.height - VIEWPORT_MARGIN_PX));
+    tip.style.left = `${Math.round(left)}px`;
+    tip.style.top = `${Math.round(top)}px`;
+  };
+
+  const showTooltip = (trigger: HTMLElement) => {
+    if (!tooltip) return;
+    clearTimeout(hideTimer);
+    if (owner && owner !== trigger && owner.getAttribute("aria-describedby") === tooltip.id) owner.removeAttribute("aria-describedby");
+    owner = trigger;
+    const title = document.createElement("strong");
+    title.textContent = trigger.getAttribute(TIP_ATTR) ?? "";
+    const parts: Node[] = [title];
+    const detail = trigger.getAttribute(TIP_DETAIL_ATTR);
+    if (detail) {
+      const line = document.createElement("span");
+      line.textContent = detail;
+      parts.push(line);
+    }
+    tooltip.replaceChildren(...parts);
+    tooltip.hidden = false;
+    trigger.setAttribute("aria-describedby", tooltip.id);
+    place(trigger, tooltip);
+  };
+
+  const scheduleHide = () => {
+    clearTimeout(showTimer);
+    clearTimeout(hideTimer);
+    hideTimer = setTimeout(hideTooltip, HIDE_DELAY_MS);
+  };
+
+  const triggerOf = (target: EventTarget | null) => {
+    const nav = navRef.current;
+    if (!nav || !(target instanceof Element)) return null;
+    const trigger = target.closest<HTMLElement>(TRIGGER_SELECTOR);
+    return trigger && nav.contains(trigger) ? trigger : null;
+  };
+
+  const activate = () => {
+    const tip = document.createElement("div");
+    tip.id = `zd-sidebar-tip-${++instanceCount}`;
+    tip.setAttribute("role", "tooltip");
+    tip.setAttribute("data-sidebar-tooltip", "");
+    tip.hidden = true;
+    document.body.append(tip);
+    tooltip = tip;
+
+    const onPointerOver = (event: Event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger || !isHoverPointer(event) || trigger.contains((event as PointerEvent).relatedTarget as Node | null)) return;
+      pointerKey.value = previewKey(trigger);
+      clearTimeout(hideTimer);
+      clearTimeout(showTimer);
+      if (owner === trigger && !tip.hidden) return;
+      showTimer = setTimeout(() => showTooltip(trigger), POINTER_SHOW_DELAY_MS);
+    };
+    const onPointerOut = (event: Event) => {
+      const trigger = triggerOf(event.target);
+      const next = (event as PointerEvent).relatedTarget as Node | null;
+      if (!trigger || trigger.contains(next)) return;
+      pointerKey.value = null;
+      // Moving onto the tooltip keeps it open (hoverable content).
+      if (next && tip.contains(next)) return;
+      if (owner === trigger && trigger === document.activeElement && isFocusVisible(trigger)) return;
+      scheduleHide();
+    };
+    const onFocusIn = (event: Event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger || !isFocusVisible(trigger)) return;
+      focusKey.value = previewKey(trigger);
+      clearTimeout(showTimer);
+      showTooltip(trigger);
+    };
+    const onFocusOut = (event: Event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger) return;
+      focusKey.value = null;
+      if (owner === trigger) scheduleHide();
+    };
+    const onTipEnter = () => clearTimeout(hideTimer);
+    const onTipLeave = (event: Event) => {
+      const next = (event as PointerEvent).relatedTarget as Node | null;
+      if (owner && next && owner.contains(next)) return;
+      if (owner && owner === document.activeElement && isFocusVisible(owner)) return;
+      scheduleHide();
+    };
+    // Capture phase so an open tooltip consumes the first Escape before the
+    // mobile drawer's document listener sees it (that listener honours
+    // defaultPrevented — layered Escape ownership, zudolab/zudo-doc#4393).
+    const onKeyDown = (event: Event) => {
+      const key = event as KeyboardEvent;
+      if (key.key !== "Escape" || key.isComposing || tip.hidden) return;
+      // Escape aimed at an unrelated surface (e.g. a dialog opened while the
+      // pointer still rests on a frame) must reach its own owner.
+      const target = key.target;
+      if (target instanceof Element && target !== document.body && !navRef.current?.contains(target) && !tip.contains(target)) {
+        hideTooltip();
+        pointerKey.value = null;
+        return;
+      }
+      key.preventDefault();
+      key.stopPropagation();
+      hideTooltip();
+      pointerKey.value = null;
+    };
+    // Keyboard focus scrolls the sidebar to reveal its target, so follow the
+    // trigger instead of dismissing; a trigger that left the DOM dismisses.
+    let scrollFrame = 0;
+    const onScroll = () => {
+      if (tip.hidden || scrollFrame) return;
+      scrollFrame = requestAnimationFrame(() => {
+        scrollFrame = 0;
+        if (tip.hidden) return;
+        if (owner?.isConnected) place(owner, tip);
+        else hideTooltip();
+      });
+    };
+    // The drawer stays mounted when closed and goes `inert`; a hidden sidebar
+    // must not keep a preview or tooltip.
+    // The <nav> sits inside a <Show> (the root-menu view can replace it), so
+    // fall back to the drawer itself when the ref is not mounted yet.
+    const drawer = navRef.current ? navRef.current.closest("[data-zd-mobile-sidebar]") : document.querySelector("[data-zd-mobile-sidebar]");
+    const observer = drawer ? new MutationObserver(() => { if (drawer.hasAttribute("inert")) clear(); }) : undefined;
+    observer?.observe(drawer!, { attributes: true, attributeFilter: ["inert"] });
+    // The lg breakpoint (Wind `lg:` / features.css) where the drawer and the desktop sidebar swap.
+    const media = window.matchMedia?.("(min-width: 1024px)");
+    const onBreakpoint = () => clear();
+    media?.addEventListener?.("change", onBreakpoint);
+
+    document.addEventListener("pointerover", onPointerOver);
+    document.addEventListener("pointerout", onPointerOut);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("focusout", onFocusOut);
+    document.addEventListener("keydown", onKeyDown, true);
+    document.addEventListener("scroll", onScroll, true);
+    tip.addEventListener("pointerenter", onTipEnter);
+    tip.addEventListener("pointerleave", onTipLeave);
+    return () => {
+      cancelAnimationFrame(scrollFrame);
+      clear();
+      observer?.disconnect();
+      media?.removeEventListener?.("change", onBreakpoint);
+      document.removeEventListener("pointerover", onPointerOver);
+      document.removeEventListener("pointerout", onPointerOut);
+      document.removeEventListener("focusin", onFocusIn);
+      document.removeEventListener("focusout", onFocusOut);
+      document.removeEventListener("keydown", onKeyDown, true);
+      document.removeEventListener("scroll", onScroll, true);
+      tip.remove();
+      tooltip = null;
+    };
+  };
+
+  return { active, clear, activate };
+}

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

@@ -19,15 +19,17 @@ import type { ResolvedDateFormats } from "../settings.js";
 import {
   INDENT,
   BASE_PAD,
+  CONNECTOR_OFFSET,
   connectorLeft,
   ConnectorLines,
   CategoryLinkIcon,
 } from "../tree-nav-shared/index.js";
-import { ChevronRight, ChevronLeft, Search } from "../icons/index.js";
+import { ChevronRight, ChevronLeft, Search, FocusFrame, RestoreArrow } from "../icons/index.js";
 import { ThemeToggle, type ThemeToggleLabels } from "../theme-toggle/index.js";
 import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 import { useSidebarScope, type ScopeControls } from "./scope-state.js";
+import { createBranchPreview } from "./branch-preview.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
 import {
@@ -47,6 +49,7 @@ import { formatMonthDay } from "../format-date/index.js";
 
 const STORAGE_KEY = "zd-sidebar-open";
 const GROUPED_TRAY_ITEM_DEPTH = 3;
+const TOGGLE_BOX_SIZE = "1.5rem";
 
 function ToggleChevron({
   isExpanded,
@@ -73,6 +76,11 @@ function padLeft(depth: number, forCategory: boolean): string {
   return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
 }
 
+/** Puts a 1px vertical guide on the center of a category row's leading toggle box. */
+function toggleGuideLeft(depth: number): string {
+  return `calc(${padLeft(depth, true)} + ${TOGGLE_BOX_SIZE} / 2 - 0.5px)`;
+}
+
 function getOpenSet(): Set<string> {
   try {
     const raw = sessionStorage.getItem(STORAGE_KEY);
@@ -274,10 +282,31 @@ export function SidebarTree({
   const scope = getScope();
   const activeSlug = useActiveSlug(navigation?.roots ?? nodes, currentSlug, currentPath);
   const query = signal("");
-  const { selected, selectedNodes, broader, labels, canRestore, changeScope, save, navRef, scopeControls } = useSidebarScope({
+  const { selected, selectedNodes, broader, labels, canRestore, changeScope, save, navRef, scopeControls: baseScopeControls } = useSidebarScope({
     nodes, navigation, activeSlug, query,
     locale: localeProp ?? localeLinks?.find((link) => link.active)?.code ?? "en",
   });
+  const branchPreview = createBranchPreview(navRef);
+  const scopeControls: TreeScopeControls | undefined = baseScopeControls
+    ? { ...baseScopeControls, preview: branchPreview.active }
+    : undefined;
+  if (navigation) {
+    scope.onActivate(() => {
+      const dispose = branchPreview.activate();
+      const onNavigate = () => branchPreview.clear();
+      document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+      return () => {
+        document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+        dispose();
+      };
+    });
+    // Scope changes, filtering and remounted rows invalidate a transient preview.
+    scope.effect(() => {
+      void selected.value;
+      void query.value;
+      branchPreview.clear();
+    });
+  }
   const showingRootMenu = signal(false);
   const filterRef: Ref<HTMLInputElement> = { current: null };
   const filterPlaceholder = signal("Filter...");
@@ -386,14 +415,10 @@ export function SidebarTree({
                     </button>
                     <Show when={canRestore}>{() => (
                       <button type="button" data-sidebar-restore on:click={() => changeScope(null)}
-                        title={labels.restore} aria-label={labels.restore}
+                        aria-label={labels.restore} data-sidebar-tip={labels.restoreTip}
                         style="width:40px;height:40px"
-                        class="grid place-items-center shrink-0 rounded text-muted hover:text-fg focus-visible:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent">
-                        <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
-                          <circle cx="12" cy="12" r="10" />
-                          <circle cx="12" cy="12" r="6" />
-                          <circle cx="12" cy="12" r="2" />
-                        </svg>
+                        class="grid place-items-center shrink-0 rounded text-muted hover:text-accent hover:bg-surface focus-visible:text-accent focus-visible:bg-surface focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent">
+                        <RestoreArrow class="h-[1.0625rem] w-[1.0625rem]" />
                       </button>
                     )}</Show>
                   </div>
@@ -443,8 +468,12 @@ export function SidebarTree({
 }
 SidebarTree.displayName = "SidebarTree";
 
+interface TreeScopeControls extends ScopeControls {
+  /** This sidebar instance's transient branch preview (occurrence id). */
+  preview: ReadonlySignal<string | null>;
+}
 interface ActiveProps {
-  scopeControls?: ScopeControls;
+  scopeControls?: TreeScopeControls;
   currentSlug: ReadonlySignal<string | undefined>;
   forceOpen: ReadonlySignal<boolean>;
 }
@@ -547,6 +576,7 @@ function TrayItem({
   isLast,
   showDate = false,
   depth = 1,
+  guideLeft,
   locale,
   dateFormats,
 }: {
@@ -556,6 +586,8 @@ function TrayItem({
   isLast: ReadonlySignal<boolean>;
   showDate?: boolean;
   depth?: number;
+  /** Draws this row's connector from the parent's toggle center instead of its depth column. */
+  guideLeft?: string;
   locale?: string;
   dateFormats?: ResolvedDateFormats;
 }) {
@@ -574,6 +606,12 @@ function TrayItem({
               depth={depth}
               isLast={isLast}
               topPad="var(--spacing-vsp-2xs)"
+              left={guideLeft}
+              width={
+                guideLeft
+                  ? `calc(${padLeft(depth, false)} - ${CONNECTOR_OFFSET} - ${guideLeft})`
+                  : undefined
+              }
             />
             <a
               href={computed(() => item.value.href ?? "")}
@@ -621,19 +659,23 @@ function ConnectorLinesLive({
   depth,
   isLast,
   topPad,
+  left,
+  width,
 }: {
   depth: number;
   isLast: ReadonlySignal<boolean>;
   topPad: string;
+  left?: string;
+  width?: string;
 }) {
   return (
     <Show
       when={isLast}
       fallback={() => (
-        <ConnectorLines depth={depth} isLast={false} topPad={topPad} />
+        <ConnectorLines depth={depth} isLast={false} topPad={topPad} left={left} width={width} />
       )}
     >
-      {() => <ConnectorLines depth={depth} isLast={true} topPad={topPad} />}
+      {() => <ConnectorLines depth={depth} isLast={true} topPad={topPad} left={left} width={width} />}
     </Show>
   );
 }
@@ -746,7 +788,15 @@ function TrayGroupNode({
       </div>
       <Show when={expanded}>
         {() => (
-          <div>
+          <div class="relative">
+            <div
+              class="absolute border-l border-dashed border-muted"
+              style={{
+                left: toggleGuideLeft(1),
+                top: "calc(-1 * var(--spacing-vsp-xs))",
+                height: "var(--spacing-vsp-xs)",
+              }}
+            />
             <For each={items} by={(item) => item.slug}>
               {(item, index) => (
                 <TrayItem
@@ -759,6 +809,7 @@ function TrayGroupNode({
                   locale={locale}
                   dateFormats={dateFormats}
                   depth={GROUPED_TRAY_ITEM_DEPTH}
+                  guideLeft={toggleGuideLeft(1)}
                 />
               )}
             </For>
@@ -865,18 +916,33 @@ function CategoryNode({
     if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value));
   });
   const expanded = computed(() => forceOpen.value || open.value);
+  const focusedRoot = computed(() => !!scopeControls?.isFocusedRoot(node.value.occurrenceId));
+  const previewed = computed(() => !!node.value.occurrenceId && scopeControls?.preview.value === node.value.occurrenceId);
+  const arrived = computed(() => !!node.value.occurrenceId && scopeControls?.arrived.value === node.value.occurrenceId);
   const focusButton = scopeControls ? (
     <button type="button" data-sidebar-focus data-sidebar-focus-scope={computed(() => node.value.occurrenceId ?? "")}
       on:click={() => scopeControls.focus(node.value)}
-      aria-label={computed(() => `${scopeControls.focusLabel}: ${node.value.label}`)}
-      title={computed(() => `${scopeControls.focusLabel}: ${node.value.label}`)}
-      class={computed(() => `ml-auto shrink-0 rounded px-hsp-xs py-vsp-2xs ${active.value ? "text-bg hover:bg-bg/10 focus-visible:bg-bg/10" : "text-muted hover:bg-surface hover:text-fg focus-visible:bg-surface focus-visible:text-fg"}`)}>
-      <span aria-hidden="true">◎</span>
+      aria-disabled={computed(() => (focusedRoot.value ? "true" : null))}
+      tabindex={computed(() => (focusedRoot.value ? -1 : null))}
+      aria-label={computed(() => (focusedRoot.value ? scopeControls.labels.focused(node.value.label) : scopeControls.labels.focus(node.value.label)))}
+      data-sidebar-tip={computed(() => (focusedRoot.value ? scopeControls.labels.focusedTip : scopeControls.labels.focusTip))}
+      data-sidebar-tip-detail={computed(() => node.value.label)}
+      class={computed(() => `ml-auto grid shrink-0 place-items-center rounded w-[1.875rem] h-[1.875rem] ${
+        focusedRoot.value
+          ? `cursor-default opacity-50 ${active.value ? "text-bg" : "text-muted"}`
+          : active.value
+            ? "text-bg hover:bg-bg/10 focus-visible:bg-bg/10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent"
+            : "text-muted hover:bg-accent/10 hover:text-accent focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent"
+      }`)}>
+      <FocusFrame class="h-[1.125rem] w-[1.125rem]" />
     </button>
   ) : null;
   const paddingLeft = padLeft(depth, true);
   return (
     <div
+      data-sidebar-branch
+      data-sidebar-preview={computed(() => (previewed.value ? "" : null))}
+      data-sidebar-arrived={computed(() => (arrived.value ? "" : null))}
       class={computed(
         () =>
           `${depth === 0 ? "border-t border-muted first:border-t-0" : ""} ${depth >= 1 && !isLast.value ? "relative" : ""}`,
@@ -888,11 +954,12 @@ function CategoryNode({
         {() => (
           <div
             class="absolute border-l border-solid border-muted z-local-1"
+            data-tree-connector
             style={{ left: connectorLeft(depth), top: "0px", bottom: "0px" }}
           />
         )}
       </Show>
-      <div class="relative">
+      <div class="relative" data-sidebar-row data-sidebar-current={computed(() => (active.value ? "" : null))}>
         <ConnectorLinesLive
           depth={depth}
           isLast={isLast}
@@ -980,7 +1047,7 @@ function CategoryNode({
       </div>
       <Show when={expanded}>
         {() => (
-          <div>
+          <div data-sidebar-children>
             <NodeList
               nodes={computed(() => node.value.children)}
               currentSlug={currentSlug}