create-zudo-doc 0.2.21 → 0.2.22

package/templates/base/pages/lib/_head-with-defaults.tsx

@@ -1,147 +1,22 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// og:title / og:description / color-scheme head injection for the zfb doc pages.
-//
-// Why this wrapper exists: the v2 `<DocLayout>` shell exposes a `head` slot
-// but intentionally does NOT emit og:* meta or mount `<ColorSchemeProvider>` —
-// that is the host's responsibility.
-//
-// Without OgTags the SSG output is missing og:title / og:description,
-// which crawlers and link-preview tools rely on. Without ColorSchemeProvider
-// the runtime `:root { --zd-* }` palette is missing, so every component that
-// resolves a color via `--zd-*` (search match-keyword highlight, image-overlay,
-// etc.) falls back to UA defaults — and the smoke-search "matched
-// keywords" regression guard at e2e/smoke-search.spec.ts:167 fires
-// because `getComputedStyle(root).getPropertyValue("--zd-matched-keyword-bg")`
-// returns "" instead of the resolved palette token.
-//
-// (#1355 wave 13 — ColorSchemeProvider mount restored after the retirement of
-// the zfb cutover's initial setup.)
-
-import type { JSX } from "preact";
-import { OgTags, TwitterCard } from "@takazudo/zudo-doc/head";
-import { SIDEBAR_RESIZER_RESTORE_SCRIPT } from "@takazudo/zudo-doc/sidebar-resizer";
-// Import ColorSchemeProvider from the dedicated
-// `./theme/color-scheme-provider` subpath rather than the
-// "@takazudo/zudo-doc/theme" barrel — the barrel also re-exports the
-// ColorTweakExportModal island and the design-token SerDe/iframe-bridge
-// modules, which this SSR-only head emission does not need in its zfb
-// esbuild graph.
-import ColorSchemeProvider from "@takazudo/zudo-doc/theme/color-scheme-provider";
-import { composeMetaTitle } from "./_compose-meta-title";
-import { withBase, absoluteUrl } from "@/utils/base";
+// Host thin-stub — see @takazudo/zudo-doc/head-with-defaults (epic #2344, S5).
 import { settings } from "@/config/settings";
-// W3B (#1730): cssText + colorMode are precomputed here — the v2
-// ColorSchemeProvider no longer reaches into the host config tree.
+import { withBase, absoluteUrl } from "@/utils/base";
 import {
   generateCssCustomProperties,
   generateLightDarkCssProperties,
 } from "@/config/color-scheme-utils";
+import { composeMetaTitle } from "./_compose-meta-title";
+import { createHeadWithDefaults } from "@takazudo/zudo-doc/head-with-defaults";
 
-export interface HeadWithDefaultsProps {
-  /** Page title forwarded to og:title. Required. */
-  title: string;
-  /** Optional page description forwarded to og:description. */
-  description?: string;
-  /**
-   * Absolute canonical URL for this page. When supplied, emits
-   * <link rel="canonical" href="...">. Compute via `absoluteUrl(pageUrl)`
-   * (@/utils/base) in each host page; it returns undefined when
-   * settings.siteUrl is empty so the link is simply omitted.
-   */
-  canonical?: string;
-}
-
-/**
- * Default-bearing host wrapper that injects og:title / og:description,
- * the ColorSchemeProvider (`:root { --zd-* }` palette + theme bootstrap),
- * the favicon link, and an optional canonical link into the v2 layout's
- * `head` slot.
- *
- * og:title is run through composeMetaTitle so it matches the
- * "<title> | <siteName>" shape emitted by the host's <title> element
- * (the legacy Astro layout produced both shapes; the zfb host has to
- * compose them itself).
- *
- * og:title is always emitted — it is the unconditional DocHead contract
- * (OgTags always emits og:title regardless of settings). All other tags
- * are gated by settings.metaTags.
- *
- * Pure SSR — no state, no client-only imports. Intended for use as:
- *   head={<HeadWithDefaults title={title} description={description} canonical={canonical} />}
- * on every DocLayoutWithDefaults call site in the host pages.
- */
-export function HeadWithDefaults({
-  title,
-  description,
-  canonical,
-}: HeadWithDefaultsProps): JSX.Element {
-  const { metaTags } = settings;
-
-  // og:image / twitter:image must be absolute URLs — crawlers silently drop
-  // relative og:image values. absoluteUrl joins siteUrl (no trailing slash) +
-  // the base-prefixed asset path, and returns undefined when siteUrl is empty
-  // (e.g. a freshly scaffolded create-zudo-doc project that hasn't configured
-  // siteUrl yet) so we never ship a useless relative og:image. OgTags /
-  // TwitterCard already gate their image emission on the prop being defined;
-  // the og:image:* companion tags below are gated explicitly because they
-  // would dangle without the parent og:image.
-  const ogImageUrl =
-    metaTags.ogImage !== false
-      ? absoluteUrl(withBase(metaTags.ogImage))
-      : undefined;
-
-  // Resolve the palette CSS body once per page render (the v2 component
-  // is pure SSR — no caching needed).
-  const colorMode = settings.colorMode ? settings.colorMode : null;
-  const cssText = colorMode
-    ? generateLightDarkCssProperties()
-    : generateCssCustomProperties();
+export type { HeadWithDefaultsProps } from "@takazudo/zudo-doc/head-with-defaults";
 
-  return (
-    <>
-      <OgTags
-        title={composeMetaTitle(title)}
-        description={metaTags.description ? description : undefined}
-        ogType="website"
-        ogUrl={canonical}
-        ogImage={ogImageUrl}
-        ogSiteName={metaTags.ogSiteName ? settings.siteName : undefined}
-      />
-      {metaTags.keywords !== false && metaTags.keywords.length > 0 && (
-        <meta name="keywords" content={metaTags.keywords} />
-      )}
-      {/* og:image:width / og:image:height / og:image:alt — not in OgTags API;
-          emitted here directly to avoid expanding the shared HeadProps surface.
-          Standard 1200×630 social preview dimensions. Gated on ogImageUrl so
-          the companion tags don't dangle when og:image itself was suppressed. */}
-      {ogImageUrl !== undefined && (
-        <>
-          <meta property="og:image:width" content="1200" />
-          <meta property="og:image:height" content="630" />
-          <meta property="og:image:alt" content={composeMetaTitle(title)} />
-        </>
-      )}
-      {metaTags.twitterCard !== false && (
-        <TwitterCard
-          card={metaTags.twitterCard}
-          image={ogImageUrl}
-          site={metaTags.twitterSite}
-          creator={metaTags.twitterCreator}
-        />
-      )}
-      <ColorSchemeProvider cssText={cssText} colorMode={colorMode} />
-      {/* Pre-paint inline script: restore persisted sidebar width to
-          --zd-sidebar-w on :root before first paint, so a reload after
-          drag-resizing the sidebar doesn't snap back to the CSS default
-          clamp() width. Mirrors the sibling sidebar-toggle restore
-          script emitted from the page's afterSidebar slot. */}
-      {settings.sidebarResizer && <script dangerouslySetInnerHTML={{ __html: SIDEBAR_RESIZER_RESTORE_SCRIPT }} />}
-      {/* favicon set — withBase() handles the configured base path prefix */}
-      <link rel="icon" href={withBase("/favicon.ico")} sizes="any" />
-      <link rel="icon" type="image/png" sizes="32x32" href={withBase("/favicon-32x32.png")} />
-      <link rel="icon" type="image/png" sizes="16x16" href={withBase("/favicon-16x16.png")} />
-      {canonical !== undefined && <link rel="canonical" href={canonical} />}
-    </>
-  );
-}
+export const HeadWithDefaults = createHeadWithDefaults({
+  settings,
+  composeMetaTitle,
+  withBase,
+  absoluteUrl,
+  generateCssCustomProperties,
+  generateLightDarkCssProperties,
+});

package/templates/base/pages/lib/_header-with-defaults.tsx

@@ -1,57 +1,6 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-/version-aware Header wrapper for the zfb doc pages.
-//
-// Header data-prep utilities — builds the resolved header config from user
-// settings + page context: header nav, active-path state, mobile SidebarToggle
-// island (hamburger + slide-in panel) with the full sidebar tree for doc routes,
-// and feeds everything into the v2 <Header> shell.
-//
-// Why this wrapper exists: the v2 Header shell is intentionally
-// framework-agnostic — it accepts slot props (sidebarToggle, themeToggle,
-// etc.) but does not import host helpers (@/config/*, @/utils/*) so the
-// package can be published independently. The data prep stays on the host
-// side. Without this wrapper the zfb doc pages fall through to the
-// DocLayoutWithDefaults minimal default (a bare <header> with only
-// <ThemeToggle>) — the full logo + nav + mobile-sidebar markup is absent
-// from the SSG output, breaking crawlers, screen readers, and no-JS users.
-//
-// Mobile sidebar strategy:
-//   - The v2 <Header> accepts a `sidebarToggle` slot that holds the
-//     complete mobile sidebar widget: hamburger button + backdrop overlay +
-//     slide-in <aside> panel (all rendered by <SidebarToggle>).
-//   - This wrapper ALWAYS builds the sidebarToggle (refs #1453:
-//     SidebarToggle is rendered unconditionally on every page; the host CSS
-//     hides it on pages with hide_sidebar). When `navSection` is defined the
-//     panel gets the full section tree; when undefined (home, 404, tags,
-//     versions) nodes=[] so the panel shows only rootMenuItems.
-//   - The bare package ThemeToggle (wrapped in Island below) is always passed
-//     to Header.themeToggle so the ThemeToggle island marker appears in the
-//     header on every page — matching the documented header contract.
-//
-// Locale switcher strategy (refs #1453):
-//   - This wrapper always renders <LanguageSwitcher /> in the right-items row
-//     when multiple locales are configured. Builds locale links from
-//     buildLocaleLinks() and passes a <LanguageSwitcher> as the
-//     languageSwitcher slot prop.
-//   - Header only renders the slot when settings.locales has > 1 entry, so
-//     single-locale projects are unaffected.
-
-import type { VNode, JSX } from "preact";
-import { Island } from "@takazudo/zfb";
-import { Header } from "@takazudo/zudo-doc/header";
-import {
-  LanguageSwitcher,
-  VersionSwitcher,
-  type VersionSwitcherLabels,
-} from "@takazudo/zudo-doc/i18n-version";
-// The bare (non-island-wrapped) package ThemeToggle, imported straight from
-// the npm subpath: zfb >= 0.1.0-next.39 scans "use client" modules under
-// node_modules (zfb#999/#1001), so the marker registers without the former
-// project-source shim (#2048/#2057). This header composes its own Island
-// below, avoiding nesting an island inside an island.
-import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
-import SidebarToggle from "@/components/sidebar-toggle";
+// Host thin-stub — see @takazudo/zudo-doc/header-with-defaults (epic #2344, S5).
 import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
 import { buildGitHubRepoUrl } from "@/utils/github";
@@ -62,7 +11,7 @@ import {
   versionedDocsUrl,
   withBase,
 } from "@/utils/base";
-import { filterHeaderRightItems } from "@takazudo/zudo-doc/header";
+import { createHeaderWithDefaults } from "@takazudo/zudo-doc/header-with-defaults";
 import { SearchWidget } from "./_search-widget";
 import {
   buildRootMenuItems,
@@ -71,275 +20,26 @@ import {
   getThemeDefaultMode,
 } from "./_nav-data-prep";
 
-// ---------------------------------------------------------------------------
-// Component
-// ---------------------------------------------------------------------------
-
-export interface HeaderWithDefaultsProps {
-  /** Active locale; defaults to the configured defaultLocale. */
-  lang?: Locale | string;
-  /**
-   * Current page URL path (as the layout passes from Astro.url.pathname or
-   * the zfb equivalent). Used by the Header to compute the active nav item
-   * and by the mobile sidebar footer locale-switcher links.
-   */
-  currentPath?: string;
-  /** Active version slug, when rendering inside /v/{version}/... routes. */
-  currentVersion?: string;
-  /**
-   * Slug of the active doc page — forwarded to SidebarTree so it can
-   * highlight the current entry. Required when navSection is set.
-   */
-  currentSlug?: string;
-  /**
-   * Header-nav category matcher used to scope the sidebar tree (e.g.
-   * "guides"). When provided the mobile sidebar toggle is wired with the
-   * full sidebar tree for this section. When omitted (404, index, tags,
-   * versions pages) no mobile sidebar toggle is included in the header.
-   */
-  navSection?: string;
-}
-
-/**
- * Default-bearing host wrapper around v2's <Header> shell.
- *
- * Handles:
- *  1. Logo, main nav with active-path highlight — delegated to <Header>.
- *  2. ThemeToggle island in the right items row — passed as themeToggle slot.
- *  3. Mobile SidebarToggle island (hamburger + slide-in aside + tree) —
- *     built from the same nav data as SidebarWithDefaults and passed as
- *     the sidebarToggle slot when navSection is defined.
- */
-export function HeaderWithDefaults(
-  props: HeaderWithDefaultsProps,
-): JSX.Element {
-  const {
-    lang: langProp = defaultLocale,
-    currentPath = "",
-    currentVersion,
-    currentSlug,
-    navSection,
-  } = props;
-  // Route params arrive as `string`; cast to Locale since keys of settings.locales
-  // are always valid locale codes. The prop accepts `Locale | string` so callers
-  // without a Locale variable don't need to cast (e.g. _tag-pages.tsx).
-  const lang = langProp as Locale;
-
-  // Root-menu items, locale links, sidebar nodes, and theme mode — all
-  // delegated to the shared _nav-data-prep helpers so header and sidebar
-  // wrappers stay in sync without duplicating the logic.
-  const rootMenuItems = buildRootMenuItems(lang, currentVersion);
-
-  // Build the mobile sidebar toggle unconditionally — SidebarToggle is rendered
-  // on every page (refs #1453); the host CSS hides it where unneeded. When navSection is
-  // defined the panel gets the full section tree; when undefined (home, 404,
-  // tags, versions) nodes=[] so the panel shows only rootMenuItems + locale
-  // links (the basic nav menu without a doc tree).
-  const backToMenuLabel = t("nav.backToMenu", lang);
-
-  // Locale-switcher links in the mobile sidebar footer — only when
-  // multiple locales are configured (mirrors _sidebar-with-defaults.tsx).
-  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
-
-  const themeDefaultMode = getThemeDefaultMode();
-
-  const sidebarNodes = buildSidebarNodes(lang, navSection, currentVersion);
-
-  // Wrap SidebarToggle (hamburger button + slide-in aside + SidebarTree) in
-  // Island so the SSG output carries the full tree HTML AND the
-  // data-zfb-island="SidebarToggle" marker for client-side hydration.
-  // Island.captureComponentName reads SidebarToggle.name → "SidebarToggle".
-  //
-  // SidebarTree's data props (nodes, currentSlug, rootMenuItems, …) are
-  // passed to SidebarToggle directly rather than as JSX children so they
-  // ride across the SSR → hydrate boundary in the Island marker's
-  // `data-props` attribute. Island only serialises a wrapped child
-  // component's *own* props (excluding `children`); when SidebarTree was
-  // nested as a JSX child its data was dropped during hydration and
-  // SidebarToggle re-rendered with `children=undefined`, wiping the SSR
-  // tree DOM. zudolab/zudo-doc#1355 wave 13.5.
-  //
-  // C4 — media-gated hydration.  zfb only supports load|idle|visible
-  // strategies (no "media" strategy; matchMedia inside the component is too
-  // late — props are already emitted, bundle already downloaded).
-  // Upstream feature request: Takazudo/zudo-front-builder#969.
-  //
-  // Best achievable downstream: when="visible" + all SidebarToggle children
-  // are lg:hidden, so on desktop the Island wrapper div has zero rendered
-  // dimensions.  IntersectionObserver fires isIntersecting=false on desktop
-  // (zero-size element) → Preact hydrate() is never called.  On mobile (and
-  // on desktop→mobile resize) the children become visible, the element gains
-  // size, IO fires isIntersecting=true, and hydration completes normally.
-  //
-  // Residual: data-props JSON (~2.4 KB) is still emitted in the SSR HTML on
-  // every page regardless of viewport, because it is serialised at build time
-  // and not gated by media. Eliminating it requires a zfb "media" hydration
-  // strategy — tracked in Takazudo/zudo-front-builder#969.
-  const sidebarToggle = Island({
-    when: "visible",
-    children: (
-      <SidebarToggle
-        nodes={sidebarNodes}
-        currentSlug={currentSlug}
-        rootMenuItems={rootMenuItems}
-        backToMenuLabel={backToMenuLabel}
-        localeLinks={localeLinks}
-        themeDefaultMode={themeDefaultMode}
-      />
-    ),
-  }) as unknown as VNode;
-
-  // Wrap the bare ThemeToggle in Island({when:"load"}) so the SSG
-  // output emits a data-zfb-island="ThemeToggle" marker the hydration
-  // runtime can find — matching the documented header contract.
-  const themeToggle = Island({
-    when: "load",
-    children: <ThemeToggle defaultMode={themeDefaultMode} />,
-  }) as unknown as VNode;
-
-  // Locale-aware search widget. Renders the full dialog markup in SSR
-  // so the placeholder text ("Type to search..." / 「検索したい単語を入力」)
-  // and keyboard-shortcut hint appear in the static HTML on every page.
-  // Strings are derived from the host's t() helper so locale switching works.
-  const searchWidget = (
-    <SearchWidget
-      placeholderText={t("search.placeholder", lang)}
-      shortcutHint={t("search.shortcutHint", lang)}
-      resultCountTemplate={t("search.resultCount", lang)}
-      searchLabel={t("search.label", lang)}
-    />
-  );
+export type { HeaderWithDefaultsProps } from "@takazudo/zudo-doc/header-with-defaults";
 
-  // Build the version-switcher component when versioning is configured.
-  // The VersionSwitcher is a pure SSR component — it emits the full dropdown
-  // markup (including the "All versions" footer link) directly in the SSG
-  // HTML so crawlers and JS-off users see the version list. The interactive
-  // toggle behavior is wired by VERSION_SWITCHER_INIT_SCRIPT included in
-  // the layout's body-end scripts.
-  //
-  // Gate: only render when settings.versions is a non-empty array. When
-  // versioning is disabled (settings.versions === false) the slot is
-  // undefined and the Header renders nothing for the version-switcher item.
-  let versionSwitcher: VNode | undefined;
-
-  if (settings.versions && settings.versions.length > 0) {
-    const isNonDefaultLocale = lang !== defaultLocale;
-    // "All versions" page URL — locale-prefixed when not on the default locale.
-    const versionsPageUrl = withBase(
-      isNonDefaultLocale ? `/${lang}/docs/versions` : "/docs/versions",
-    );
-    // "Latest" entry links to the current page in the latest (unversioned)
-    // docs when a slug is available, or falls back to the versions index page.
-    // Null check, not truthiness: "" is the canonical root-index slug (#1891)
-    // and must produce real per-version root URLs.
-    const latestUrl = currentSlug != null
-      ? docsUrl(currentSlug, lang)
-      : versionsPageUrl;
-
-    // Per-version URLs for the current page. When there is no slug in scope
-    // (e.g. on the versions page itself) all entries point to the versions
-    // index — matching the documented version-switcher contract.
-    const versionUrls: Record<string, string> = {};
-    for (const v of settings.versions) {
-      versionUrls[v.slug] = currentSlug != null
-        ? versionedDocsUrl(currentSlug, v.slug, lang)
-        : versionsPageUrl;
-    }
-
-    const labels: VersionSwitcherLabels = {
-      latest: t("version.latest", lang),
-      switcher: t("version.switcher.label", lang),
-      unavailable: t("version.switcher.unavailable", lang),
-      allVersions: t("version.switcher.allVersions", lang),
-    };
-
-    versionSwitcher = (
-      <VersionSwitcher
-        versions={settings.versions.map((v) => ({
-          slug: v.slug,
-          label: v.label ?? v.slug,
-        }))}
-        currentVersion={currentVersion}
-        latestUrl={latestUrl}
-        versionsPageUrl={versionsPageUrl}
-        versionUrls={versionUrls}
-        labels={labels}
-        idSuffix="header"
-      />
-    ) as unknown as VNode;
-  }
-
-  // Build locale-switcher for the header right-items row (refs #1453).
-  // Renders <LanguageSwitcher /> when multiple locales are configured.
-  // Reuses the same localeLinks array built above for the mobile sidebar footer
-  // (buildLocaleLinks is pure, but one call is cleaner).
-  const languageSwitcher =
-    localeLinks != null ? (
-      <LanguageSwitcher
-        links={localeLinks}
-      />
-    ) as unknown as VNode : undefined;
-
-  // Locale-keyed persist key: same-locale swaps preserve the header's
-  // DOM-node identity; cross-locale swaps use a different key and the
-  // router replaces the header entirely (re-rendering locale-specific
-  // SSR content such as the LanguageSwitcher anchors). See #1546 + #1549.
-  const persistKey = `header-${lang}`;
-
-  // Compute the right-items flags from the host's settings. The v2
-  // `<Header>` no longer consults `@/config/settings` directly — see
-  // sub-issue #1729 — so the wrapper is responsible for translating
-  // host state into the prop bag the renderer expects. Boolean
-  // coercion mirrors the original filter predicates verbatim.
-  const headerRightItems = filterHeaderRightItems(
-    settings.headerRightItems ?? [],
-    {
-      designTokenPanel: Boolean(settings.designTokenPanel),
-      aiAssistant: Boolean(settings.aiAssistant),
-      colorMode: Boolean(settings.colorMode),
-      hasLocales: Object.keys(settings.locales).length > 0,
-      hasVersions: Boolean(settings.versions),
-      hasGithubUrl: Boolean(settings.githubUrl),
-    },
-  );
-
-  const githubRepoUrl = buildGitHubRepoUrl();
-  const githubLabel = t("header.github", lang);
-
-  return (
-    <Header
-      lang={lang}
-      currentPath={currentPath}
-      currentVersion={currentVersion}
-      activeCategory={navSection}
-      sidebarToggle={sidebarToggle}
-      themeToggle={themeToggle}
-      search={searchWidget}
-      versionSwitcher={versionSwitcher}
-      languageSwitcher={languageSwitcher}
-      persistKey={persistKey}
-      siteName={settings.siteName}
-      headerNav={settings.headerNav}
-      headerRightItems={headerRightItems}
-      colorModeEnabled={Boolean(settings.colorMode)}
-      hasLocales={locales.length > 1}
-      hasVersions={Boolean(settings.versions)}
-      githubRepoUrl={githubRepoUrl}
-      githubLabel={githubLabel}
-      urlHelpers={{
-        withBase,
-        stripBase,
-        // `navHref` from `@/utils/base` types the lang param as the
-        // host's literal-locale union; v2's `Locale` is `string`. Wrap
-        // so strictFunctionTypes accepts the assignment without losing
-        // the runtime call shape (sub-issue #1729 boundary widening).
-        navHref: (path, l, v) => navHref(path, l as Locale | undefined, v),
-      }}
-      i18n={{
-        defaultLocale,
-        locales,
-        t,
-      }}
-    />
-  );
-}
+export const HeaderWithDefaults = createHeaderWithDefaults({
+  settings,
+  defaultLocale,
+  locales,
+  t: (key, lang) => t(key as Parameters<typeof t>[0], lang as Locale),
+  withBase,
+  stripBase,
+  docsUrl: (slug, lang) => docsUrl(slug, lang as Locale),
+  navHref: (path, lang, version) => navHref(path, lang as Locale | undefined, version),
+  versionedDocsUrl: (slug, versionSlug, lang) =>
+    versionedDocsUrl(slug, versionSlug, lang as Locale),
+  buildLocaleLinksForNav: (currentPath, lang, localeCount) =>
+    buildLocaleLinksForNav(currentPath, lang as Locale, localeCount),
+  buildRootMenuItems: (lang, currentVersion) =>
+    buildRootMenuItems(lang as Locale, currentVersion),
+  buildSidebarNodes: (lang, navSection, currentVersion) =>
+    buildSidebarNodes(lang as Locale, navSection, currentVersion),
+  getThemeDefaultMode,
+  buildGitHubRepoUrl,
+  SearchWidget,
+});

package/templates/base/pages/lib/_inline-version-switcher.tsx

@@ -1,85 +1,23 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Inline VersionSwitcher for the breadcrumb rightSlot on doc pages.
-//
-// The reference site (takazudomodular.com) renders the version-switcher
-// pill inline at the right of the breadcrumb row on every doc page:
-//
-//   <div class="mb-vsp-sm flex ... sm:justify-between [&_nav]:mb-0">
-//     <breadcrumb nav>
-//     <VersionSwitcher ... />
-//   </div>
-//
-// (Wave 2 parity sweep, zudolab/zudo-doc#1478; placement fix #1534.)
-// The header already shows a VersionSwitcher via _header-with-defaults.tsx;
-// this helper provides the pill for the breadcrumb's `rightSlot` prop so
-// both the DOM position AND the flex-row layout match the reference.
-//
-// Gate: only returns a non-null element when settings.versions is a
-// non-empty array. When versioning is disabled the caller gets undefined
-// and <Breadcrumb> renders without a rightSlot (no wrapper div emitted).
+// Thin stub — inline-version-switcher moved to the package (epic #2344, S8).
+// Calls `createInlineVersionSwitcher(deps)` from
+// @takazudo/zudo-doc/inline-version-switcher with host singletons injected,
+// then re-exports the resulting builder so all existing call sites continue
+// to work unchanged.
 
-import type { JSX } from "preact";
-import {
-  VersionSwitcher,
-  type VersionSwitcherLabels,
-} from "@takazudo/zudo-doc/i18n-version";
+import { createInlineVersionSwitcher } from "@takazudo/zudo-doc/inline-version-switcher";
 import { settings } from "@/config/settings";
-import { defaultLocale, t, type Locale } from "@/config/i18n";
+import { defaultLocale, t } from "@/config/i18n";
 import { docsUrl, versionedDocsUrl, withBase } from "@/utils/base";
 
-/**
- * Build an inline VersionSwitcher element for the `<Breadcrumb rightSlot>` prop.
- *
- * Returns `undefined` when versioning is not configured (callers can pass
- * the return value directly as `rightSlot` — `<Breadcrumb>` renders the
- * plain nav (no flex wrapper, no version pill) when `rightSlot` is
- * `undefined`).
- *
- * @param slug       - Slug of the current doc page (used to build per-version URLs).
- * @param locale     - Active locale string.
- * @param currentVersion - Active version slug, or `undefined` on the "latest" route.
- */
-export function buildInlineVersionSwitcher(
-  slug: string,
-  locale: Locale,
-  currentVersion?: string,
-): JSX.Element | undefined {
-  if (!settings.versions || settings.versions.length === 0) return undefined;
+export { type InlineVersionSwitcherVersionEntry } from "@takazudo/zudo-doc/inline-version-switcher";
 
-  const isNonDefaultLocale = locale !== defaultLocale;
-  const versionsPageUrl = withBase(
-    isNonDefaultLocale ? `/${locale}/docs/versions` : "/docs/versions",
-  );
-  // The docs root index has the canonical empty slug "" (#1891), and
-  // docsUrl("")/versionedDocsUrl("") resolve to the per-version docs roots —
-  // so an empty slug must NOT fall back to the versions page.
-  const latestUrl = docsUrl(slug, locale);
-
-  const versionUrls: Record<string, string> = {};
-  for (const v of settings.versions) {
-    versionUrls[v.slug] = versionedDocsUrl(slug, v.slug, locale);
-  }
-
-  const labels: VersionSwitcherLabels = {
-    latest: t("version.latest", locale),
-    switcher: t("version.switcher.label", locale),
-    unavailable: t("version.switcher.unavailable", locale),
-    allVersions: t("version.switcher.allVersions", locale),
-  };
-
-  return (
-    <VersionSwitcher
-      versions={settings.versions.map((v) => ({
-        slug: v.slug,
-        label: v.label ?? v.slug,
-      }))}
-      currentVersion={currentVersion}
-      latestUrl={latestUrl}
-      versionsPageUrl={versionsPageUrl}
-      versionUrls={versionUrls}
-      labels={labels}
-      idSuffix="inline"
-    />
-  );
-}
+export const buildInlineVersionSwitcher = createInlineVersionSwitcher({
+  settings,
+  defaultLocale,
+  t,
+  docsUrl,
+  versionedDocsUrl,
+  withBase,
+});