@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/theme-cli/registry.d.ts

@@ -0,0 +1,14 @@
+import { type ThemePackRegistry, type ThemePackRegistryEntry } from "../theme-packs-registry/index.js";
+export type { ThemePackRegistry, ThemePackRegistryEntry };
+export interface LoadInstalledThemePackCatalogOptions {
+    /** Override for tests — points at a fixture `theme-packs/` directory
+     *  instead of this module's own shipped one. */
+    themePacksDir?: string | URL;
+}
+/**
+ * Load the full installed catalog (every pack the running
+ * `@takazudo/zudo-doc` ships), validated the same way the package's own
+ * build validates it (`loadThemePackRegistry` — throws loudly naming the
+ * offending pack on a corrupted install rather than silently degrading).
+ */
+export declare function loadInstalledThemePackCatalog(options?: LoadInstalledThemePackCatalogOptions): ThemePackRegistry;

package/dist/theme-cli/registry.js

@@ -0,0 +1,13 @@
+import {
+  loadThemePackRegistry
+} from "../theme-packs-registry/index.js";
+function defaultThemePacksDir() {
+  return new URL("../theme-packs/", import.meta.url);
+}
+function loadInstalledThemePackCatalog(options = {}) {
+  const dir = options.themePacksDir ?? defaultThemePacksDir();
+  return loadThemePackRegistry(dir);
+}
+export {
+  loadInstalledThemePackCatalog
+};

package/dist/theme-pack-dialog/dialog-state.d.ts

@@ -0,0 +1,25 @@
+import type { ThemePackMeta } from "../theme-packs-registry/index.js";
+/**
+ * Structurally parse the `{base}theme-packs/index.json` registry payload
+ * (ADR Decision 2: `{ schemaVersion: 1, packs: ThemePackMeta[] }`). This is a
+ * defensive shape check against a truncated/malformed fetch response — NOT a
+ * re-run of the build-time zod validator (`theme-packs-registry/validator.ts`),
+ * which already gated every pack before the manifest was ever written.
+ * Re-validating each field client-side would pull `zod` into this dialog's
+ * browser bundle for no real benefit (the ADR's "Registry types... come from
+ * theme-packs-registry/" note means TYPES only). Returns `null` on any shape
+ * mismatch so the caller can show its inline error note instead of crashing
+ * on a bad field access later (`isValidThemePackMeta` covers every field
+ * `ThemePackCard` reads).
+ */
+export declare function parseThemePackRegistryPayload(data: unknown): ThemePackMeta[] | null;
+/**
+ * Resolve which `meta.preview` swatch set paints the dialog's cards, matching
+ * the CURRENT light/dark UI mode (ADR Decision 7: "Card previews must pick
+ * the swatch set matching the CURRENT light/dark mode" — NOT `meta.mode`,
+ * which is only the designed-primary badge). Takes the raw `data-theme`
+ * attribute value rather than reading `document` itself so it stays
+ * plain-Node testable — mirrors `theme-toggle/color-scheme-sync.ts`'s
+ * `readColorSchemeFromDom` fallback shape (unknown/missing → "light").
+ */
+export declare function resolveDialogMode(dataThemeAttr: string | null): "light" | "dark";

package/dist/theme-pack-dialog/dialog-state.js

@@ -0,0 +1,40 @@
+function isValidSwatches(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v["bg"] !== "string" || typeof v["fg"] !== "string" || typeof v["accent"] !== "string") {
+    return false;
+  }
+  const syntax = v["syntax"];
+  if (typeof syntax !== "object" || syntax === null) return false;
+  const s = syntax;
+  return typeof s["keyword"] === "string" && typeof s["string"] === "string" && typeof s["comment"] === "string" && typeof s["callable"] === "string";
+}
+function isValidThemePackMeta(entry) {
+  if (typeof entry !== "object" || entry === null) return false;
+  const p = entry;
+  if (typeof p["slug"] !== "string" || typeof p["name"] !== "string" || typeof p["description"] !== "string") {
+    return false;
+  }
+  if (p["mode"] !== "light" && p["mode"] !== "dark") return false;
+  const fonts = p["fonts"];
+  if (typeof fonts !== "object" || fonts === null) return false;
+  if (typeof fonts["sans"] !== "string") return false;
+  const preview = p["preview"];
+  if (typeof preview !== "object" || preview === null) return false;
+  const pv = preview;
+  return isValidSwatches(pv["light"]) && isValidSwatches(pv["dark"]);
+}
+function parseThemePackRegistryPayload(data) {
+  if (typeof data !== "object" || data === null) return null;
+  const record = data;
+  if (record["schemaVersion"] !== 1 || !Array.isArray(record["packs"])) return null;
+  const packs = record["packs"];
+  return packs.every(isValidThemePackMeta) ? packs : null;
+}
+function resolveDialogMode(dataThemeAttr) {
+  return dataThemeAttr === "dark" ? "dark" : "light";
+}
+export {
+  parseThemePackRegistryPayload,
+  resolveDialogMode
+};

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

@@ -0,0 +1,5 @@
+import type { ThemePackDialogProps } from "../theme-pack-switcher/index.js";
+export declare function ThemePackDialog({ open, onClose, order, active, base }: ThemePackDialogProps): import("preact").JSX.Element;
+export declare namespace ThemePackDialog {
+    var displayName: string;
+}

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

@@ -0,0 +1,152 @@
+"use client";
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "preact/compat";
+import { Close } from "../icons/index.js";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+import { applyThemePack, DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
+import { connectActivePackSync } from "../theme-pack-switcher/switcher-state.js";
+import { useModalDialog } from "../use-modal-dialog/index.js";
+import { parseThemePackRegistryPayload, resolveDialogMode } from "./dialog-state.js";
+import { ThemePackCard } from "./theme-pack-card.js";
+const COLOR_SCHEME_CHANGED_EVENT = "color-scheme-changed";
+const LAUNCHER_SELECTOR = "[data-switcher-launcher]";
+function ThemePackDialog({ open, onClose, order, active, base }) {
+  const [registryState, setRegistryState] = useState("idle");
+  const [packs, setPacks] = useState(null);
+  const [mode, setMode] = useState(
+    () => typeof document === "undefined" ? "light" : resolveDialogMode(document.documentElement.getAttribute("data-theme"))
+  );
+  const [activeSlug, setActiveSlug] = useState(active);
+  const launcherFocusRef = useRef(null);
+  const hasBrowsablePacks = order.some((entry) => entry.slug !== DEFAULT_THEME_PACK_SLUG);
+  useEffect(() => connectActivePackSync(setActiveSlug), []);
+  useEffect(() => {
+    function sync() {
+      setMode(resolveDialogMode(document.documentElement.getAttribute("data-theme")));
+    }
+    window.addEventListener(COLOR_SCHEME_CHANGED_EVENT, sync);
+    return () => window.removeEventListener(COLOR_SCHEME_CHANGED_EVENT, sync);
+  }, []);
+  useEffect(() => {
+    if (!open) return;
+    launcherFocusRef.current = document.querySelector(LAUNCHER_SELECTOR);
+  }, [open]);
+  const hasOpenedRef = useRef(false);
+  const [fetchToken, setFetchToken] = useState(0);
+  useEffect(() => {
+    if (open && !hasOpenedRef.current) {
+      hasOpenedRef.current = true;
+      if (hasBrowsablePacks) setFetchToken((t) => t + 1);
+    }
+  }, [open, hasBrowsablePacks]);
+  useEffect(() => {
+    if (fetchToken === 0) return;
+    let cancelled = false;
+    setRegistryState("loading");
+    fetch(`${base}theme-packs/index.json`).then((res) => {
+      if (!res.ok) throw new Error(`theme-packs/index.json responded ${res.status}`);
+      return res.json();
+    }).then((data) => {
+      if (cancelled) return;
+      const parsed = parseThemePackRegistryPayload(data);
+      if (parsed === null) {
+        setRegistryState("error");
+        return;
+      }
+      setPacks(parsed);
+      setRegistryState("loaded");
+    }).catch(() => {
+      if (!cancelled) setRegistryState("error");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [fetchToken, base]);
+  const retry = useCallback(() => setFetchToken((t) => t + 1), []);
+  const { dialogRef, handleBackdropClick } = useModalDialog({
+    isOpen: open,
+    onClose,
+    navigateEvent: AFTER_NAVIGATE_EVENT,
+    backdropClickClose: true,
+    manageFocus: true,
+    returnFocusRef: launcherFocusRef
+  });
+  return /* @__PURE__ */ jsx(
+    "dialog",
+    {
+      ref: dialogRef,
+      onClick: handleBackdropClick,
+      "aria-labelledby": "zd-theme-pack-dialog-title",
+      className: "z-modal m-auto max-h-[85vh] w-[calc(100vw-2rem)] max-w-[64rem] rounded-lg border border-muted bg-surface p-0 text-fg backdrop:z-modal-backdrop backdrop:bg-bg/80",
+      children: /* @__PURE__ */ jsxs("div", { className: "flex max-h-[85vh] flex-col", children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex shrink-0 items-center justify-between gap-hsp-sm border-b border-muted px-hsp-lg py-vsp-sm", children: [
+          /* @__PURE__ */ jsx("h2", { id: "zd-theme-pack-dialog-title", className: "text-title font-bold text-fg", children: "Preview theme" }),
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              onClick: () => dialogRef.current?.close(),
+              "aria-label": "Close",
+              className: "flex items-center justify-center text-muted transition-colors hover:text-fg",
+              children: /* @__PURE__ */ jsx(Close, { className: "h-icon-sm w-icon-sm" })
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx("div", { className: "min-h-0 flex-1 overflow-y-auto overscroll-contain px-hsp-lg py-vsp-lg", children: !hasBrowsablePacks ? /* @__PURE__ */ jsx("p", { className: "py-vsp-xl text-center text-small text-muted", children: "No other theme packs are configured \u2014 only the default look is available." }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          registryState === "error" && /* @__PURE__ */ jsxs(
+            "div",
+            {
+              role: "alert",
+              className: "mx-auto flex max-w-sm flex-col items-center gap-vsp-xs rounded-[0.75rem] border border-danger bg-bg px-hsp-lg py-vsp-lg text-center text-small text-danger",
+              children: [
+                /* @__PURE__ */ jsx("p", { children: "Could not load theme previews." }),
+                /* @__PURE__ */ jsx(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: retry,
+                    className: "rounded border border-danger px-hsp-md py-hsp-2xs text-caption text-danger transition-colors hover:bg-danger/10",
+                    children: "Retry"
+                  }
+                )
+              ]
+            }
+          ),
+          (registryState === "idle" || registryState === "loading") && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("p", { role: "status", className: "sr-only", children: "Loading theme previews\u2026" }),
+            /* @__PURE__ */ jsx(
+              "div",
+              {
+                "aria-hidden": "true",
+                className: "grid grid-cols-1 gap-hsp-lg sm:grid-cols-2 lg:grid-cols-3",
+                children: order.map((entry) => /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    className: "h-40 animate-pulse rounded-lg border border-muted bg-surface/50"
+                  },
+                  entry.slug
+                ))
+              }
+            )
+          ] }),
+          packs !== null && /* @__PURE__ */ jsx("div", { className: "grid grid-cols-1 gap-hsp-lg sm:grid-cols-2 lg:grid-cols-3", children: packs.map((meta) => /* @__PURE__ */ jsx(
+            ThemePackCard,
+            {
+              meta,
+              mode,
+              isActive: meta.slug === activeSlug,
+              onSelect: () => {
+                void applyThemePack(meta.slug);
+              }
+            },
+            meta.slug
+          )) })
+        ] }) })
+      ] })
+    }
+  );
+}
+ThemePackDialog.displayName = "ThemePackDialog";
+export {
+  ThemePackDialog
+};

package/dist/theme-pack-dialog/theme-pack-card.d.ts

@@ -0,0 +1,25 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { VNode } from "preact";
+import type { ThemePackMeta } from "../theme-packs-registry/index.js";
+export interface ThemePackCardProps {
+    /** Full pack meta (incl. resolved preview swatches) for one registry entry. */
+    meta: ThemePackMeta;
+    /** Current light/dark UI mode — selects which `meta.preview` swatch set
+     *  paints the card (NOT `meta.mode`, which is only the designed-primary
+     *  badge shown alongside the name). */
+    mode: "light" | "dark";
+    /** Whether this card's pack is the currently active one (selected ring). */
+    isActive: boolean;
+    /** Apply this pack — the caller wires this to `applyThemePack(meta.slug)`;
+     *  this component stays a plain presentational click forwarder. */
+    onSelect: () => void;
+}
+/**
+ * One theme-pack preview card: a mini "Aa Heading" / prose+link / code-line
+ * sample painted from `meta.preview[mode]`, plus name, Light/Dark badge, and
+ * description. Clicking applies the pack immediately (the dialog stays open
+ * — ADR Decision 7 — so the selected ring is driven by `isActive`, not by
+ * the click itself).
+ */
+export declare function ThemePackCard({ meta, mode, isActive, onSelect }: ThemePackCardProps): VNode;

package/dist/theme-pack-dialog/theme-pack-card.js

@@ -0,0 +1,72 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+function ThemePackCard({ meta, mode, isActive, onSelect }) {
+  const swatches = meta.preview[mode];
+  const fontCaption = meta.fonts.display ?? meta.fonts.sans;
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: "button",
+      onClick: onSelect,
+      "aria-pressed": isActive,
+      "aria-label": `Apply ${meta.name} theme pack \u2014 ${meta.mode === "dark" ? "Dark" : "Light"}. ${meta.description}`,
+      className: `flex flex-col gap-vsp-2xs rounded-lg border p-hsp-sm text-left transition-colors focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 ${isActive ? "border-accent ring-2 ring-accent" : "border-muted hover:border-accent"}`,
+      children: [
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            "aria-hidden": "true",
+            className: "flex flex-col gap-vsp-3xs rounded-md border p-hsp-sm",
+            style: {
+              backgroundColor: swatches.bg,
+              color: swatches.fg,
+              borderColor: `color-mix(in oklch, ${swatches.fg} 15%, transparent)`
+            },
+            children: [
+              /* @__PURE__ */ jsx("p", { className: "text-title font-bold", children: "Aa Heading" }),
+              /* @__PURE__ */ jsxs("p", { className: "text-small", children: [
+                "The quick brown fox jumps over",
+                " ",
+                /* @__PURE__ */ jsx("span", { className: "underline", style: { color: swatches.accent }, children: "the lazy dog" }),
+                "."
+              ] }),
+              /* @__PURE__ */ jsxs(
+                "p",
+                {
+                  className: "rounded px-hsp-2xs py-hsp-3xs font-mono text-caption",
+                  style: { backgroundColor: `color-mix(in oklch, ${swatches.fg} 8%, transparent)` },
+                  children: [
+                    /* @__PURE__ */ jsx("span", { style: { color: swatches.syntax.keyword }, children: "const" }),
+                    " ",
+                    /* @__PURE__ */ jsx("span", { style: { color: swatches.syntax.callable }, children: "theme" }),
+                    " =",
+                    " ",
+                    /* @__PURE__ */ jsxs("span", { style: { color: swatches.syntax.string }, children: [
+                      '"',
+                      meta.slug,
+                      '"'
+                    ] }),
+                    ";",
+                    " ",
+                    /* @__PURE__ */ jsxs("span", { style: { color: swatches.syntax.comment }, children: [
+                      "// ",
+                      meta.mode
+                    ] })
+                  ]
+                }
+              )
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-hsp-sm", children: [
+          /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate text-body font-bold text-fg", children: meta.name }),
+          /* @__PURE__ */ jsx("span", { className: "shrink-0 rounded-full border border-muted px-hsp-sm text-micro tracking-wide text-muted uppercase", children: meta.mode === "dark" ? "Dark" : "Light" })
+        ] }),
+        /* @__PURE__ */ jsx("p", { className: "text-caption text-muted", children: meta.description }),
+        /* @__PURE__ */ jsx("p", { className: "text-micro text-muted", children: fontCaption })
+      ]
+    }
+  );
+}
+export {
+  ThemePackCard
+};

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

@@ -0,0 +1,49 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type ThemePackOrderEntry } from "./switcher-state.js";
+export type { ThemePackOrderEntry } from "./switcher-state.js";
+/**
+ * Island props (ADR Decision 7 "Switcher data flow") — serializable ONLY:
+ * they ride the island marker's `data-props` JSON across the SSR → hydrate
+ * boundary, so no functions/components may ever be added here.
+ */
+export interface ThemePackSwitcherProps {
+    /** The SSR-known active pack slug (`settings.themePack`); the user's
+     *  stored choice is synced from the DOM after hydration. */
+    active: string;
+    /** The resolved, enabled packs IN SWITCHER ORDER — the Prev/Next cycle
+     *  order and the dialog grid order. */
+    order: ThemePackOrderEntry[];
+    /** Base prefix WITH trailing slash (`ctx.withBase("/")`) — forwarded to
+     *  the browse-all dialog for its `{base}theme-packs/index.json` fetch. */
+    base: string;
+}
+/** Props of the browse-all dialog mounted through {@link ThemePackDialogSlot}
+ *  — the #2825 contract. The dialog fetches `{base}theme-packs/index.json`
+ *  lazily on first open for the full meta (preview swatches); cards apply
+ *  via `applyThemePack(slug)` and the dialog stays open (ADR Decision 7). */
+export interface ThemePackDialogProps {
+    /** Whether the dialog is currently open. */
+    open: boolean;
+    /** Close callback (Esc / ✕ / backdrop — the dialog's own close paths). */
+    onClose: () => void;
+    /** The switcher order — also the dialog grid order. */
+    order: ThemePackOrderEntry[];
+    /** Currently active pack slug (live — follows `theme-pack-changed`). */
+    active: string;
+    /** Base prefix WITH trailing slash for the `index.json` fetch. */
+    base: string;
+}
+/** The browse-all dialog component contract (#2825). */
+export type ThemePackDialogComponent = (props: ThemePackDialogProps) => JSX.Element | null;
+/**
+ * The bottom-right theme-pack switcher flyout. Mounted (settings-gated on
+ * `themePackSwitcher`) by the package body-end islands via
+ * `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 namespace ThemePackSwitcher {
+    var displayName: string;
+}

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

@@ -0,0 +1,205 @@
+"use client";
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { useEffect, useRef, useState } from "preact/hooks";
+import { ChevronLeft, ChevronRight, Close } from "../icons/index.js";
+import { ThemePackDialog } from "../theme-pack-dialog/index.js";
+import { applyThemePack } from "./theme-pack-sync.js";
+import {
+  connectActivePackSync,
+  connectEscapeToClose,
+  nextPackSlug,
+  prevPackSlug,
+  resolveActiveEntry
+} from "./switcher-state.js";
+const ThemePackDialogSlot = ThemePackDialog;
+function GridIcon({ className }) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      class: className || void 0,
+      fill: "none",
+      viewBox: "0 0 24 24",
+      stroke: "currentColor",
+      "stroke-width": "2",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ jsx("rect", { x: "4", y: "4", width: "7", height: "7", rx: "1" }),
+        /* @__PURE__ */ jsx("rect", { x: "13", y: "4", width: "7", height: "7", rx: "1" }),
+        /* @__PURE__ */ jsx("rect", { x: "4", y: "13", width: "7", height: "7", rx: "1" }),
+        /* @__PURE__ */ jsx("rect", { x: "13", y: "13", width: "7", height: "7", rx: "1" })
+      ]
+    }
+  );
+}
+function PaletteIcon({ className }) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      class: className || void 0,
+      fill: "none",
+      viewBox: "0 0 24 24",
+      stroke: "currentColor",
+      "stroke-width": "2",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ jsx(
+          "path",
+          {
+            "stroke-linecap": "round",
+            "stroke-linejoin": "round",
+            d: "M12 21a9 9 0 1 1 9-9c0 2-1.5 3-3 3h-2a2 2 0 0 0-1.5 3.3c.5.6.2 1.7-.7 1.7H12z"
+          }
+        ),
+        /* @__PURE__ */ jsx("circle", { cx: "7.5", cy: "11.5", r: "1", fill: "currentColor", stroke: "none" }),
+        /* @__PURE__ */ jsx("circle", { cx: "10.5", cy: "7.5", r: "1", fill: "currentColor", stroke: "none" }),
+        /* @__PURE__ */ jsx("circle", { cx: "15", cy: "7.5", r: "1", fill: "currentColor", stroke: "none" })
+      ]
+    }
+  );
+}
+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 }) {
+  const [open, setOpen] = useState(false);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [activeSlug, setActiveSlug] = useState(active);
+  const launcherRef = useRef(null);
+  const cardRef = useRef(null);
+  useEffect(() => connectActivePackSync(setActiveSlug), []);
+  useEffect(() => {
+    if (!open || dialogOpen) return void 0;
+    return connectEscapeToClose(() => {
+      setOpen(false);
+      launcherRef.current?.focus();
+    });
+  }, [open, dialogOpen]);
+  useEffect(() => {
+    if (open) cardRef.current?.focus();
+  }, [open]);
+  const entry = resolveActiveEntry(order, activeSlug);
+  function cycle(step) {
+    const target = step === 1 ? nextPackSlug(order, activeSlug) : prevPackSlug(order, activeSlug);
+    if (target !== null && target !== activeSlug) void applyThemePack(target);
+  }
+  function closeCard() {
+    setOpen(false);
+    launcherRef.current?.focus();
+  }
+  function openDialog() {
+    setOpen(false);
+    setDialogOpen(true);
+  }
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      class: "fixed right-hsp-lg bottom-hsp-lg z-popover flex flex-col items-end gap-vsp-2xs",
+      "data-theme-pack-switcher": true,
+      children: [
+        open ? /* @__PURE__ */ jsxs(
+          "div",
+          {
+            ref: cardRef,
+            tabIndex: -1,
+            role: "dialog",
+            "aria-label": "Theme pack switcher",
+            "data-switcher-card": true,
+            class: "flex w-72 max-w-[calc(100vw-2rem)] flex-col gap-vsp-2xs rounded-lg border border-muted bg-surface p-hsp-lg shadow-lg focus-visible:outline-2 focus-visible:outline-accent",
+            children: [
+              /* @__PURE__ */ jsxs("div", { class: "flex items-start justify-between gap-hsp-sm", children: [
+                /* @__PURE__ */ jsx("p", { class: "min-w-0 break-words text-body font-bold text-fg", "aria-live": "polite", children: entry?.name ?? activeSlug }),
+                /* @__PURE__ */ jsxs("div", { class: "flex shrink-0 items-center gap-hsp-2xs", children: [
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      "aria-label": "Browse all theme packs",
+                      title: "Browse all theme packs",
+                      disabled: ThemePackDialogSlot === null,
+                      onClick: openDialog,
+                      class: ICON_BUTTON_CLASS,
+                      children: /* @__PURE__ */ jsx(GridIcon, { className: "h-icon-sm w-icon-sm" })
+                    }
+                  ),
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      "aria-label": "Close theme pack switcher",
+                      title: "Close",
+                      onClick: closeCard,
+                      class: ICON_BUTTON_CLASS,
+                      children: /* @__PURE__ */ jsx(Close, { className: "h-icon-sm w-icon-sm" })
+                    }
+                  )
+                ] })
+              ] }),
+              entry !== null && /* @__PURE__ */ jsx("span", { class: "self-start rounded-full border border-muted px-hsp-sm text-micro tracking-wide text-muted uppercase", children: entry.mode === "dark" ? "Dark" : "Light" }),
+              entry !== null && entry.description !== "" && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: entry.description }),
+              /* @__PURE__ */ jsxs("div", { class: "flex items-center justify-between gap-hsp-sm", children: [
+                /* @__PURE__ */ jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    "aria-label": "Previous theme pack",
+                    disabled: order.length < 2,
+                    onClick: () => cycle(-1),
+                    class: CONTROL_BUTTON_CLASS,
+                    children: [
+                      /* @__PURE__ */ jsx(ChevronLeft, { className: "h-icon-xs w-icon-xs" }),
+                      "Prev"
+                    ]
+                  }
+                ),
+                /* @__PURE__ */ jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    "aria-label": "Next theme pack",
+                    disabled: order.length < 2,
+                    onClick: () => cycle(1),
+                    class: CONTROL_BUTTON_CLASS,
+                    children: [
+                      "Next",
+                      /* @__PURE__ */ jsx(ChevronRight, { className: "h-icon-xs w-icon-xs" })
+                    ]
+                  }
+                )
+              ] })
+            ]
+          }
+        ) : null,
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            ref: launcherRef,
+            type: "button",
+            "aria-haspopup": "dialog",
+            "aria-expanded": open,
+            "aria-label": "Theme pack switcher",
+            title: "Theme packs",
+            "data-switcher-launcher": true,
+            onClick: () => setOpen(!open),
+            class: "flex h-10 w-10 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" })
+          }
+        ),
+        ThemePackDialogSlot !== null ? /* @__PURE__ */ jsx(
+          ThemePackDialogSlot,
+          {
+            open: dialogOpen,
+            onClose: () => setDialogOpen(false),
+            order,
+            active: activeSlug,
+            base
+          }
+        ) : null
+      ]
+    }
+  );
+}
+ThemePackSwitcher.displayName = "ThemePackSwitcher";
+export {
+  ThemePackSwitcher
+};

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

@@ -0,0 +1,56 @@
+/**
+ * One entry of the flyout's SSR-provided `order` prop — the lightweight
+ * projection of a registry entry's meta (ADR Decision 7 "Switcher data
+ * flow": `{ slug, name, mode, description }`). The array order IS the
+ * Prev/Next cycle order (and the dialog grid order).
+ */
+export interface ThemePackOrderEntry {
+    /** Pack slug (`meta.slug` — equals the pack's directory name). */
+    slug: string;
+    /** Display name shown as the flyout card title. */
+    name: string;
+    /** Designed-primary mode badge — a badge, not a capability flag. */
+    mode: "light" | "dark";
+    /** 1–2 sentence note shown under the title. */
+    description: string;
+}
+/**
+ * Resolve the cycle target `step` away from `active` in `order`, wrapping
+ * around at both ends (ADR Decision 7: "Ordering IS the switcher order",
+ * Prev/Next cycle with wraparound).
+ *
+ * - Empty `order` → `null` (nothing to cycle to).
+ * - `active` not present in `order` (e.g. the html attribute carries a slug
+ *   the switcher was not configured with) → the first entry for `+1`, the
+ *   last for `-1`, so the UI recovers onto the cycle instead of dead-ending.
+ */
+export declare function cyclePackSlug(order: readonly ThemePackOrderEntry[], active: string, step: 1 | -1): string | null;
+/** The Prev/Next cycle target after `active` (wraparound). */
+export declare function nextPackSlug(order: readonly ThemePackOrderEntry[], active: string): string | null;
+/** The Prev/Next cycle target before `active` (wraparound). */
+export declare function prevPackSlug(order: readonly ThemePackOrderEntry[], active: string): string | null;
+/**
+ * The `order` entry matching `active`, or `null` when the active slug is not
+ * part of the switcher order (the card then falls back to showing the bare
+ * slug with no badge/description).
+ */
+export declare function resolveActiveEntry(order: readonly ThemePackOrderEntry[], active: string): ThemePackOrderEntry | null;
+/**
+ * Connect a state setter to the live active-pack source of truth: push the
+ * CURRENT DOM value once immediately, then re-push on every
+ * `theme-pack-changed` event so multiple mounted surfaces (flyout, dialog, a
+ * future header trigger) never disagree — the ThemeToggle cross-instance
+ * sync pattern (#2012 E3). Returns an unsubscribe function suitable as a
+ * `useEffect` cleanup.
+ *
+ * Note the display state only ever advances FROM this event: a failed or
+ * aborted `applyThemePack` never fires it, so the UI never shows a pack that
+ * did not commit (ADR Decision 3 failure semantics).
+ */
+export declare function connectActivePackSync(onActive: (slug: string) => void): () => void;
+/**
+ * Register a document-level Escape handler (used while the flyout card is
+ * open — close on Escape, acceptance criterion of #2821). Returns the
+ * matching teardown, suitable as a `useEffect` cleanup.
+ */
+export declare function connectEscapeToClose(onEscape: () => void): () => void;