@takazudo/zudo-doc 5.12.0 → 5.13.0

package/dist/theme-cli/registry.js

@@ -1,6 +1,4 @@
-import {
-  loadThemePackRegistry
-} from "../theme-packs-registry/index.js";
+import { loadThemePackRegistry } from "../theme-packs-registry/load-registry.js";
 function defaultThemePacksDir() {
   return new URL("../theme-packs/", import.meta.url);
 }

package/dist/theme-pack-switcher/index.d.ts

@@ -18,6 +18,8 @@ export interface ThemePackSwitcherProps {
     /** Base prefix WITH trailing slash (`ctx.withBase("/")`) — forwarded to
      *  the browse-all dialog for its `{base}theme-packs/index.json` fetch. */
     base: string;
+    /** Keep launcher activation pending until the first successful mount. @default true */
+    pendingUntilHydrated?: boolean;
 }
 /** Props of the browse-all dialog mounted through {@link ThemePackDialogSlot}
  *  — the #2825 contract. The dialog fetches `{base}theme-packs/index.json`
@@ -43,7 +45,7 @@ export type ThemePackDialogComponent = (props: ThemePackDialogProps) => JSX.Elem
  * `Island({ when: "load" })` — see
  * `../doc-body-end-islands/theme-pack-switcher-island.tsx`.
  */
-export declare function ThemePackSwitcher({ active, order, base }: ThemePackSwitcherProps): JSX.Element;
+export declare function ThemePackSwitcher({ active, order, base, pendingUntilHydrated, }: ThemePackSwitcherProps): JSX.Element;
 export declare namespace ThemePackSwitcher {
     var displayName: string;
 }

package/dist/theme-pack-switcher/index.js

@@ -2,6 +2,7 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { useEffect, useRef, useState } from "preact/hooks";
 import { ChevronLeft, ChevronRight, Close } from "../icons/index.js";
+import { useHydrationPending } from "../hydration-pending.js";
 import { ThemePackDialog } from "../theme-pack-dialog/index.js";
 import { applyThemePack } from "./theme-pack-sync.js";
 import {
@@ -61,7 +62,13 @@ function PaletteIcon({ className }) {
 }
 const CONTROL_BUTTON_CLASS = "flex items-center gap-hsp-xs rounded border border-muted bg-bg px-hsp-md py-hsp-2xs text-caption text-fg transition-colors hover:border-accent focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 disabled:opacity-50 disabled:pointer-events-none";
 const ICON_BUTTON_CLASS = "flex items-center justify-center rounded p-hsp-2xs text-muted transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 disabled:opacity-50 disabled:pointer-events-none";
-function ThemePackSwitcher({ active, order, base }) {
+function ThemePackSwitcher({
+  active,
+  order,
+  base,
+  pendingUntilHydrated = true
+}) {
+  const pending = useHydrationPending(pendingUntilHydrated);
   const [open, setOpen] = useState(false);
   const [dialogOpen, setDialogOpen] = useState(false);
   const [activeSlug, setActiveSlug] = useState(active);
@@ -178,9 +185,14 @@ function ThemePackSwitcher({ active, order, base }) {
             "aria-haspopup": "dialog",
             "aria-expanded": open,
             "aria-label": "Theme pack switcher",
+            "aria-disabled": pending ? "true" : void 0,
             title: "Theme packs",
             "data-switcher-launcher": true,
-            onClick: () => setOpen(!open),
+            "data-zd-pending": pending ? "" : void 0,
+            onClick: () => {
+              if (pending) return;
+              setOpen(!open);
+            },
             class: "flex h-[2.5rem] w-[2.5rem] items-center justify-center rounded-full border border-muted bg-surface text-fg shadow-lg transition-colors hover:text-accent focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2",
             children: /* @__PURE__ */ jsx(PaletteIcon, { className: "h-icon-md w-icon-md" })
           }

package/dist/theme-packs-registry/build-registry.d.ts

@@ -0,0 +1,41 @@
+import { type ResolveEnabledPacksSettings } from "./resolve-enabled-packs.js";
+import type { ThemePackMeta, ThemePackRegistry } from "../route-context-payload/types.js";
+/** Contract version for the `./theme-packs-registry` public surface. */
+export declare const schemaVersion = 1;
+/** One entry in the browser-facing catalog v2 manifest. */
+export interface ThemePackCatalogEntry {
+    /** The pack directory slug. */
+    slug: string;
+    /** The schema-validated metadata for this pack. */
+    meta: ThemePackMeta;
+    /** Whether the pack ships a CSS stylesheet. */
+    hasStylesheet: boolean;
+}
+/**
+ * The complete catalog manifest accepted by {@link buildThemePackRegistry}.
+ *
+ * This is intentionally a whole-manifest parameter rather than a bare
+ * `packs` array: the catalog schema version is part of the input contract and
+ * must be checked before its entries are interpreted.
+ */
+export interface ThemePacksCatalogManifest {
+    /** Catalog schema version, distinct from each meta.json schema version. */
+    schemaVersion: 2;
+    packs: ThemePackCatalogEntry[];
+}
+/** The `{ themePack, themePacks }` settings projection used by the resolver. */
+export type ThemePackSettingsProjection = ResolveEnabledPacksSettings;
+/** Alias emphasizing that this is the registry builder's settings input. */
+export type ThemePackRegistrySettings = ThemePackSettingsProjection;
+/**
+ * Build the resolved, enabled, ordered theme-pack registry for a browser
+ * consumer.
+ *
+ * The input is the complete catalog v2 manifest and the settings projection
+ * `{ themePack, themePacks }`. Catalog schema versions other than `2` are
+ * rejected with an error naming the received value. Once the boundary is
+ * validated, {@link resolveEnabledPacks} remains the single source of truth
+ * for default-first/alphabetical ordering and loud duplicate, unknown, and
+ * excluded-active-slug failures.
+ */
+export declare function buildThemePackRegistry(catalog: ThemePacksCatalogManifest, settings: ThemePackSettingsProjection): ThemePackRegistry;

package/dist/theme-packs-registry/build-registry.js

@@ -0,0 +1,62 @@
+import { resolveEnabledPacks } from "./resolve-enabled-packs.js";
+const schemaVersion = 1;
+function describeCatalogValue(value) {
+  if (value === void 0) return "undefined";
+  try {
+    const json = JSON.stringify(value);
+    return json === void 0 ? String(value) : json;
+  } catch {
+    return String(value);
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateCatalogManifest(value) {
+  if (!isRecord(value)) {
+    throw new TypeError(
+      `@takazudo/zudo-doc/theme-packs-registry: expected a catalog manifest object with schemaVersion 2; got ${describeCatalogValue(value)}.`
+    );
+  }
+  if (value.schemaVersion !== 2) {
+    throw new Error(
+      `@takazudo/zudo-doc/theme-packs-registry: unsupported catalog schemaVersion ${describeCatalogValue(value.schemaVersion)}; expected 2.`
+    );
+  }
+  if (!Array.isArray(value.packs)) {
+    throw new TypeError(
+      `@takazudo/zudo-doc/theme-packs-registry: catalog.packs must be an array; got ${describeCatalogValue(value.packs)}.`
+    );
+  }
+  for (const [index, entry] of value.packs.entries()) {
+    if (!isRecord(entry)) {
+      throw new TypeError(
+        `@takazudo/zudo-doc/theme-packs-registry: catalog.packs[${index}] must be an object; got ${describeCatalogValue(entry)}.`
+      );
+    }
+    if (typeof entry.slug !== "string") {
+      throw new TypeError(
+        `@takazudo/zudo-doc/theme-packs-registry: catalog.packs[${index}].slug must be a string; got ${describeCatalogValue(entry.slug)}.`
+      );
+    }
+    if (!isRecord(entry.meta)) {
+      throw new TypeError(
+        `@takazudo/zudo-doc/theme-packs-registry: catalog.packs[${index}].meta must be an object; got ${describeCatalogValue(entry.meta)}.`
+      );
+    }
+    if (typeof entry.hasStylesheet !== "boolean") {
+      throw new TypeError(
+        `@takazudo/zudo-doc/theme-packs-registry: catalog.packs[${index}].hasStylesheet must be a boolean; got ${describeCatalogValue(entry.hasStylesheet)}.`
+      );
+    }
+  }
+  return value;
+}
+function buildThemePackRegistry(catalog, settings) {
+  const manifest = validateCatalogManifest(catalog);
+  return resolveEnabledPacks(manifest.packs, settings);
+}
+export {
+  buildThemePackRegistry,
+  schemaVersion
+};

package/dist/theme-packs-registry/index.d.ts

@@ -1,5 +1,6 @@
 export { THEME_PACK_SLUG_RE, DEFAULT_THEME_PACK_SLUG, themePackMetaSchema, type ThemePackMeta, type ThemePackSwatches, } from "./meta-schema.js";
 export { KNOWN_THEME_PACK_TOKEN_NAMES, COMMERCIAL_FONT_DENYLIST, THEME_PACK_SOFT_BUDGET_BYTES, } from "./token-manifest.js";
 export { validateThemePack, type ThemePackValidationInput, type ThemePackValidationIssue, type ThemePackValidationResult, type ThemePackValidationSeverity, } from "./validator.js";
-export { loadThemePackRegistry, type ThemePackRegistry, type ThemePackRegistryEntry, } from "./load-registry.js";
+export type { ThemePackRegistry, ThemePackRegistryEntry } from "./types.js";
 export { resolveEnabledPacks, type ResolveEnabledPacksSettings, } from "./resolve-enabled-packs.js";
+export { buildThemePackRegistry, schemaVersion, type ThemePackCatalogEntry, type ThemePackRegistrySettings, type ThemePackSettingsProjection, type ThemePacksCatalogManifest, } from "./build-registry.js";

package/dist/theme-packs-registry/index.js

@@ -11,20 +11,22 @@ import {
 import {
   validateThemePack
 } from "./validator.js";
-import {
-  loadThemePackRegistry
-} from "./load-registry.js";
 import {
   resolveEnabledPacks
 } from "./resolve-enabled-packs.js";
+import {
+  buildThemePackRegistry,
+  schemaVersion
+} from "./build-registry.js";
 export {
   COMMERCIAL_FONT_DENYLIST,
   DEFAULT_THEME_PACK_SLUG,
   KNOWN_THEME_PACK_TOKEN_NAMES,
   THEME_PACK_SLUG_RE,
   THEME_PACK_SOFT_BUDGET_BYTES,
-  loadThemePackRegistry,
+  buildThemePackRegistry,
   resolveEnabledPacks,
+  schemaVersion,
   themePackMetaSchema,
   validateThemePack
 };

package/dist/theme-packs-registry/load-registry.d.ts

@@ -1,16 +1,5 @@
-import type { ThemePackMeta } from "./meta-schema.js";
-/** One entry in the aggregated, canonically-ordered bundled registry. */
-export interface ThemePackRegistryEntry {
-    /** The pack's directory name (equals `meta.slug`). */
-    slug: string;
-    /** The pack's schema-validated `meta.json`. */
-    meta: ThemePackMeta;
-    /** Whether this pack ships a `pack.css` (always `false` for `"default"`). */
-    hasStylesheet: boolean;
-}
-/** The full bundled registry, or a subset of it (after `resolveEnabledPacks`)
- *  — an ordered array; order carries meaning (canonical / switcher order). */
-export type ThemePackRegistry = ThemePackRegistryEntry[];
+import type { ThemePackRegistry } from "../route-context-payload/types.js";
+export type { ThemePackRegistry, ThemePackRegistryEntry, } from "../route-context-payload/types.js";
 /**
  * Scan `dir` (a `theme-packs/` directory — `src/theme-packs/` in the
  * workspace, `dist/theme-packs/` once shipped) for per-slug pack directories,

package/dist/theme-packs-registry/meta-schema.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export type { ThemePackMeta, ThemePackSwatches } from "../route-context-payload/types.js";
 /** `[a-z0-9][a-z0-9-]*` — a pack's slug MUST equal its directory name
  *  (Decision 6.7 "slug regex + dir-name parity"). */
 export declare const THEME_PACK_SLUG_RE: RegExp;
@@ -6,20 +7,6 @@ export declare const THEME_PACK_SLUG_RE: RegExp;
  *  ONLY (no `pack.css`); the runtime never inserts a stylesheet link for it
  *  (ADR Decision 1, "The reserved `default` pack"). */
 export declare const DEFAULT_THEME_PACK_SLUG = "default";
-declare const themePackSwatchesSchema: z.ZodObject<{
-    bg: z.ZodString;
-    fg: z.ZodString;
-    accent: z.ZodString;
-    syntax: z.ZodObject<{
-        keyword: z.ZodString;
-        string: z.ZodString;
-        comment: z.ZodString;
-        callable: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-/** Preview swatches for the dialog grid — RESOLVED plain CSS colors, one set
- *  per mode. See {@link themePackMetaSchema}'s `preview` field. */
-export type ThemePackSwatches = z.infer<typeof themePackSwatchesSchema>;
 export declare const themePackMetaSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     slug: z.ZodString;
@@ -61,10 +48,3 @@ export declare const themePackMetaSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>;
 }, z.core.$strip>;
-/**
- * A pack's `meta.json`, schema-validated (ADR Decision 1). `mode` is a
- * designed-primary badge only — every pack still defines BOTH modes via
- * `light-dark()` in `pack.css`.
- */
-export type ThemePackMeta = z.infer<typeof themePackMetaSchema>;
-export {};

package/dist/theme-packs-registry/resolve-enabled-packs.d.ts

@@ -1,4 +1,4 @@
-import type { ThemePackRegistry } from "./load-registry.js";
+import type { ThemePackRegistry } from "./types.js";
 /** The subset of settings this resolver reads. */
 export interface ResolveEnabledPacksSettings {
     /** Active pack slug — must end up a member of the resolved list. */

package/dist/theme-packs-registry/types.d.ts

@@ -0,0 +1 @@
+export type { ThemePackRegistry, ThemePackRegistryEntry, } from "../route-context-payload/types.js";

package/dist/theme-toggle/index.d.ts

@@ -1,8 +1,10 @@
 import { type ColorSchemeMode } from "./color-scheme-sync.js";
 export interface ThemeToggleProps {
     defaultMode?: ColorSchemeMode;
+    /** Keep activation pending until the first successful mount. @default true */
+    pendingUntilHydrated?: boolean;
 }
-export declare function ThemeToggle({ defaultMode, }: ThemeToggleProps): import("preact").JSX.Element;
+export declare function ThemeToggle({ defaultMode, pendingUntilHydrated, }: ThemeToggleProps): import("preact").JSX.Element;
 export declare namespace ThemeToggle {
     var displayName: string;
 }

package/dist/theme-toggle/index.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { useState, useEffect } from "preact/hooks";
+import { useHydrationPending } from "../hydration-pending.js";
 import {
   applyColorScheme,
   readColorSchemeFromDom,
@@ -53,8 +54,10 @@ function MoonIcon() {
   );
 }
 function ThemeToggle({
-  defaultMode = "dark"
+  defaultMode = "dark",
+  pendingUntilHydrated = true
 }) {
+  const pending = useHydrationPending(pendingUntilHydrated);
   const [mode, setMode] = useState(defaultMode);
   useEffect(() => {
     const sync = () => setMode(readColorSchemeFromDom(defaultMode));
@@ -62,6 +65,7 @@ function ThemeToggle({
     return subscribeColorSchemeChanged(sync);
   }, []);
   function toggle() {
+    if (pending) return;
     const next = mode === "dark" ? "light" : "dark";
     setMode(next);
     applyColorScheme(next);
@@ -72,6 +76,8 @@ function ThemeToggle({
     {
       onClick: toggle,
       "aria-label": `Switch to ${nextMode} mode`,
+      "aria-disabled": pending ? "true" : void 0,
+      "data-zd-pending": pending ? "" : void 0,
       className: "text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2",
       children: mode === "dark" ? /* @__PURE__ */ jsx(SunIcon, {}) : /* @__PURE__ */ jsx(MoonIcon, {})
     }

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

@@ -1,5 +1,7 @@
 interface NestedIslandPropsRefreshOptions {
     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.
@@ -8,7 +10,7 @@ interface NestedIslandPropsRefreshOptions {
  * non-singleton hosts. Browser modules use the durable, duplicate-safe
  * `ensureNestedIslandPropsRefresh` wrapper below instead.
  */
-export declare function installNestedIslandPropsRefresh({ document, }: NestedIslandPropsRefreshOptions): () => void;
+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.

package/dist/transitions/nested-island-props-refresh.js

@@ -7,12 +7,47 @@ const ISLAND_REMOUNT_ATTR = "data-zfb-island-remount";
 const DOCUMENT_NODE = 9;
 const installedControllers = /* @__PURE__ */ new WeakMap();
 function installNestedIslandPropsRefresh({
-  document: document2
+  document: document2,
+  reportError
 }) {
   const onBeforeSwap = (event) => {
-    const incoming = event.newDocument;
-    if (!isDocument(incoming) || incoming === document2) return;
-    refreshNestedIslandProps(document2, incoming);
+    const swapEvent = event;
+    const incoming = swapEvent.newDocument;
+    if (!isDocument(incoming) || incoming === document2 || typeof swapEvent.swap !== "function") {
+      return;
+    }
+    const capturedSwap = swapEvent.swap;
+    const plan = buildNestedIslandPropsMutationPlan(document2, incoming);
+    let commitStarted = false;
+    let commitOutcome;
+    const composedSwap = function(...args) {
+      if (commitStarted) {
+        if (!commitOutcome) return void 0;
+        if (!commitOutcome.ok) throw commitOutcome.error;
+        return commitOutcome.value;
+      }
+      commitStarted = true;
+      try {
+        const value = commitMutationPlanAndDelegate(
+          plan,
+          capturedSwap,
+          this,
+          args,
+          reportError
+        );
+        commitOutcome = { ok: true, value };
+        return value;
+      } catch (error) {
+        commitOutcome = { ok: false, error };
+        throw error;
+      }
+    };
+    try {
+      swapEvent.swap = composedSwap;
+    } catch {
+      return;
+    }
+    if (swapEvent.swap !== composedSwap) return;
   };
   document2.addEventListener(BEFORE_SWAP_EVENT, onBeforeSwap);
   return () => document2.removeEventListener(BEFORE_SWAP_EVENT, onBeforeSwap);
@@ -29,9 +64,10 @@ function disposeNestedIslandPropsRefresh(document2) {
   installedControllers.get(document2)?.();
   installedControllers.delete(document2);
 }
-function refreshNestedIslandProps(liveDocument, incomingDocument) {
+function buildNestedIslandPropsMutationPlan(liveDocument, incomingDocument) {
+  const plan = [];
   const liveRoots = collectRefreshableRoots(liveDocument);
-  if (liveRoots.size === 0) return;
+  if (liveRoots.size === 0) return Object.freeze(plan);
   const incomingRoots = collectRefreshableRoots(incomingDocument);
   for (const [persistKey, liveRoot] of liveRoots) {
     const incomingRoot = incomingRoots.get(persistKey);
@@ -41,9 +77,31 @@ function refreshNestedIslandProps(liveDocument, incomingDocument) {
     for (const [name, liveIsland] of collectUniqueOwnedIslands(liveRoot, true)) {
       const incomingIsland = incomingIslands.get(name);
       if (!incomingIsland) continue;
-      applyProps(liveIsland, incomingIsland);
+      const incomingProps = incomingIsland.getAttribute(PROPS_ATTR);
+      if (incomingProps === liveIsland.getAttribute(PROPS_ATTR)) continue;
+      plan.push(Object.freeze({ liveIsland, incomingProps }));
+    }
+  }
+  return Object.freeze(plan);
+}
+function commitMutationPlanAndDelegate(plan, delegate, receiver, args, reportError) {
+  const helperErrors = [];
+  for (const mutation of plan) {
+    try {
+      applyPropsMutation(mutation);
+    } catch (error) {
+      helperErrors.push(error);
     }
   }
+  let delegateResult;
+  try {
+    delegateResult = delegate.apply(receiver, args);
+  } catch (delegateError) {
+    reportRefreshErrors(helperErrors, reportError);
+    throw delegateError;
+  }
+  reportRefreshErrors(helperErrors, reportError);
+  return delegateResult;
 }
 function collectRefreshableRoots(doc) {
   const roots = indexUniquely(
@@ -83,17 +141,35 @@ function indexUniquely(elements, attribute) {
   for (const value of duplicated) byValue.delete(value);
   return byValue;
 }
-function applyProps(liveIsland, incomingIsland) {
-  const incoming = incomingIsland.getAttribute(PROPS_ATTR);
-  const current = liveIsland.getAttribute(PROPS_ATTR);
-  if (incoming === current) return;
-  if (incoming === null) {
+function applyPropsMutation({
+  liveIsland,
+  incomingProps
+}) {
+  if (incomingProps === null) {
     liveIsland.removeAttribute(PROPS_ATTR);
   } else {
-    liveIsland.setAttribute(PROPS_ATTR, incoming);
+    liveIsland.setAttribute(PROPS_ATTR, incomingProps);
   }
   liveIsland.setAttribute(ISLAND_REMOUNT_ATTR, "");
 }
+function reportRefreshErrors(errors, reportError) {
+  if (errors.length === 0) return;
+  const error = errors.length === 1 ? errors[0] : new AggregateError(errors, "Nested-island props refresh failed");
+  if (reportError) {
+    try {
+      reportError(error);
+    } catch (reporterError) {
+      surfaceAsynchronously(reporterError);
+    }
+    return;
+  }
+  surfaceAsynchronously(error);
+}
+function surfaceAsynchronously(error) {
+  queueMicrotask(() => {
+    throw error;
+  });
+}
 function isDocument(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;

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

@@ -187,7 +187,9 @@ function SidebarFooter({ links, themeDefaultMode }: { links?: SidebarLocaleLink[
   return (
     // pb-[50vh] provides scroll room so the footer doesn't sit at the very bottom of the viewport
     <div className="lg:hidden flex items-center gap-hsp-md border-t border-muted px-hsp-sm py-vsp-xs pb-[50vh] text-small">
-      {themeDefaultMode && <ThemeToggle defaultMode={themeDefaultMode} />}
+      {themeDefaultMode && (
+        <ThemeToggle defaultMode={themeDefaultMode} pendingUntilHydrated={true} />
+      )}
       {links && links.map((link, i) => (
         <span key={link.href} className="flex items-center gap-hsp-xs">
           {i > 0 && <span className="text-muted">/</span>}

package/eject/theme-toggle/hydration-pending.ts

@@ -0,0 +1,13 @@
+import { useEffect, useState } from "preact/hooks";
+
+/**
+ * Keep an interactive control pending until its first successful client mount.
+ * Initializing from `enabled` preserves server/client-first-render parity.
+ */
+export function useHydrationPending(enabled: boolean): boolean {
+  const [pending, setPending] = useState(enabled);
+
+  useEffect(() => setPending(false), []);
+
+  return pending;
+}

package/eject/theme-toggle/index.tsx

@@ -14,6 +14,7 @@
 // not alias "react" to "preact/compat", so importing from "react" here
 // would fail to resolve.
 import { useState, useEffect } from "preact/hooks";
+import { useHydrationPending } from "./hydration-pending.js";
 import {
   applyColorScheme,
   readColorSchemeFromDom,
@@ -69,6 +70,8 @@ function MoonIcon() {
 
 export interface ThemeToggleProps {
   defaultMode?: ColorSchemeMode;
+  /** Keep activation pending until the first successful mount. @default true */
+  pendingUntilHydrated?: boolean;
 }
 
 // NAMED export (not default) on purpose: tsup compiles a default export
@@ -79,7 +82,9 @@ export interface ThemeToggleProps {
 // the package's MobileToc island).
 export function ThemeToggle({
   defaultMode = "dark",
+  pendingUntilHydrated = true,
 }: ThemeToggleProps) {
+  const pending = useHydrationPending(pendingUntilHydrated);
   // 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);
@@ -94,6 +99,7 @@ export function ThemeToggle({
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
   function toggle() {
+    if (pending) return;
     const next = mode === "dark" ? "light" : "dark";
     setMode(next);
     applyColorScheme(next);
@@ -105,6 +111,8 @@ export function ThemeToggle({
     <button
       onClick={toggle}
       aria-label={`Switch to ${nextMode} mode`}
+      aria-disabled={pending ? "true" : undefined}
+      data-zd-pending={pending ? "" : undefined}
       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 />}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "5.12.0",
+  "version": "5.13.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",
@@ -247,11 +247,16 @@
       "types": "./dist/site-schema/index.d.ts",
       "default": "./dist/site-schema/index.js"
     },
+    "./theme-packs-registry": {
+      "types": "./dist/theme-packs-registry/index.d.ts",
+      "default": "./dist/theme-packs-registry/index.js"
+    },
     "./theme.css": "./dist/theme.css",
     "./safelist.css": "./dist/safelist.css",
     "./content.css": "./dist/content.css",
     "./page-loading.css": "./dist/page-loading.css",
     "./features.css": "./dist/features.css",
+    "./compiled.css": "./dist/compiled.css",
     "./theme-packs/*": "./dist/theme-packs/*",
     "./routes-src/*": "./routes-src/*",
     "./tsconfig.base.json": "./tsconfig.base.json",
@@ -612,6 +617,10 @@
     "./note-tray-model": {
       "types": "./dist/note-tray-model/index.d.ts",
       "default": "./dist/note-tray-model/index.js"
+    },
+    "./route-context-payload": {
+      "types": "./dist/route-context-payload/index.d.ts",
+      "default": "./dist/route-context-payload/index.js"
     }
   },
   "bin": {
@@ -634,10 +643,10 @@
   ],
   "peerDependencies": {
     "@takazudo/zdtp": "^0.4.12",
-    "@takazudo/zfb": "^2.10.0",
-    "@takazudo/zfb-md-wasm": "^2.10.0",
-    "@takazudo/zfb-runtime": "^2.10.0",
-    "@takazudo/zudo-doc-history-server": "^5.5.3",
+    "@takazudo/zfb": "^2.12.0",
+    "@takazudo/zfb-md-wasm": "^2.12.0",
+    "@takazudo/zfb-runtime": "^2.12.0",
+    "@takazudo/zudo-doc-history-server": "^5.12.1",
     "diff": "^8.0.0",
     "katex": "^0.16.0",
     "preact": "^10.29.1",
@@ -669,18 +678,16 @@
     "picocolors": "^1.1.1",
     "pluralize": "^8.0.0",
     "smol-toml": "^1.8.0",
-    "string-similarity": "^4.0.4",
     "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@takazudo/zfb": "2.10.0",
-    "@takazudo/zfb-md-wasm": "2.10.0",
-    "@takazudo/zfb-runtime": "2.10.0",
+    "@takazudo/zfb": "2.12.0",
+    "@takazudo/zfb-md-wasm": "2.12.0",
+    "@takazudo/zfb-runtime": "2.12.0",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
     "@types/pluralize": "^0.0.33",
-    "@types/string-similarity": "^4.0.2",
     "happy-dom": "^20.10.6",
     "npm-run-all2": "^7.0.2",
     "preact": "^10.29.1",
@@ -689,7 +696,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "5.12.0"
+    "@takazudo/zudo-doc-history-server": "5.13.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",
@@ -701,7 +708,7 @@
     "dev:js": "tsup --watch",
     "dev:dts": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "// check:prepack-contract": "check:search-widget-drift and check:nav-overflow-drift run here (not just b4push/CI) because `prepare` regenerates BOTH frozen literals unconditionally — without a prepack gate, packing from a tree where a source changed but a literal was never re-committed would silently publish new script bytes and break every consumer's pinned CSP hash (#3534/#3535 for nav-overflow; #3540 extended the same gate to search-widget, the exact failure class the freezes exist to prevent).",
-    "check:prepack-contract": "pnpm --dir ../.. check:search-widget-drift && pnpm --dir ../.. check:nav-overflow-drift && pnpm --dir ../.. gen:changelog && node scripts/check-theme-css.mjs && node scripts/check-safelist.mjs && node scripts/check-content-css.mjs && node scripts/check-page-loading-css.mjs && node scripts/check-features-css.mjs && node scripts/check-theme-packs.mjs && node scripts/check-catalog.mjs && node scripts/check-site-schema.mjs && node scripts/check-plugins.mjs && node scripts/check-plugin-resolution.mjs && node scripts/check-eject-sources.mjs && node scripts/check-routes-src.mjs && node scripts/check-shim-artifacts.mjs && node scripts/check-virtual-modules.mjs && node bin/gen-component-tokens.mjs --check",
+    "check:prepack-contract": "pnpm --dir ../.. check:search-widget-drift && pnpm --dir ../.. check:nav-overflow-drift && pnpm --dir ../.. gen:changelog && node scripts/check-theme-css.mjs && node scripts/check-safelist.mjs && node scripts/check-content-css.mjs && node scripts/check-page-loading-css.mjs && node scripts/check-features-css.mjs && node scripts/check-compiled-css.mjs && node scripts/check-theme-packs.mjs && node scripts/check-catalog.mjs && node scripts/check-site-schema.mjs && node scripts/check-theme-packs-registry.mjs && node scripts/check-plugins.mjs && node scripts/check-plugin-resolution.mjs && node scripts/check-eject-sources.mjs && node scripts/check-routes-src.mjs && node scripts/check-shim-artifacts.mjs && node scripts/check-virtual-modules.mjs && node bin/gen-component-tokens.mjs --check && node scripts/check-route-context-payload.mjs",
     "test:plugin-resolution": "node scripts/check-plugin-resolution.mjs",
     "test": "vitest run --config vitest.config.ts",
     "test:slow": "vitest run --config vitest.slow.config.ts",