@takazudo/zudo-doc 0.2.21 → 1.0.0

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

@@ -0,0 +1,103 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// Server-rendered, zero-hydration full-page loading overlay.
+//
+// Renders three things into the document:
+//
+//   1. A fixed-position overlay `<div>` with a centered spinner. Hidden
+//      by default (`opacity: 0; pointer-events: none;`) and made
+//      visible by adding `data-visible` to it.
+//   2. A `<style>` block that owns the overlay + spinner CSS plus the
+//      `prefers-reduced-motion` fallback. Inlined via
+//      `dangerouslySetInnerHTML` (matching the ColorSchemeProvider
+//      pattern) so no separate stylesheet has to be wired up.
+//   3. A small `<script>` that toggles the `data-visible` attribute on
+//      navigation lifecycle events. The event names come from the
+//      `@takazudo/zudo-doc/transitions` module — this component does
+//      not reach for the underlying browser event names directly. Under
+//      zfb's Strategy B SPA navigation, the v2 vocabulary resolves to
+//      `zfb:before-preparation` (BEFORE_NAVIGATE_EVENT) and
+//      `zfb:after-swap` (AFTER_NAVIGATE_EVENT); see
+//      `transitions/page-events.ts` for rationale.
+//
+// The component is intentionally not hydrated. Hydrating Preact just to
+// attach two listeners would be wasteful given the original Astro file
+// shipped a tiny imperative script — this port keeps that profile.
+
+import {
+  AFTER_NAVIGATE_EVENT,
+  BEFORE_NAVIGATE_EVENT,
+} from "../transitions/page-events.js";
+
+/** Default `id` for the overlay element. Stable so test rigs can target it. */
+export const PAGE_LOADING_OVERLAY_ID = "page-loading-overlay";
+
+export interface PageLoadingOverlayProps {
+  /**
+   * Override the DOM `id` used by both the overlay element and the
+   * bootstrap script. Useful when multiple overlays could co-exist on
+   * the page (e.g. tests). Defaults to `PAGE_LOADING_OVERLAY_ID`.
+   */
+  id?: string;
+}
+
+/**
+ * Build the inline bootstrap script body. Exported so test rigs can
+ * inspect / snapshot it without rendering the component.
+ */
+export function buildPageLoadingOverlayBootstrap(overlayId: string): string {
+  // Values are inlined as JSON literals so the script is fully
+  // self-contained and matches the `define:vars` shape used elsewhere
+  // (see ColorSchemeProvider). Event names come from the transitions
+  // module's exported constants — no raw `astro:*` strings live in
+  // this file.
+  const id = JSON.stringify(overlayId);
+  const before = JSON.stringify(BEFORE_NAVIGATE_EVENT);
+  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 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");});}
+document.addEventListener(${before},show);
+document.addEventListener(${after},hide);
+document.addEventListener(${before},setPending);
+document.addEventListener(${after},clearPending);
+})();`;
+}
+
+/**
+ * Full-page loading overlay shown during view-transition navigations.
+ *
+ * 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`,
+ * `.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
+ * version-switcher in zudolab/zudo-doc#1505; regression caught in W2A #1543).
+ */
+export default function PageLoadingOverlay({
+  id = PAGE_LOADING_OVERLAY_ID,
+}: PageLoadingOverlayProps = {}) {
+  return (
+    <>
+      <div
+        id={id}
+        class="page-loading-overlay"
+        aria-hidden="true"
+      >
+        <span class="page-loading-spinner" />
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: buildPageLoadingOverlayBootstrap(id),
+        }}
+      />
+    </>
+  );
+}

package/eject/sidebar/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Public entry for the framework-agnostic sidebar shell.
+ *
+ * Consumers import from `@takazudo/zudo-doc/sidebar`:
+ *
+ *   import {
+ *     Sidebar,
+ *     type SidebarProps,
+ *     type SidebarNavNode,
+ *     type SidebarRootMenuItem,
+ *     type SidebarLocaleLink,
+ *     type SidebarTreeIslandProps,
+ *   } from "@takazudo/zudo-doc/sidebar";
+ *
+ * The shell does NOT include the SidebarTree island itself — the host
+ * project's existing Preact island is plugged in via the
+ * `treeComponent` prop (or rendered as `children`).
+ */
+
+export { Sidebar } from "./sidebar.js";
+export type { SidebarProps } from "./sidebar.js";
+export type {
+  SidebarLocaleLink,
+  SidebarNavNode,
+  SidebarRootMenuItem,
+  SidebarTreeIslandProps,
+} from "./types.js";

package/eject/sidebar/sidebar.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// JSX port of src/components/sidebar.
+//
+// The original Astro template was almost entirely data assembly —
+// build root-menu items from `settings.headerNav`, load the locale's
+// docs collection, build the nav tree for the active section, optionally
+// remap hrefs for versioned routes, and finally render the project's
+// `<SidebarTree client:load .../>` Preact island.
+//
+// All of that data-prep depends on host-only helpers (`@/config/i18n`,
+// `@/utils/sidebar`, `@/utils/locale-docs`, `@/utils/base`,
+// `@/config/settings`) that v2 must not import. This shell therefore
+// keeps the data-prep on the host side and only provides:
+//
+//   - typed props that match the SidebarTree island's prop shape, so
+//     the host's prep code can be typed against v2's interface;
+//   - a `treeComponent` prop the host supplies (their existing Preact
+//     island) — the shell instantiates it with the typed props and
+//     forwards everything;
+//   - a `children` fallback for callers that want to render the tree
+//     themselves (useful for tests, fixtures, and downstream projects
+//     that swap the tree out wholesale).
+//
+// Wave 13 ("smoke-toc duplicate-nav regression follow-on", zudolab/zudo-doc#1355):
+// before this refactor, this module exported a `Sidebar` wrapper that
+// itself called `Island({when:"load", children:<SidebarInner/>})` and
+// returned the wrapped div. The zfb island scanner picked the exported
+// `Sidebar` (the wrapper) as the bundle's hydration target, so on the
+// client `mountIslands` ran `hydrate(<Sidebar/>, dataIslandDiv)` where
+// the rendered vnode itself emitted *another* `<div data-zfb-island=
+// "Sidebar"><SidebarInner/></div>` inside the existing one. Unlike the
+// `Toc` / `MobileToc` case (where the inner re-rendered identical
+// content alongside the SSR'd content, producing a visible duplicate),
+// the duplicate here was silent: the host passes `treeComponent` (a
+// Preact component function) as a prop, and `island.ts`'s
+// `captureSerializableProps` does `JSON.stringify` on the props bag,
+// which silently drops function values. At hydrate time the
+// deserialized props had no `treeComponent`, `SidebarInner` returned
+// `null`, and the appended wrapper-div was empty. Net result: an extra
+// dead-mount data-zfb-island Sidebar div alongside the SSR'd tree, with
+// no observable content — but a wasted hydration slot, and the actual
+// user-facing event-handler / state work was being done entirely by
+// the host's `SidebarTree` island registration.
+//
+// Fix: same shape as Toc / MobileToc — drop the `Island`-wrapping
+// outer, export the bare component (was `SidebarInner`) as `Sidebar`,
+// pin `displayName` explicitly. The `<Island when="load">` wrapper is
+// applied at the call site (`<DocLayoutWithDefaults>`).
+
+import type { ComponentChildren, FunctionComponent, VNode } from "preact";
+
+import type { SidebarTreeIslandProps } from "./types.js";
+
+export interface SidebarProps extends SidebarTreeIslandProps {
+  /**
+   * The host's SidebarTree component. When present, the shell renders
+   * `<TreeComponent {...islandProps} />` with the typed props below.
+   * Mutually exclusive with `children`: prefer this form so v2 owns the
+   * prop forwarding contract.
+   */
+  treeComponent?: FunctionComponent<SidebarTreeIslandProps>;
+  /**
+   * Pre-rendered tree content — falls back to this when
+   * `treeComponent` is omitted. Useful for tests and for layouts that
+   * compose the tree separately (e.g. inside a host wrapper
+   * that needs `client:load` on the actual island element).
+   */
+  children?: ComponentChildren;
+}
+
+/**
+ * Sidebar shell — typed wrapper around the SidebarTree island.
+ *
+ * Two usage shapes (matching the breadcrumb shell's pattern):
+ *
+ *   1. Pass `treeComponent` plus the data props (`nodes`,
+ *      `rootMenuItems`, `localeLinks`, …). The shell forwards them all
+ *      to the supplied component.
+ *
+ *   2. Pass `children` (e.g. a pre-instantiated `<SidebarTree
+ *      client:load … />` from an Astro wrapper). The shell renders
+ *      them as-is — the typed island props are then unused but kept on
+ *      the type signature so call-sites stay self-documenting.
+ *
+ * **The caller is responsible for wrapping this in `<Island when="load">`**
+ * so the SSG output emits the `data-zfb-island="Sidebar"` hydration
+ * marker around the rendered tree. `<DocLayoutWithDefaults>` does this
+ * for you; consumers who render `<Sidebar>` outside the default layout
+ * (e.g. via the `sidebarOverride` prop or in a custom layout) must
+ * apply the wrapper themselves — otherwise no hydration marker is
+ * emitted, and the runtime walks past the SSR'd tree without claiming
+ * it as an island. Either way the actual user-facing interactivity
+ * comes from the `treeComponent`'s own island registration; the
+ * `<Island>` wrapper here exists so the shell can host data-only
+ * variants in the future without losing the marker contract.
+ */
+export function Sidebar(props: SidebarProps): VNode | null {
+  const {
+    treeComponent: TreeComponent,
+    children,
+    nodes,
+    currentSlug,
+    rootMenuItems,
+    backToMenuLabel,
+    localeLinks,
+    themeDefaultMode,
+  } = props;
+
+  if (TreeComponent) {
+    return (
+      <TreeComponent
+        nodes={nodes}
+        currentSlug={currentSlug}
+        rootMenuItems={rootMenuItems}
+        backToMenuLabel={backToMenuLabel}
+        localeLinks={localeLinks}
+        themeDefaultMode={themeDefaultMode}
+      />
+    );
+  }
+
+  if (children !== undefined && children !== null) {
+    return <>{children}</>;
+  }
+
+  return null;
+}
+// Pin the marker name to "Sidebar" regardless of how Preact's compat
+// layer or esbuild minification renames the function. Island's SSR
+// pass reads `displayName ?? name` to derive the marker string;
+// pinning both means the SSG marker stays `data-zfb-island="Sidebar"`
+// independent of the bundle's symbol-renaming.
+Sidebar.displayName = "Sidebar";

package/eject/sidebar/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Public types for the framework-agnostic sidebar shell.
+ *
+ * The original `sidebar` mixed three concerns:
+ *   1. Building `rootMenuItems` from `settings.headerNav` (with i18n
+ *      label resolution and version-aware hrefs).
+ *   2. Building the doc tree via `loadLocaleDocs` +
+ *      `buildSidebarForSection`, then optionally remapping hrefs to
+ *      versioned paths.
+ *   3. Rendering a `<SidebarTree client:load .../>` Preact island.
+ *
+ * Concerns (1) and (2) depend on host-only helpers that v2 must not
+ * reach into. The v2 shell exists to:
+ *   - publish the prop shape so the host's data prep code can be
+ *     typed against a v2-owned interface, and
+ *   - render whatever the host hands in (typically the project's
+ *     `<SidebarTree client:load .../>` island) inside a typed wrapper.
+ *
+ * The structural types here mirror `src/utils/docs.ts` (`NavNode`) and
+ * `src/types/locale.ts` (`LocaleLink`) so the host can keep using its
+ * existing data-prep pipeline without re-mapping fields.
+ */
+
+/**
+ * One node in the navigation tree the SidebarTree island renders.
+ * Matches `NavNode` in the host project's `src/utils/docs.ts`.
+ */
+export interface SidebarNavNode {
+  slug: string;
+  label: string;
+  description?: string;
+  position: number;
+  href?: string;
+  hasPage: boolean;
+  children: SidebarNavNode[];
+  sortOrder?: "asc" | "desc";
+  collapsed?: boolean;
+}
+
+/**
+ * Item in the root-level "Docusaurus-style" menu shown above the
+ * doc tree on mobile / inside the back-to-menu view.
+ */
+export interface SidebarRootMenuItem {
+  label: string;
+  href: string;
+  children?: SidebarRootMenuItem[];
+}
+
+/**
+ * Locale switcher link rendered inside the mobile sidebar footer.
+ * Matches `LocaleLink` in the host project's `src/types/locale.ts`.
+ */
+export interface SidebarLocaleLink {
+  code: string;
+  label: string;
+  href: string;
+  active: boolean;
+}
+
+/**
+ * Props the SidebarTree island consumes. The shell forwards these
+ * to whichever component the host plugs in via {@link SidebarProps.treeComponent}
+ * (or to nothing, when the host renders its own tree as `children`).
+ */
+export interface SidebarTreeIslandProps {
+  nodes: SidebarNavNode[];
+  currentSlug?: string;
+  rootMenuItems?: SidebarRootMenuItem[];
+  backToMenuLabel?: string;
+  localeLinks?: SidebarLocaleLink[];
+  themeDefaultMode?: "light" | "dark";
+}

package/eject/tab-item/index.ts

@@ -0,0 +1,7 @@
+// E5 framework primitives — tab-item visual wrapper.
+//
+// Subpath: `@takazudo/zudo-doc/tab-item`. JSX port of
+// the legacy `tab-item` component from the host project.
+
+export { TabItem, default } from "./tab-item.js";
+export type { TabItemProps } from "./tab-item.js";

package/eject/tab-item/tab-item.tsx

@@ -0,0 +1,70 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// JSX port of the legacy `tab-item` component.
+//
+// Visual wrapper for one tab panel inside a Tabs group. Server-rendered,
+// no hydration. The companion Tabs island reads `data-tab-value` /
+// `data-tab-label` / `data-tab-default` to wire interactivity, so the
+// attribute shape here must mirror the Astro original byte-for-byte.
+
+import type { ComponentChildren } from "preact";
+
+export interface TabItemProps {
+  /** Human-readable label rendered by the parent Tabs trigger row. */
+  label: string;
+  /**
+   * Optional stable value for the tab. Falls back to `label` when
+   * omitted, matching the Astro original's `value ?? label`.
+   */
+  value?: string;
+  /**
+   * When true, this panel is the initially-active one. Encoded as the
+   * empty-string `data-tab-default` attribute so plain attribute
+   * selectors (`[data-tab-default]`) still match.
+   */
+  default?: boolean;
+  /** Panel body. */
+  children?: ComponentChildren;
+}
+
+/**
+ * One tab panel.
+ *
+ * Wave 11 (zudolab/zudo-doc#1355): the default panel is rendered
+ * **without** the `hidden` attribute so the SSR HTML already shows the
+ * correct active panel before any JS runs. Non-default panels keep
+ * `hidden`. This avoids the post-Wave-10 regression where the tabs
+ * init script could land after first paint and flash an empty tab
+ * group; it also gives the no-JS path a usable default tab.
+ *
+ * The companion `TabsInit` script remains the source of truth at
+ * runtime — it re-derives the active tab from `localStorage` and
+ * `[data-tab-default]` and reapplies `hidden` / `aria-selected` so
+ * the SSR-rendered defaults survive group sync and View Transitions.
+ */
+export function TabItem({
+  label,
+  value,
+  default: isDefault,
+  children,
+}: TabItemProps) {
+  return (
+    <div
+      class="tab-panel"
+      role="tabpanel"
+      data-tab-value={value ?? label}
+      data-tab-label={label}
+      // `data-tab-default={undefined}` omits the attribute entirely,
+      // matching the Astro template's conditional spread.
+      data-tab-default={isDefault ? "" : undefined}
+      // Render `hidden` only on non-default panels so the SSR markup
+      // shows the active panel immediately (no JS-required flash).
+      hidden={isDefault ? undefined : true}
+    >
+      {children}
+    </div>
+  );
+}
+
+export default TabItem;

package/eject/theme-toggle/color-scheme-sync.ts

@@ -0,0 +1,73 @@
+// Shared color-scheme state helpers for ThemeToggle (#2012 E3).
+//
+// Two ThemeToggle instances can be mounted at once (header + mobile
+// sidebar footer). Each instance holds its own `mode` state, so a
+// toggle in one used to leave the other's icon stale — the instances
+// only read the DOM at mount. These helpers centralise the write path
+// (`applyColorScheme`) and give every instance a subscription point
+// (`subscribeColorSchemeChanged`) keyed on the `color-scheme-changed`
+// window event, which `applyColorScheme` dispatches after mutating the
+// DOM. The same event is already consumed by the zdtp design-token
+// panel, so the event name is a cross-package contract — do not rename.
+//
+// This module is intentionally NOT marked "use client": zfb's island
+// scanner registers every exported binding of a "use client" file as an
+// island, and these helpers are plain functions, not components. They
+// run in the browser only (called from the ThemeToggle island and
+// unit tests).
+
+export type ColorSchemeMode = "light" | "dark";
+
+export const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
+
+const STORAGE_KEY = "zudo-doc-theme";
+
+/**
+ * Read the active color scheme from `<html data-theme>`. Falls back to
+ * `defaultMode` when the attribute is missing or holds an unexpected
+ * value (e.g. before the ColorSchemeProvider bootstrap script ran).
+ */
+export function readColorSchemeFromDom(
+  defaultMode: ColorSchemeMode,
+): ColorSchemeMode {
+  const actual = document.documentElement.getAttribute("data-theme");
+  return actual === "light" || actual === "dark" ? actual : defaultMode;
+}
+
+/**
+ * Apply `next` as the active color scheme: mutate the DOM, persist the
+ * preference, and notify every subscriber (including other mounted
+ * ThemeToggle instances and the zdtp design-token panel) via the
+ * `color-scheme-changed` window event.
+ *
+ * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
+ * panel owns its own storage lifecycle: it persists the unified tweak envelope
+ * under `zudo-doc-tweak-state-v3` (auto-migrating the legacy
+ * `zudo-doc-tweak-state-v2` / `zudo-doc-tweak-state` keys into it), and its own
+ * `color-scheme-changed` listener clears applied inline styles and re-seeds the
+ * color slice from the newly active scheme. An earlier version of this function
+ * deleted `zudo-doc-tweak-state` + `-v2` on every toggle, which (a) targeted
+ * stale keys after zdtp moved to v3 — so it no longer did anything — and
+ * (b) when it did fire, wiped the whole envelope including scheme-independent
+ * spacing/typography/size tweaks, contradicting the documented carry-over
+ * guarantee. So the host no longer touches zdtp's private storage keys.
+ *
+ * Whether palette tweaks should instead persist per-scheme (so a light/dark
+ * round-trip keeps them) is a zdtp design question tracked upstream at
+ * Takazudo/zudo-design-token-panel#343. See zudo-doc#2037.
+ */
+export function applyColorScheme(next: ColorSchemeMode): void {
+  document.documentElement.setAttribute("data-theme", next);
+  document.documentElement.style.colorScheme = next;
+  localStorage.setItem(STORAGE_KEY, next);
+  window.dispatchEvent(new CustomEvent(COLOR_SCHEME_CHANGED_EVENT));
+}
+
+/**
+ * Subscribe to color-scheme changes. Returns an unsubscribe function
+ * (suitable as a `useEffect` cleanup).
+ */
+export function subscribeColorSchemeChanged(listener: () => void): () => void {
+  window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
+  return () => window.removeEventListener(COLOR_SCHEME_CHANGED_EVENT, listener);
+}

package/eject/theme-toggle/index.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// BARE (non-island-wrapped) theme toggle — the single ThemeToggle
+// implementation (#2012 E2). Published as the dedicated
+// `@takazudo/zudo-doc/theme-toggle` subpath so hosts can compose it
+// into their own `<Island>` wrappers (or nest it inside another island,
+// e.g. the mobile sidebar footer) without inheriting an extra island
+// layer. The island-wrapped variant for the `./theme` barrel lives in
+// `../theme/theme-toggle.tsx`, which wraps this component.
+//
+// Use the preact hook entrypoints directly — zfb's esbuild step does
+// not alias "react" to "preact/compat", so importing from "react" here
+// would fail to resolve.
+import { useState, useEffect } from "preact/hooks";
+import {
+  applyColorScheme,
+  readColorSchemeFromDom,
+  subscribeColorSchemeChanged,
+  type ColorSchemeMode,
+} from "./color-scheme-sync.js";
+
+function SunIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      width="20"
+      height="20"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="12" cy="12" r="5" />
+      <line x1="12" y1="1" x2="12" y2="3" />
+      <line x1="12" y1="21" x2="12" y2="23" />
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+      <line x1="1" y1="12" x2="3" y2="12" />
+      <line x1="21" y1="12" x2="23" y2="12" />
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+    </svg>
+  );
+}
+
+function MoonIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      width="20"
+      height="20"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  );
+}
+
+export interface ThemeToggleProps {
+  defaultMode?: ColorSchemeMode;
+}
+
+// NAMED export (not default) on purpose: tsup compiles a default export
+// to `export { ThemeToggle as default }`, an alias shape zfb's island
+// scanner does not recognize — the island then never registers and the
+// header toggle ships dead (zero hydration). Named exports compile to
+// `export { ThemeToggle }`, which the scanner handles (same pattern as
+// the package's MobileToc island).
+export function ThemeToggle({
+  defaultMode = "dark",
+}: ThemeToggleProps) {
+  // Initial state must match server render to avoid hydration mismatch.
+  // Actual theme is synced from DOM in useEffect below.
+  const [mode, setMode] = useState<ColorSchemeMode>(defaultMode);
+
+  useEffect(() => {
+    const sync = () => setMode(readColorSchemeFromDom(defaultMode));
+    sync();
+    // Cross-instance sync (#2012 E3): every mounted toggle re-reads the
+    // DOM whenever any instance (or the zdtp panel) applies a scheme,
+    // so the header toggle and the sidebar-footer toggle never disagree.
+    return subscribeColorSchemeChanged(sync);
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  function toggle() {
+    const next = mode === "dark" ? "light" : "dark";
+    setMode(next);
+    applyColorScheme(next);
+  }
+
+  const nextMode = mode === "dark" ? "light" : "dark";
+
+  return (
+    <button
+      onClick={toggle}
+      aria-label={`Switch to ${nextMode} mode`}
+      className="text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
+    >
+      {mode === "dark" ? <SunIcon /> : <MoonIcon />}
+    </button>
+  );
+}
+// Pin the island marker name to "ThemeToggle" regardless of bundler
+// identifier mangling: zfb's Island() derives the SSR marker via
+// `displayName ?? name`, and esbuild may rename the function when
+// another binding shares the name in the same bundle. Setting
+// displayName explicitly keeps the emitted marker aligned with the
+// island-manifest entry. zudolab/zudo-doc#1446.
+ThemeToggle.displayName = "ThemeToggle";

package/eject/toc/cx.ts

@@ -0,0 +1,38 @@
+/**
+ * Tiny `clsx`-style class name joiner. Accepts strings, falsy values,
+ * and arrays/objects of the same — only truthy strings survive.
+ *
+ * Framework primitives keep their dependency surface minimal so that a
+ * downstream consumer of `@takazudo/zudo-doc/toc` does not need an extra
+ * runtime dep just for class name composition. The behavior here is the
+ * subset the TOC primitives use; see `clsx` for the full feature set.
+ */
+type ClassValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | ClassValue[]
+  | { [key: string]: unknown };
+
+export function cx(...args: ClassValue[]): string {
+  const out: string[] = [];
+  for (const arg of args) {
+    if (!arg) continue;
+    if (typeof arg === "string") {
+      out.push(arg);
+    } else if (typeof arg === "number" || typeof arg === "bigint") {
+      out.push(String(arg));
+    } else if (Array.isArray(arg)) {
+      const inner = cx(...arg);
+      if (inner) out.push(inner);
+    } else if (typeof arg === "object") {
+      for (const key of Object.keys(arg)) {
+        if ((arg as Record<string, unknown>)[key]) out.push(key);
+      }
+    }
+  }
+  return out.join(" ");
+}

package/eject/toc/index.ts

@@ -0,0 +1,11 @@
+export { Toc } from "./toc.js";
+export type { TocProps } from "./toc.js";
+export { MobileToc } from "./mobile-toc.js";
+export type { MobileTocProps } from "./mobile-toc.js";
+export { useActiveHeading, getActiveHeadingId } from "./use-active-heading.js";
+export type { UseActiveHeadingResult } from "./use-active-heading.js";
+export type { HeadingItem } from "./types.js";
+// Exposed so consumers wiring their own scanner-visible Toc/MobileToc shims
+// (the override pattern from zudolab/zudo-doc#2057) can derive the locale TOC
+// label from the page `lang` without hand-mirroring the lang→title map.
+export { getTocTitle } from "./toc-title.js";