create-zudo-doc 3.1.0 → 3.3.0

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -1,165 +0,0 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Host-side body-end islands helper.
-//
-// Wave 8 (Path A — super-epic #1333 / child epic #1355) drops the local
-// SSR-skip wrapper functions in `@takazudo/zudo-doc/ssr-skip` and uses
-// zfb's native `<Island ssrFallback={...}>` API directly with the real
-// component constructors imported by the host.
-//
-// The previous indirection (page → wrapper → placeholder div) created an
-// orphan-component bug: the real components were `"use client"` modules
-// that no page module ever imported transitively, so zfb's island scanner
-// never walked page → real-component, the manifest never bound the marker
-// to the real constructor, and the bundle never contained the real
-// component body. PR #150 to zfb fixed the marker-name alignment but the
-// orphan problem stayed — see issue zudolab/zudo-doc#1355 Wave 7 report.
-//
-// This helper is the page → real-component import chain the scanner
-// needs. Each island below is composed with zfb's `<Island>` wrapper,
-// which emits `<div data-zfb-island-skip-ssr="<ComponentName>">…</div>`
-// at SSR (zfb's `captureComponentName` derives the marker from
-// `child.displayName ?? child.name`). Because the page imports this
-// file, and this file imports the real components, the scanner walks
-// page → helper → real component and registers the constructor under
-// the SSR marker name.
-//
-// Pattern mirrors `_header-with-defaults.tsx`: the JSX-shim widens
-// `Island`'s return type to `unknown`, so call-sites cast through
-// `as unknown as VNode` at the boundary.
-
-import type { VNode, JSX } from "preact";
-import { Island } from "@takazudo/zfb";
-import { settings } from "@/config/settings";
-
-import { AiChatModal } from "@takazudo/zudo-doc/ai-chat-modal";
-import { ImageEnlarge, ImageEnlargeSsrFallback } from "@takazudo/zudo-doc/image-enlarge";
-import { MermaidEnlarge, MermaidEnlargeSsrFallback } from "@takazudo/zudo-doc/mermaid-enlarge";
-// @slot:body-end-islands:imports
-
-// AiChatModal, ImageEnlarge, MermaidEnlarge pin displayName internally in the
-// package. Optional feature islands that still need explicit call-site pinning
-// inject their displayName assignment at the slot below only when selected.
-// @slot:body-end-islands:display-names
-
-/**
- * Default sr-only label rendered as the AiChatModal SSR fallback. This
- * mirrors the body-label string the deleted `AiChatModalIsland` wrapper
- * produced verbatim so assistive tech can discover the chat entrypoint
- * in the static HTML before JS hydration. English-only for now — the
- * previous default was also English-only; pass `aiChatBodyLabel` to
- * localise.
- */
-const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
-
-/** Props for {@link BodyEndIslands}. */
-export interface BodyEndIslandsProps {
-  /** Base path the AI chat modal uses to construct API URLs. */
-  basePath: string;
-  /**
-   * Sr-only label rendered as the AiChatModal SSR fallback. Defaults to
-   * the English string. Pass a locale-translated string for non-default
-   * locales so screen readers announce the chat entrypoint correctly
-   * before hydration.
-   */
-  aiChatBodyLabel?: string;
-}
-
-/**
- * The default body-end islands a doc page may mount: the AI chat modal
- * (`<dialog>` overlay) and the image-enlarge dialog (mounted lazily based
- * on viewport scan). Each is feature-gated — the AI chat modal (and its
- * sr-only landmark heading) on `settings.aiAssistant`, and image-enlarge
- * on `settings.imageEnlarge` — so a feature-off consumer ships neither the
- * island marker nor a misleading landmark (zudolab/zudo-doc#2058).
- *
- * Optional feature islands (e.g. the design token panel bootstrap) are not
- * listed here: they are injected at the body-end-islands composition
- * anchors only when their feature is selected, so a feature-off scaffold
- * carries no trace of them.
- *
- * Each island is wrapped in `<Island ssrFallback>` so the heavy
- * component is NOT evaluated server-side — they depend on
- * `dialog.showModal()`, `localStorage`, `ResizeObserver`, runtime
- * fetch, etc. The hydration runtime swaps each placeholder on the
- * client.
- *
- * When `settings.aiAssistant` is enabled, the
- * `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in the SSG
- * output so screen readers and crawlers can discover the chat section
- * landmark before JS hydration.
- */
-export function BodyEndIslands({
-  basePath,
-  aiChatBodyLabel = DEFAULT_AI_CHAT_BODY_LABEL,
-}: BodyEndIslandsProps): JSX.Element {
-  // Gated on `settings.aiAssistant` (zudolab/zudo-doc#2058): when the AI
-  // assistant feature is off, neither the AiChatModal island marker nor the
-  // sr-only "AI Assistant" landmark heading should reach the SSG output —
-  // otherwise feature-off consumers ship a dead island marker plus a
-  // misleading screen-reader landmark for a section that never hydrates.
-  // Same feature-gating pattern as the other optional body-end islands.
-  //
-  // KNOWN CAVEAT: zfb's island scanner walks the static `"use client"`
-  // import chain, so gating this JSX removes the SSR marker and heading but
-  // may NOT strip the AiChatModal bundle from the build output. Marker
-  // removal is the agreed first fix (#2058); bundle stripping is out of scope.
-  //
-  // The sr-only <p> fallback keeps the body label in static HTML for screen
-  // readers before JS hydration; sr-only keeps it invisible to sighted users.
-  const aiAssistant = settings.aiAssistant ? (
-    <>
-      {/* Emits the "AI Assistant" heading in the SSG output so screen
-          readers can discover the chat section landmark before JS
-          hydration. */}
-      <h2 class="sr-only">AI Assistant</h2>
-      {
-        Island({
-          ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
-          children: <AiChatModal basePath={basePath} />,
-        }) as unknown as VNode
-      }
-    </>
-  ) : null;
-
-  // Gated on `settings.imageEnlarge` (zudolab/zudo-doc#2058). Same caveat as
-  // the AI assistant gating: removing this JSX drops the SSR dialog shell and
-  // island marker, but the bundle may persist via the static import scan.
-  //
-  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty, closed
-  // `<dialog class="zd-enlarge-dialog ...">` shell so the dist HTML carries
-  // one dialog from the start. Without this the smoke "exactly one
-  // zd-enlarge-dialog element" assertion sees zero (skip-ssr placeholders are
-  // empty divs) and the no-JS path has no dialog at all. Hydration replaces
-  // this shell with the real ImageEnlarge component when the page goes idle.
-  const imageEnlarge = settings.imageEnlarge
-    ? (Island({
-        when: "idle",
-        ssrFallback: <ImageEnlargeSsrFallback />,
-        children: <ImageEnlarge />,
-      }) as unknown as VNode)
-    : null;
-
-  // Gated on `settings.mermaid`. Mirrors the imageEnlarge block: the SSR
-  // fallback is an empty, closed `<dialog class="zd-mermaid-dialog ...">` so
-  // the dist HTML carries one dialog from the start and hydration (when="idle")
-  // swaps in the real component. Unlike images (SSR-wrapped by the MDX paragraph
-  // override), mermaid renders client-side, so this island injects the enlarge
-  // button into each rendered diagram container itself.
-  const mermaidEnlarge = settings.mermaid
-    ? (Island({
-        when: "idle",
-        ssrFallback: <MermaidEnlargeSsrFallback />,
-        children: <MermaidEnlarge />,
-      }) as unknown as VNode)
-    : null;
-
-  return (
-    <>
-      {aiAssistant}
-      {imageEnlarge}
-      {mermaidEnlarge}
-      {/* @slot:body-end-islands:extra-islands */}
-    </>
-  );
-}

package/templates/base/pages/lib/_chrome.ts

@@ -1,167 +0,0 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Host chrome adapter — THE single host adapter for the page-chrome surface
-// (epic Collapse Wiring Shells #2420; HOSTCOLLAPSE #2427 collapsed the former
-// per-component `pages/lib/_*` chrome shells into this one module).
-//
-// It builds the host's REAL bindings ONCE and threads them through the public
-// `createChrome(routeContext, hostBindings)` builder, then re-exports the wired
-// page-chrome barrel (renderDocPage, HeaderWithDefaults, FooterWithDefaults,
-// HeadWithDefaults, composeMetaTitle, …). Every doc route + homepage chrome
-// import resolves here.
-//
-//   - the reconstructed route context comes from the retained, vitest-safe
-//     `./_route-context` seam (settings + i18n + URL/nav/slug helpers +
-//     nav-source resolvers + route enumerators), fed the host content bridge
-//     (`stableDocs`) so the content read + nav enumeration stay byte-identical;
-//   - the genuinely host-bound slots (`hostBindings`): the real SearchWidget,
-//     git-history manifest, sidebars config, frontmatter renderers/builder,
-//     footer tag loader + vocabulary, body-end islands, DocHistory island, and
-//     the showcase MDX content overrides (`mdxExtras`).
-//
-// Island-scanner contract (load-bearing): this module MUST keep the STATIC
-// imports of DocHistory (`@takazudo/zudo-doc/doc-history`), BodyEndIslands
-// (`./_body-end-islands`) and PresetGeneratorFallback (`./_preset-generator`).
-// After the collapse the only page→island import chain is
-// `pages/docs/*.tsx → _chrome.ts → {DocHistory, BodyEndIslands, PresetGenerator}`;
-// if any of these became a type-only or dynamic import the zfb island scanner
-// would stop walking it and the marker/bundle would silently drop.
-
-import type { ComponentChildren } from "preact";
-import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";
-
-import { createChrome } from "@takazudo/zudo-doc/chrome";
-
-import { settings } from "@/config/settings";
-import { defaultLocale } from "@/config/i18n";
-import { tagVocabulary } from "@/config/tag-vocabulary";
-import sidebars from "@/config/sidebars";
-import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
-import { collectTags } from "@/utils/tags";
-import { toRouteSlug } from "@/utils/slug";
-import type { DocsEntry } from "@/types/docs-entry";
-
-import { routeContext } from "./_route-context";
-import { stableDocs, memoizeDerived } from "./_nav-source-cache";
-import { mergeLocaleDocs } from "./locale-merge";
-import { SearchWidget } from "./_search-widget";
-import { BodyEndIslands as BodyEndIslandsSeam } from "./_body-end-islands";
-import { buildFrontmatterPreviewEntries } from "./_frontmatter-preview-data";
-import { DetailsWrapper } from "./_details";
-import { PresetGeneratorFallback } from "./_preset-generator";
-import { DocHistory } from "@takazudo/zudo-doc/doc-history";
-import { HtmlPreviewWrapper, type HtmlPreviewWrapperProps } from "@takazudo/zudo-doc/html-preview-wrapper";
-// SSR author + date metadata — `#doc-history-meta` is the build-time manifest
-// alias (esbuild-inlined, no fs). Static import is load-bearing for the island
-// scanner chain noted above.
-import docHistoryMeta from "#doc-history-meta";
-
-// ---------------------------------------------------------------------------
-// Footer tag loader (host-side; moved verbatim from the former
-// _footer-with-defaults.tsx). Reads collections via
-// stableDocs / memoizeDerived and aggregates tags per locale. Threaded as
-// hostBindings.loadTagsForLocale.
-// ---------------------------------------------------------------------------
-
-function loadTagsForLocale(lang: string) {
-  if (lang === defaultLocale) {
-    const baseDocs = stableDocs("docs");
-    return memoizeDerived([baseDocs], "footerTaglist;default", () => {
-      const docs: DocsEntry[] = baseDocs.filter(
-        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
-      );
-      const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-      return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-    });
-  }
-  const baseDocs = stableDocs("docs");
-  const localeDocs = stableDocs(`docs-${lang}`);
-  return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
-    const result = mergeLocaleDocs({
-      baseDocs: baseDocs.filter((d) => !d.data.draft),
-      localeDocs: localeDocs.filter((d) => !d.data.draft),
-      applyDefaultLocaleOnlyFilter: true,
-    });
-    const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
-    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-    return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Showcase MDX content overrides (host-bound; identical to the former
-// pages/_mdx-components.ts `extras` block — kept in lockstep). Threaded via
-// hostBindings.mdxExtras; the package factory merges them over its defaults.
-// ---------------------------------------------------------------------------
-
-/** MDX-tag stub: renders nothing (Preact null-vnode path). */
-const MdxStub = (_props: unknown) => null;
-
-/** SSR pass-through for `<Island when=…>` — renders children, ignores `when`. */
-function IslandWrapper(props: {
-  when?: "load" | "idle" | "visible" | "media";
-  children?: ComponentChildren;
-}): ComponentChildren {
-  return props.children ?? null;
-}
-
-const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
-  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
-
-const mdxExtras = {
-  HtmlPreview: HtmlPreviewWithGlobalConfig,
-  Details: DetailsWrapper,
-  SmartBreak: MdxStub,
-  Island: IslandWrapper,
-  PresetGenerator: PresetGeneratorFallback,
-  Avatar: MdxStub,
-  Button: MdxStub,
-  Card: MdxStub,
-  MyComponent: MdxStub,
-  PageLayout: MdxStub,
-} as unknown as Record<string, (props: Record<string, unknown>) => unknown>;
-
-// ---------------------------------------------------------------------------
-// The host's real bindings (the 10 ChromeHostBindings slots).
-// ---------------------------------------------------------------------------
-
-const hostBindings: ChromeHostBindings = {
-  SearchWidget: SearchWidget as ChromeHostBindings["SearchWidget"],
-  docHistoryMeta: docHistoryMeta as Record<string, unknown>,
-  sidebarsConfig: sidebars as unknown as Record<string, unknown>,
-  frontmatterRenderers: frontmatterRenderers as unknown as ChromeHostBindings["frontmatterRenderers"],
-  buildFrontmatterPreviewEntries:
-    buildFrontmatterPreviewEntries as unknown as ChromeHostBindings["buildFrontmatterPreviewEntries"],
-  loadTagsForLocale: loadTagsForLocale as unknown as ChromeHostBindings["loadTagsForLocale"],
-  tagVocabulary,
-  BodyEndIslands: BodyEndIslandsSeam as unknown as ChromeHostBindings["BodyEndIslands"],
-  DocHistory: DocHistory as unknown as ChromeHostBindings["DocHistory"],
-  mdxExtras: mdxExtras as ChromeHostBindings["mdxExtras"],
-};
-
-// ---------------------------------------------------------------------------
-// Build the wired page-chrome surface ONCE from the route context + real host
-// bindings, and re-export the barrel. Every omitted slot falls back to the
-// package stub (byte-identical to the injected package-routes path); each REAL
-// slot above overrides it.
-// ---------------------------------------------------------------------------
-
-const chrome = createChrome(routeContext, hostBindings);
-
-export type { RenderDocPageOptions } from "@takazudo/zudo-doc/doc-page-renderer";
-
-export const {
-  composeMetaTitle,
-  HeadWithDefaults,
-  HeaderWithDefaults,
-  FooterWithDefaults,
-  SidebarWithDefaults,
-  renderDocPage,
-  VersionsPageView,
-  collectTagMapForLocale,
-  TagDetailPageView,
-  TagsIndexPageView,
-  SiteTreeNavWrapper,
-  BodyEndIslands,
-  HomePageView,
-} = chrome;

package/templates/base/pages/lib/_details.tsx

@@ -1,29 +0,0 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Host-side MDX wrapper for <Details> — trivial passthrough to the v2
-// Details component.
-//
-// The v2 Details component accepts standard Preact children. MDX passes slot
-// content as `children`, so the mapping is direct. The title prop (default
-// "Details") is forwarded unchanged.
-
-import type { ComponentChildren, VNode } from "preact";
-import { Details as DetailsV2 } from "@takazudo/zudo-doc/details";
-
-export interface DetailsWrapperProps {
-  /** Summary label shown in the <summary> element. Defaults to "Details". */
-  title?: string;
-  /** MDX slot content rendered inside the collapsed body. */
-  children?: ComponentChildren;
-}
-
-/**
- * Passthrough wrapper for the v2 Details component.
- *
- * Used in pages/_mdx-components.ts as the Details binding so that MDX
- * content using `<Details title="...">...</Details>` renders correctly
- * on zfb routes.
- */
-export function DetailsWrapper({ title, children }: DetailsWrapperProps): VNode {
-  return <DetailsV2 title={title}>{children}</DetailsV2>;
-}

package/templates/base/pages/lib/_doc-route-entries.ts

@@ -1,10 +0,0 @@
-// Thin shim — the memoized doc-route-entry builder rides on the unified
-// ChromeContext now (epic Collapse Wiring Shells #2420, FACTORIES #2424).
-// `createRouteContext` (in _route-context.ts) assembles `buildDocRouteEntries`
-// as part of the route context; this module just re-exports it so the doc-route
-// page files keep importing it from here unchanged.
-
-export type { DocRouteEntry, BuildDocRouteEntriesArgs } from "@takazudo/zudo-doc/doc-route-entries";
-import { routeContext } from "./_route-context";
-
-export const { buildDocRouteEntries } = routeContext;

package/templates/base/pages/lib/_extract-headings.ts

@@ -1,37 +0,0 @@
-// Thin showcase wrapper around @takazudo/zudo-doc/extract-headings.
-// The package-side extractHeadings takes settings as explicit params (no
-// project singleton import). This wrapper re-reads the project settings and
-// passes them through so call sites in _doc-route-entries.ts continue to
-// call extractHeadings(body) without change.
-//
-// Moved to the package as part of the package-first migration (#2321, S4 #2327).
-
-import { settings } from "../../src/config/settings";
-export type { HeadingIdStrategy, HeadingItem } from "@takazudo/zudo-doc/extract-headings";
-export { slugify } from "@takazudo/zudo-doc/extract-headings";
-import { extractHeadings as _extractHeadings } from "@takazudo/zudo-doc/extract-headings";
-import type { HeadingItem, HeadingIdStrategy } from "@takazudo/zudo-doc/extract-headings";
-
-/**
- * Extract TOC headings from a raw MDX/markdown body, using the project's
- * configured `tocMinDepth`, `tocMaxDepth`, and `headingIdStrategy` from
- * `src/config/settings`.
- *
- * Accepts the same optional `opts` overrides as the underlying package
- * function (for tests that want to override the depth window or strategy
- * without touching the global settings).
- */
-export function extractHeadings(
-  body: string,
-  opts?: {
-    tocMinDepth?: number;
-    tocMaxDepth?: number;
-    strategy?: HeadingIdStrategy;
-  },
-): HeadingItem[] {
-  return _extractHeadings(body, {
-    tocMinDepth: opts?.tocMinDepth ?? settings.tocMinDepth,
-    tocMaxDepth: opts?.tocMaxDepth ?? settings.tocMaxDepth,
-    strategy: opts?.strategy ?? settings.headingIdStrategy,
-  });
-}

package/templates/base/pages/lib/_frontmatter-preview-data.ts

@@ -1,27 +0,0 @@
-// Host-side filter helper that turns a doc entry's `data` (frontmatter)
-// into the `entries` array expected by `<FrontmatterPreview>`.
-//
-// The v2 component (packages/zudo-doc/src/metainfo/frontmatter-preview.tsx)
-// is a pure renderer — the caller is responsible for:
-//
-//  1. Honouring `settings.frontmatterPreview === false` (block hidden everywhere).
-//  2. Removing schema-managed system keys (DEFAULT_FRONTMATTER_IGNORE_KEYS).
-//  3. Applying the host's `ignoreKeys` (replaces the default list) or
-//     `extraIgnoreKeys` (adds to the default).
-//  4. Skipping null/undefined values.
-//
-// Returning an empty array suppresses the block — the v2 component
-// short-circuits with `null` when `entries` is empty.
-//
-// Custom per-key renderers (from `src/config/frontmatter-preview-renderers.tsx`)
-// are wired by the page template directly on the `<FrontmatterPreview>` call site
-// via the `renderers` prop. This helper only produces the filtered entries array.
-
-import { createBuildFrontmatterPreviewEntries } from "@takazudo/zudo-doc/frontmatter-preview-data";
-import { settings } from "@/config/settings";
-import { DEFAULT_FRONTMATTER_IGNORE_KEYS } from "@/config/frontmatter-preview-defaults";
-
-export const buildFrontmatterPreviewEntries = createBuildFrontmatterPreviewEntries({
-  frontmatterPreview: settings.frontmatterPreview,
-  defaultIgnoreKeys: DEFAULT_FRONTMATTER_IGNORE_KEYS,
-});

package/templates/base/pages/lib/_nav-source-cache.ts

@@ -1,100 +0,0 @@
-// Snapshot-anchored memoization for nav-source arrays.
-//
-// WHY THIS EXISTS — build-time array-identity stabilization
-// --------------------------------------------------------
-// zfb's `getCollection(name)` returns a FRESH array of FRESH entry objects on
-// every call (it `.map()`s over the underlying snapshot — see
-// `node_modules/@takazudo/zfb/dist/content.js`). The doc-route `paths()`
-// functions are re-invoked once per built page (e.g. ~123× for the EN docs
-// route), and the per-page sidebar + header each re-derive their nav source
-// independently. The net effect: `buildNavTree` is called ~2× the page count
-// (~900 calls for 251 pages), and every call recomputed an O(n log n)
-// stringify+sort cache key over the entire docs collection.
-//
-// The fix anchors identity on the ONE thing stable across the whole build:
-// `getContentSnapshot().collections[name]` — the readonly snapshot array zfb
-// installs once at worker boot (verified INSTALLED during `pnpm build`,
-// collections `[docs, docs-ja, docs-v-*]`). We memoize the bridged +
-// draft-filtered arrays on that anchor (WeakMap) so every repeat caller
-// receives the SAME array instance. `buildNavTree`'s WeakMap fast-path
-// (`src/utils/docs.ts`) then short-circuits the key computation on identity,
-// collapsing ~900 key computations to the handful of distinct
-// (snapshot, locale, version, options) inputs.
-//
-// FALLBACK (no snapshot): unit tests and direct Node invocations run the
-// filesystem path with no installed snapshot. There is no stable anchor array
-// to key on, AND the underlying `getCollection(name)` result can legitimately
-// change between calls in that mode (e.g. a test swapping its mock for the same
-// collection name). So we DELIBERATELY do not memoize the no-snapshot path —
-// it computes fresh each call. The perf win targets the real build, where the
-// snapshot is always installed; correctness wins in the fallback path.
-//
-// HMR intent preserved: a content edit produces a NEW snapshot object (new
-// `collections[name]` array identity), so every memo here misses and
-// recomputes — matching the old content-keyed cache's change detection.
-//
-// PACKAGE SPLIT (epic #2344, S6):
-//   `memoizeDerived` — the generic two-level WeakMap memo — is now in the
-//   package at @takazudo/zudo-doc/nav-source-cache (no zfb imports needed).
-//   `stableDocs` stays here because it imports `getCollection` /
-//   `getContentSnapshot` from "zfb/content", which is a virtual module
-//   provided by the zfb SSG build system at compile time — not an npm package.
-
-import { getCollection, getContentSnapshot } from "zfb/content";
-import { bridgeDocsEntries, type ZfbDocsData } from "../_data";
-import type { DocPageEntry } from "./doc-page-props";
-
-// Re-export memoizeDerived from the package (pure, no zfb dep).
-export { memoizeDerived } from "@takazudo/zudo-doc/nav-source-cache";
-
-// ---------------------------------------------------------------------------
-// Snapshot anchor → stable bridged arrays
-// ---------------------------------------------------------------------------
-
-/**
- * The stable per-build anchor array for a collection: the raw readonly
- * snapshot array zfb installed once. Returns `undefined` when no snapshot is
- * installed (filesystem-fallback path) so callers take the fresh, unmemoized
- * branch.
- */
-function snapshotAnchor(name: string): readonly unknown[] | undefined {
-  return getContentSnapshot()?.collections[name];
-}
-
-// Per-anchor-array memo of the bridged + draft-filtered entries. Keyed on the
-// snapshot array identity so a new build snapshot invalidates automatically.
-const bridgedByAnchor = new WeakMap<object, DocPageEntry[]>();
-
-function buildBridged(collectionName: string): DocPageEntry[] {
-  const raw = getCollection<ZfbDocsData>(collectionName);
-  return bridgeDocsEntries(raw, collectionName).filter(
-    (d) => !d.data.draft,
-  );
-}
-
-/**
- * Identity-stable, draft-filtered `DocPageEntry[]` for a collection.
- *
- * Returns the SAME array instance on every call within one build (anchored on
- * the snapshot array), so downstream derived arrays — and ultimately
- * `buildNavTree` — can rely on reference equality. The entries carry the full
- * `DocPageEntry` shape (Content, body, module_specifier, id, collection) the
- * route `paths()` props need.
- *
- * Passed as `stableDocs` to `createNavSourceDocs` in `_nav-source-docs.ts`.
- */
-export function stableDocs(collectionName: string): DocPageEntry[] {
-  const anchor = snapshotAnchor(collectionName);
-
-  // No snapshot (fs-fallback / unit tests): compute fresh, do not memoize —
-  // see the no-snapshot rationale in the module header.
-  if (anchor === undefined) {
-    return buildBridged(collectionName);
-  }
-
-  const cached = bridgedByAnchor.get(anchor);
-  if (cached) return cached;
-  const built = buildBridged(collectionName);
-  bridgedByAnchor.set(anchor, built);
-  return built;
-}

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -1,17 +0,0 @@
-// Thin shim — nav-source resolvers ride on the unified ChromeContext now
-// (epic Collapse Wiring Shells #2420, FACTORIES #2424). The reconstructed
-// `createRouteContext` (in _route-context.ts) builds the identity-stable
-// nav-source API as part of the route context; this module just re-exports the
-// bindings so the existing call sites (route files, nav wrappers, _nav-data-prep,
-// route-enumerators) keep importing them from here unchanged.
-
-export type { NavSourceDocs, NavSourceOptions } from "@takazudo/zudo-doc/nav-source-docs";
-import { routeContext } from "./_route-context";
-
-export const {
-  resolveNavSource,
-  resolveVersionedLocaleSource,
-  loadNavSourceDocs,
-  stableMergeCategoryMeta,
-  stableNavDocs,
-} = routeContext;

package/templates/base/pages/lib/_preset-generator.tsx

@@ -1,81 +0,0 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// SSR fallback shell for the <PresetGenerator> interactive form.
-//
-// The real component (src/components/preset-generator.tsx) is a large
-// client-only island. This file is imported transitively from page modules
-// (pages/docs/[...slug].tsx → _mdx-components.ts → here), so zfb's island
-// scanner walks the static import chain and registers PresetGenerator in the
-// manifest. Without this import, the scanner never finds the component and
-// client-side hydration never fires (orphan-component problem; same root
-// cause fixed for body-end islands in _body-end-islands.tsx).
-//
-// The fallback renders all 8 section headings as static SSR HTML so:
-//   1. Screen readers and search engines see the section structure (a11y/SEO).
-//   2. Layout does not collapse to nothing while JS loads (no-JS layout).
-//   3. The scanner traces this file → preset-generator.tsx via the Island child
-//      and registers PresetGenerator in the manifest for client-side mounting.
-//
-// Uses the canonical `<Island ssrFallback>` API (zfb) so the scanner can
-// connect the import to the manifest entry and the hydration runtime can
-// mount the real form into the skip-ssr placeholder on the client.
-
-import type { VNode } from "preact";
-import { HeadingH3 } from "@takazudo/zudo-doc/content";
-import { Island } from "@takazudo/zfb";
-import PresetGenerator from "@/components/preset-generator";
-
-// Pin displayName so zfb's captureComponentName produces a stable marker
-// name even after the SSR pipeline runs through a function-name-rewriting
-// layer. Matches the data-zfb-island-skip-ssr attribute value the runtime
-// queries. Mirrors the pattern in _body-end-islands.tsx.
-(PresetGenerator as { displayName?: string }).displayName = "PresetGenerator";
-
-// Heading text for each of the 8 sections — must match the original
-// SectionHeading calls in src/components/preset-generator.tsx exactly
-// so the SSR fallback and the real component render the same section labels.
-// Order must mirror the JSX source order in preset-generator.tsx — do NOT
-// sort alphabetically. The array drives the SSR fallback heading sequence
-// shown to screen readers and visible before JS hydration.
-const SECTION_HEADINGS = [
-  "Project Name",
-  "Default Language",
-  "Color Scheme Mode",
-  "Color Scheme",
-  "Features",
-  "Header right items",
-  "Markdown Options",
-  "Package Manager",
-] as const;
-
-/**
- * Static SSR fallback for the interactive PresetGenerator form.
- *
- * Renders all 8 section headings as static HTML for a11y/SEO and no-JS
- * layout stability. Uses Island with ssrFallback so the zfb scanner traces
- * this file → preset-generator.tsx and registers the real component in the
- * island manifest for client-side mounting.
- */
-export function PresetGeneratorFallback(): VNode {
-  const fallback = (
-    <div class="zd-preset-gen-fallback">
-      {SECTION_HEADINGS.map((heading) => (
-        <section key={heading}>
-          <HeadingH3>{heading}</HeadingH3>
-        </section>
-      ))}
-    </div>
-  );
-
-  // Island with ssrFallback:
-  // - SSR emits the section headings as static HTML inside the skip-ssr div.
-  // - The scanner reads children.type = PresetGenerator → registers it in
-  //   the manifest under "PresetGenerator".
-  // - The hydration runtime mounts the real interactive form into the
-  //   skip-ssr placeholder on the client after load.
-  return Island({
-    when: "load",
-    ssrFallback: fallback,
-    children: <PresetGenerator />,
-  }) as unknown as VNode;
-}