@takazudo/zudo-doc 5.28.2 → 6.0.0

package/dist/theme.css

@@ -1,85 +1,5 @@
-/* ============================================================================
- * @takazudo/zudo-doc — default design tokens + project-agnostic base rules
- *
- * Shipped to consumers as `@takazudo/zudo-doc/theme.css` (copied to
- * `dist/theme.css` by scripts/copy-theme-css.mjs on build). Single source of
- * truth for the default `@theme` token block (colors, spacing, icon sizes,
- * elevation, typography, radius, breakpoints, z-index) plus the small set of
- * project-agnostic base rules (scroll-margin, selection color, focus ring,
- * search / find-in-page highlight, version-switcher visibility) every
- * zudo-doc project needs. See zudolab/zudo-doc#2655.
- *
- * ── @import order (load-bearing) ────────────────────────────────────────────
- * The consumer's global.css MUST import this file:
- *   1. AFTER `@layer zd-preflight, zd-flow;` and the two Tailwind imports
- *      (`tailwindcss/preflight` layer(zd-preflight), `tailwindcss/utilities`).
- *      Those three lines stay project-side — path-relative `@source`/`@layer`
- *      resolution requires them to live in the consumer's own CSS file (see
- *      packages/create-zudo-doc/templates/base/src/styles/global.css).
- *   2. BEFORE `@takazudo/zudo-doc/safelist.css`, `content.css`,
- *      `page-loading.css`, and `features.css` — all four consume the
- *      `@theme` tokens defined here (colors, spacing, typography, z-index),
- *      and `content.css`'s `@layer zd-flow` rule depends on the cascade
- *      layer order already being established by the time it loads.
- *   3. BEFORE the project's own token-override `@theme { … }` block — Tailwind
- *      v4 `@theme` resolution is last-declaration-wins per custom property,
- *      so a later project block can redefine any default declared here.
- *
- * ── Consumer contract ────────────────────────────────────────────────────────
- * The consumer must inject the `--zd-*` ramp/role custom properties this file
- * aliases into `--color-*` tokens (`ColorSchemeProvider`, see
- * `@takazudo/zudo-doc/theme`). Without them every `--color-*` token below
- * resolves to nothing (the tight-token guardrail below wipes Tailwind's
- * default palette; only `--zd-*`-backed aliases repopulate it).
- *
- * Namespace contract: zudo-doc reserves the 23 bare `--color-*` alias names
- * declared in the first block plus the `--color-zd-*` prefix. Every other
- * `--color-*` name, such as `--color-acme-*`, belongs to the embedder. A
- * second `@theme` block that defines any reserved bare name in the same
- * document is unsupported: Tailwind merges every `@theme` block reached from
- * the entry, last declaration wins, and no error is reported. Embedders must
- * namespace their own tokens (`--color-<theirs>-*`), import this file before
- * their own `@theme` block so this reset cannot reach their tokens, or import
- * `@takazudo/zudo-doc/theme-no-reset.css` (#4055) when import order is outside
- * their control. Consume zudo-doc colors through `--color-zd-*` / `bg-zd-*`.
- *
- * Deliberately NOT shipped here: `--color-page-loading-overlay`. That scrim
- * token stays feature-injected by a project's `dynamicPageTransition` wiring
- * (its default depends on `--color-overlay`, which IS defined below) — do
- * not add it to this base block.
- *
- * ── Z-index defaults ─────────────────────────────────────────────────────────
- * The 13 `--z-index-*` entries below are the package DEFAULT tiers (mirrors
- * `defaultZIndexTiers` from `@takazudo/zudo-doc/z-index-defaults`, #2654).
- * A project only needs its own `src/config/z-index-tokens.ts` +
- * `gen:z-index`/`check:z-index` codegen wiring if it OVERRIDES a tier — its
- * own `@theme` block (declared after this file's import) simply redefines
- * the specific `--z-index-<name>` it wants to change.
- * ============================================================================ */
-
-@theme {
-  /* ========================================
-   * Tight-token color reset
-   *
-   * Wipes all Tailwind default color tokens (`--color-*`) so only
-   * project-defined palette and semantic tokens remain. This enforces
-   * zudo-doc's tight-token policy: "NEVER use Tailwind default colors"
-   * (documented per-project in src/CLAUDE.md's Color Rules). Semantic color
-   * tokens (defined below) are added back after this reset.
-   *
-   * The upstream split-import fix (zfb#159 / 9e37551, shipped in f68a9ba)
-   * eliminated the original leak cause (zfb no longer prepends the full
-   * @import "tailwindcss" bundle). The reset is retained as an explicit
-   * design guardrail — it prevents accidental default palette bleed from any
-   * future upstream change and keeps the color surface intentional.
-   *
-   * NOT reset: `--spacing` (the base spacing scale, default 0.25rem).
-   * Tailwind spacing utilities compute as calc(var(--spacing) * N); wiping
-   * `--spacing` collapses them to zero (observed in Wave 4 Sub-7 #1403).
-   * This guardrail resets ONLY the color namespace — never widen it.
-   * ======================================== */
-  --color-*: initial;
-
+/* Authored design properties backing zudo-wind tokens. */
+:root {
   /* ========================================
    * Colors — Three-tier token system
    * ======================================== */
@@ -148,14 +68,7 @@
   /* Image overlay button chrome */
   --spacing-image-overlay-inset: 0.5rem;  /* 8px — overlay button corner inset + internal padding */
 
-  /* ========================================
-   * Elevation — the tight `@import "tailwindcss/utilities"` (no default
-   * @theme) drops Tailwind's default shadow scale, so `shadow-*` utilities
-   * generate nothing. Re-add the one elevation the components use: header
-   * and version-switcher dropdown panels apply `shadow-lg`. Value is
-   * Tailwind v4's default shadow-lg; the black is intentionally
-   * theme-independent (a drop shadow is absence of light, not a themed color).
-   * ======================================== */
+  /* Package elevation used by the header and dropdown panels. */
   --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
 
   /* ========================================
@@ -186,6 +99,7 @@
   --leading-snug: 1.375;
   --leading-normal: 1.5;
   --leading-relaxed: 1.625;
+  --leading-none: 1;
 
   /* Letter spacing / tracking (4 steps) */
   --tracking-tight: -0.025em;   /* headings, display text */
@@ -198,7 +112,8 @@
    * ======================================== */
   --radius-DEFAULT: 0.25rem;    /* 4px — rounded */
   --radius-lg: 0.5rem;          /* 8px — rounded-lg */
-  --radius-full: 9999px;        /* rounded-full */
+  --radius-full: 9999px;
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);        /* rounded-full */
 
   /* ========================================
    * Breakpoints (3 steps)
@@ -208,30 +123,8 @@
   --breakpoint-xl: 1280px;
 }
 
-/* ==========================================================================
- * Tailwind-facing zudo-doc namespace aliases
- *
- * zudolab/zudo-doc#4051 needs a collision-free surface for code outside
- * zudo-doc. An embedder's own components can use `bg-zd-*` / `var(--color-zd-*)`
- * without touching the bare tier consumed by the package chrome.
- *
- * This block is `static` because Tailwind v4 emits a plain `@theme` token into
- * `:root` only when something in its own scan consumes it. zudo-doc never
- * scans the code that consumes these aliases, so the variables must always be
- * emitted. `static` guarantees the variables; `bg-zd-*` utilities are still
- * generated only when the consumer's own Tailwind scan sees those classes.
- *
- * Keep this block after the reset: `--color-*: initial` clears every
- * `--color-*` declared before it in the merged theme, regardless of the file
- * that declared it. The package chrome deliberately continues consuming the
- * bare tier; do not migrate call sites ad hoc.
- *
- * The raw tier is prefix-first (`--zd-*`) outside `@theme`; this semantic tier
- * is category-first (`--color-zd-*`) inside `@theme`. A third ordering that
- * puts the namespace before the category is disconnected from both tiers and
- * must never be introduced.
- * ========================================================================== */
-@theme static {
+/* Namespaced color aliases remain available to external consumers. */
+:root {
   --color-zd-bg: var(--zd-bg);
   --color-zd-fg: var(--zd-fg);
   --color-zd-sel-bg: var(--zd-selection-bg);
@@ -261,9 +154,8 @@
  * Z-index tiers — semantic, single-namespace default scale.
  *
  * The 13 tokens below are the package DEFAULTS (mirrors defaultZIndexTiers
- * from @takazudo/zudo-doc/z-index-defaults, #2654). Tailwind v4 reads each
- * --z-index-<name> theme key and generates a `z-<name>` utility, so e.g.
- * --z-index-toolbar: 20 produces `.z-toolbar { z-index: 20 }`; raw CSS can
+ * from @takazudo/zudo-doc/z-index-defaults, #2654). The wind config points at each
+ * --z-index-<name> property and generates a `z-<name>` utility. Raw CSS can
  * also reference `z-index: var(--z-index-<name>)`.
  *
  * A project only needs its own src/config/z-index-tokens.ts +
@@ -271,7 +163,7 @@
  * GENERATED:Z_INDEX block that used to live in every project's global.css is
  * now opt-in customization only, not a mandatory per-project artifact.
  * ======================================== */
-@theme inline {
+:root {
   --z-index-content: 0;
   --z-index-local-1: 1;
   --z-index-local-2: 2;
@@ -301,7 +193,7 @@
   --text-scale-xl:  3rem;       /* 48px */
   --text-scale-2xl: 3.75rem;    /* 60px */
 
-  --default-transition-duration: 150ms; /* consumed by image-enlarge and hash-link opacity fade */
+  --default-transition-duration: 150ms; /* consumed by image-enlarge transitions */
   --zd-transition-slow: 200ms;          /* sidebar transform/visibility and content-band max-width */
   --zd-transition-slower: 300ms;        /* view-transition fade-in (contentFadeIn animation) */
   --zd-header-h: 80px;                  /* sticky header height; consumed by scroll-margin-top on [id] anchors */
@@ -326,6 +218,40 @@ body {
 }
 
 @layer base {
+  /* zudo-wind preflight parity missing from zudo-wind owned-v1. */
+  ::backdrop, ::file-selector-button {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    border: 0 solid;
+  }
+  [hidden]:where(:not([hidden="until-found"])) { display: none !important; }
+  html { font-family: var(--font-sans); -webkit-tap-highlight-color: transparent; }
+  code, kbd, samp, pre { font-family: var(--font-mono); }
+  button, input, select, optgroup, textarea, ::file-selector-button {
+    background-color: transparent;
+    border-radius: 0;
+  }
+  button, ::file-selector-button { appearance: button; }
+  :disabled { opacity: 1; }
+  ::placeholder { opacity: 1; color: color-mix(in oklab, currentColor 50%, transparent); }
+  ::file-selector-button {
+    font: inherit;
+    font-feature-settings: inherit;
+    font-variation-settings: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    opacity: 1;
+    margin-inline-end: 4px;
+  }
+  hr { color: inherit; }
+  abbr:where([title]) { text-decoration: underline dotted; }
+  small { font-size: 80%; }
+  sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
+  sub { bottom: -0.25em; }
+  sup { top: -0.5em; }
+  /* Keep emoji fallback after the authored font stack. */
+  html { font-family: var(--font-sans), "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }
   a {
     text-underline-offset: 4px;
   }
@@ -351,7 +277,7 @@ body {
  * <style>-inside-<div> HTML5 content-model violation flagged by
  * html-validate — see zudolab/zudo-doc#1505).
  *
- * Pins onto the `.hidden` baseline that Tailwind always generates so
+ * Pins onto the generated `.hidden` utility so
  * consumers wrapping <VersionSwitcher> in `<div class="hidden lg:block">`
  * still get the desktop override even when the content scanner did not
  * generate `.lg:block`. Mobile (<64rem) falls through to `.hidden`'s

package/dist/toc/mobile-toc.d.ts

@@ -1,13 +1,11 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { VNode } from "preact";
+import type { Child } from "@takazudo/zfb/zudo-react";
 import type { HeadingItem } from "./types.js";
 export interface MobileTocProps {
     headings: readonly HeadingItem[];
     title?: string;
 }
 /**
- * Collapsible TOC for narrow viewports (`xl:hidden`) — a Preact island
+ * Collapsible TOC for narrow viewports (`xl:hidden`) — a zudo-react island
  * component. Closed by default; tapping the header toggles, and tapping
  * any entry closes the panel after navigation.
  *
@@ -36,7 +34,7 @@ export interface MobileTocProps {
  * crawlers can still find the locale label in the static markup. When
  * headings are present the full interactive toggle UI is rendered.
  */
-export declare function MobileToc({ headings, title, }: MobileTocProps): VNode;
+export declare function MobileToc({ headings, title, }: MobileTocProps): Child;
 export declare namespace MobileToc {
     var displayName: string;
 }

package/dist/toc/mobile-toc.js

@@ -1,48 +1,51 @@
 "use client";
-import { jsx, jsxs } from "preact/jsx-runtime";
-import { useMemo, useState } from "preact/hooks";
+import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
+import { computed, signal } from "@takazudo/zfb/zudo-react";
 import { SmartBreak } from "../smart-break/index.js";
 import { cx } from "./cx.js";
 function MobileToc({
   headings,
   title = "On this page"
 }) {
-  const filtered = useMemo(
-    () => headings.filter((h) => h.depth >= 2 && h.depth <= 4),
-    [headings]
-  );
-  const [open, setOpen] = useState(false);
+  const filtered = headings.filter((h) => h.depth >= 2 && h.depth <= 4);
+  const open = signal(false);
+  const chevronClass = computed(() => cx(
+    "h-icon-sm w-icon-sm text-muted transition-transform duration-150",
+    open.value && "rotate-180"
+  ));
+  const itemsClass = computed(() => cx(
+    "border-t border-muted px-hsp-lg py-vsp-xs space-y-vsp-2xs",
+    !open.value && "hidden"
+  ));
   if (filtered.length === 0) {
-    return /* @__PURE__ */ jsx("div", { className: "hidden", "aria-hidden": "true", children: title });
+    return /* @__PURE__ */ jsx("div", { class: "hidden", "aria-hidden": "true", children: title });
   }
-  return /* @__PURE__ */ jsxs("div", { "data-zd-mobile-toc": true, className: "xl:hidden border border-muted mb-vsp-lg", children: [
+  return /* @__PURE__ */ jsxs("div", { "data-zd-mobile-toc": true, class: "xl:hidden border border-muted mb-vsp-lg", children: [
     /* @__PURE__ */ jsxs(
       "button",
       {
         type: "button",
-        onClick: () => setOpen((prev) => !prev),
+        "on:click": () => {
+          open.value = !open.value;
+        },
         "aria-expanded": open,
-        className: "flex w-full items-center justify-between px-hsp-lg py-vsp-xs text-small font-medium text-fg",
+        class: "flex w-full items-center justify-between px-hsp-lg py-vsp-xs text-small font-medium text-fg",
         children: [
           /* @__PURE__ */ jsx("span", { children: title }),
           /* @__PURE__ */ jsx(
             "svg",
             {
-              xmlns: "http://www.w3.org/2000/svg",
               "aria-hidden": "true",
-              className: cx(
-                "h-icon-sm w-icon-sm text-muted transition-transform duration-150",
-                open && "rotate-180"
-              ),
+              class: chevronClass,
               fill: "none",
               viewBox: "0 0 24 24",
               stroke: "currentColor",
-              strokeWidth: 2,
+              "stroke-width": 2,
               children: /* @__PURE__ */ jsx(
                 "path",
                 {
-                  strokeLinecap: "round",
-                  strokeLinejoin: "round",
+                  "stroke-linecap": "round",
+                  "stroke-linejoin": "round",
                   d: "M19 9l-7 7-7-7"
                 }
               )
@@ -54,15 +57,12 @@ function MobileToc({
     /* @__PURE__ */ jsx(
       "ul",
       {
-        className: cx(
-          "border-t border-muted px-hsp-lg py-vsp-xs space-y-vsp-2xs",
-          !open && "hidden"
-        ),
-        "aria-hidden": !open,
+        class: itemsClass,
+        "aria-hidden": computed(() => !open.value),
         children: filtered.map((heading, index) => /* @__PURE__ */ jsx(
           "li",
           {
-            className: cx(
+            class: cx(
               heading.depth === 3 && "ml-hsp-lg",
               heading.depth === 4 && "ml-hsp-2xl"
             ),
@@ -70,8 +70,10 @@ function MobileToc({
               "a",
               {
                 href: `#${heading.slug}`,
-                onClick: () => setOpen(false),
-                className: "block py-vsp-2xs text-small text-muted hover:text-fg hover:underline focus-visible:underline",
+                "on:click": () => {
+                  open.value = false;
+                },
+                class: "block py-vsp-2xs text-small text-muted hover:text-fg hover:underline focus-visible:underline",
                 children: /* @__PURE__ */ jsx(SmartBreak, { children: heading.text })
               }
             )

package/dist/toc/toc.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { VNode } from "preact";
+import { type Child } from "@takazudo/zfb/zudo-react";
 import type { HeadingItem } from "./types.js";
 export interface TocProps {
     headings: readonly HeadingItem[];
@@ -13,7 +12,7 @@ export interface TocProps {
     title?: string;
 }
 /**
- * Desktop right-rail Table of Contents — a Preact island component.
+ * Desktop right-rail Table of Contents — a zudo-react island component.
  *
  * Renders the `<nav aria-label="Table of contents">` directly. **The
  * caller is responsible for wrapping this in `<Island when="load">`**
@@ -50,7 +49,7 @@ export interface TocProps {
  * `<nav aria-label="Table of contents">` landmark provides the section
  * semantics for screen readers. Issue #1655 / T1.
  */
-export declare function Toc({ headings, title }: TocProps): VNode;
+export declare function Toc({ headings, title }: TocProps): Child;
 export declare namespace Toc {
     var displayName: string;
 }

package/dist/toc/toc.js

@@ -1,33 +1,36 @@
 "use client";
-import { jsx } from "preact/jsx-runtime";
-import { useMemo } from "preact/hooks";
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
+import { computed, getScope } from "@takazudo/zfb/zudo-react";
 import { useActiveHeading } from "./use-active-heading.js";
 import { SmartBreak } from "../smart-break/index.js";
 import { cx } from "./cx.js";
 function Toc({ headings, title = "On this page" }) {
-  const filtered = useMemo(
-    () => headings.filter((h) => h.depth >= 2 && h.depth <= 4),
-    [headings]
-  );
-  const { activeId, activate } = useActiveHeading(filtered);
+  const filtered = headings.filter((h) => h.depth >= 2 && h.depth <= 4);
+  const { activeId, activate } = useActiveHeading(getScope(), filtered);
   return /* @__PURE__ */ jsx(
     "nav",
     {
       "aria-label": "Table of contents",
       "data-zd-toc": true,
-      className: cx(
+      class: cx(
         "hidden xl:flex flex-col",
         "w-[280px] shrink-0",
         "sticky top-[3.5rem] self-start z-sidebar",
         "pt-vsp-xl lg:pt-vsp-2xl",
-        "h-[calc(100vh-3.5rem)]"
+        "h-[calc(100vh_-_3.5rem)]"
       ),
-      children: filtered.length > 0 && /* @__PURE__ */ jsx("ul", { className: "border-l border-muted pl-hsp-lg overflow-y-auto", children: filtered.map((heading, index) => {
-        const isActive = heading.slug === activeId;
+      children: filtered.length > 0 && /* @__PURE__ */ jsx("ul", { class: "border-l border-muted pl-hsp-lg overflow-y-auto", children: filtered.map((heading, index) => {
+        const isActive = computed(() => heading.slug === activeId.value);
+        const linkClass = computed(
+          () => cx(
+            "block py-vsp-2xs text-small leading-snug transition-colors duration-0",
+            isActive.value ? "bg-fg text-bg font-medium" : "text-muted hover:underline focus:underline"
+          )
+        );
         return /* @__PURE__ */ jsx(
           "li",
           {
-            className: cx(
+            class: cx(
               heading.depth === 3 && "ml-hsp-lg",
               heading.depth === 4 && "ml-hsp-2xl"
             ),
@@ -35,12 +38,9 @@ function Toc({ headings, title = "On this page" }) {
               "a",
               {
                 href: `#${heading.slug}`,
-                onClick: () => activate(heading.slug),
-                "aria-current": isActive ? "true" : void 0,
-                className: cx(
-                  "block py-vsp-2xs text-small leading-snug transition-colors",
-                  isActive ? "bg-fg text-bg font-medium" : "text-muted hover:underline focus:underline"
-                ),
+                "on:click": () => activate(heading.slug),
+                "aria-current": computed(() => isActive.value ? "true" : void 0),
+                class: linkClass,
                 children: /* @__PURE__ */ jsx(SmartBreak, { children: heading.text })
               }
             )

package/dist/toc/use-active-heading.d.ts

@@ -1,7 +1,8 @@
+import type { Scope, Signal } from "@takazudo/zfb/zudo-react";
 import type { HeadingItem } from "./types.js";
 /**
  * Pure helper that picks the active heading id given the heading slug
- * order and a slug→element map. Extracted from the hook so it is unit-
+ * order and a slug→element map. Extracted from the setup helper so it is unit-
  * testable without DOM event plumbing.
  *
  * Algorithm: find the first heading whose top is at or below the
@@ -13,15 +14,15 @@ import type { HeadingItem } from "./types.js";
  */
 export declare function getActiveHeadingId(headingIds: readonly string[], elementMap: ReadonlyMap<string, HTMLElement>, viewportHeight: number): string | null;
 export interface UseActiveHeadingResult {
-    activeId: string | null;
+    activeId: Signal<string | null>;
     activate: (id: string) => void;
 }
 /**
- * Scroll-spy hook. Tracks which heading slug should be highlighted
+ * Scroll-spy setup helper. Tracks which heading slug should be highlighted
  * based on the current scroll position. Provides an `activate(id)`
  * imperatively-callable helper used by click handlers — sets the
  * active id immediately and suppresses the scroll-driven update until
  * the smooth-scroll completes (`scrollend`, with a timeout fallback
  * for older Safari).
  */
-export declare function useActiveHeading(headings: readonly HeadingItem[]): UseActiveHeadingResult;
+export declare function useActiveHeading(scope: Scope, headings: readonly HeadingItem[]): UseActiveHeadingResult;

package/dist/toc/use-active-heading.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import { signal } from "@takazudo/zfb/zudo-react";
 const SCROLL_MARGIN_TOP = 80;
 const DEBOUNCE_MS = 200;
 function getActiveHeadingId(headingIds, elementMap, viewportHeight) {
@@ -35,41 +35,37 @@ function getActiveHeadingId(headingIds, elementMap, viewportHeight) {
   }
   return headingIds[firstVisibleIndex - 1] ?? null;
 }
-function useActiveHeading(headings) {
-  const [activeId, setActiveId] = useState(null);
-  const headingIdsRef = useRef([]);
-  const elementMapRef = useRef(/* @__PURE__ */ new Map());
-  const suppressedRef = useRef(false);
-  const activate = useCallback((id) => {
-    setActiveId(id);
-    suppressedRef.current = true;
-    setTimeout(() => {
-      suppressedRef.current = false;
-    }, 2e3);
-  }, []);
-  useEffect(() => {
-    const ids = headings.map((h) => h.slug);
-    headingIdsRef.current = ids;
+function useActiveHeading(scope, headings) {
+  const activeId = signal(null);
+  const headingIds = headings.map((heading) => heading.slug);
+  let activateInScope = () => {
+  };
+  const activate = (id) => activateInScope(id);
+  scope.onActivate(() => {
+    let suppressed = false;
+    let timerId = null;
+    let fallbackTimerId = null;
+    let suppressionTimerId = null;
+    activateInScope = (id) => {
+      activeId.value = id;
+      suppressed = true;
+      if (suppressionTimerId !== null) clearTimeout(suppressionTimerId);
+      suppressionTimerId = setTimeout(() => {
+        suppressionTimerId = null;
+        suppressed = false;
+      }, 2e3);
+    };
     const map = /* @__PURE__ */ new Map();
-    for (const id of ids) {
+    for (const id of headingIds) {
       const el = document.getElementById(id);
       if (el) map.set(id, el);
     }
-    elementMapRef.current = map;
-    let timerId = null;
     function update() {
       timerId = null;
-      setActiveId(
-        getActiveHeadingId(
-          headingIdsRef.current,
-          elementMapRef.current,
-          window.innerHeight
-        )
-      );
+      activeId.value = getActiveHeadingId(headingIds, map, window.innerHeight);
     }
-    let fallbackTimerId = null;
     function onScroll() {
-      if (suppressedRef.current) {
+      if (suppressed) {
         if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
         fallbackTimerId = setTimeout(onScrollEnd, 1500);
         return;
@@ -78,7 +74,11 @@ function useActiveHeading(headings) {
       timerId = setTimeout(update, DEBOUNCE_MS);
     }
     function onScrollEnd() {
-      suppressedRef.current = false;
+      suppressed = false;
+      if (suppressionTimerId !== null) {
+        clearTimeout(suppressionTimerId);
+        suppressionTimerId = null;
+      }
       if (fallbackTimerId !== null) {
         clearTimeout(fallbackTimerId);
         fallbackTimerId = null;
@@ -91,13 +91,19 @@ function useActiveHeading(headings) {
     window.addEventListener("resize", onScroll, { passive: true });
     window.addEventListener("scrollend", onScrollEnd, { passive: true });
     return () => {
+      activateInScope = () => {
+      };
       window.removeEventListener("scroll", onScroll);
       window.removeEventListener("resize", onScroll);
       window.removeEventListener("scrollend", onScrollEnd);
       if (timerId !== null) clearTimeout(timerId);
+      timerId = null;
       if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
+      fallbackTimerId = null;
+      if (suppressionTimerId !== null) clearTimeout(suppressionTimerId);
+      suppressionTimerId = null;
     };
-  }, [headings]);
+  });
   return { activeId, activate };
 }
 export {

package/dist/toc-prepaint/index.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 export interface TocPrepaintProps {
     /**
      * Whether the page actually renders the package's own default TOC (i.e.

package/dist/toc-prepaint/index.js

@@ -1,9 +1,7 @@
-import { Fragment, jsx } from "preact/jsx-runtime";
+import { Fragment, jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { Island } from "@takazudo/zfb";
-import {
-  DesktopTocToggle,
-  TOC_STORAGE_KEY
-} from "../desktop-toc-toggle-island/index.js";
+import { DesktopTocToggle } from "../desktop-toc-toggle-island/index.js";
+import { TOC_STORAGE_KEY } from "../desktop-toc-toggle-island/storage.js";
 function tocPrepaintActive(settings, shouldRenderDefaultToc) {
   return Boolean(settings.tocToggle) && Boolean(shouldRenderDefaultToc);
 }
@@ -18,7 +16,7 @@ function createTocVisibilityPrepaint(settings) {
     return /* @__PURE__ */ jsx(
       "script",
       {
-        dangerouslySetInnerHTML: { __html: TOC_VISIBILITY_PREPAINT_SCRIPT }
+        rawHtml: TOC_VISIBILITY_PREPAINT_SCRIPT
       }
     );
   }

package/dist/transitions/nested-island-props-refresh.d.ts

@@ -1,21 +1,8 @@
-interface NestedIslandPropsRefreshOptions {
+interface Options {
     document: Document;
-    /** Explicit error seam for hosts/tests; omitted errors surface in a microtask. */
     reportError?: (error: unknown) => void;
 }
-/**
- * Install the before-swap props-refresh listener on a document.
- *
- * This low-level entrypoint owns an explicit cleanup for focused tests and
- * non-singleton hosts. Browser modules use the durable, duplicate-safe
- * `ensureNestedIslandPropsRefresh` wrapper below instead.
- */
-export declare function installNestedIslandPropsRefresh({ document, reportError, }: NestedIslandPropsRefreshOptions): () => void;
-/**
- * Install exactly one document-lifetime controller for a browser document.
- * Repeated calls from component renders or duplicate boot paths are no-ops.
- */
-export declare function ensureNestedIslandPropsRefresh(options?: NestedIslandPropsRefreshOptions): void;
-/** Test/HMR teardown for a controller installed through the singleton wrapper. */
+export declare function installNestedIslandPropsRefresh({ document, reportError }: Options): () => void;
+export declare function ensureNestedIslandPropsRefresh(options?: Options): void;
 export declare function disposeNestedIslandPropsRefresh(document: Document): void;
 export {};