create-zudo-doc 3.1.0 → 3.3.0

package/templates/features/i18n/files/pages/[locale]/docs/[[...slug]].tsx

@@ -0,0 +1,88 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locked manifest (#2653 Decision 4, i18n addendum): the locale-prefixed
+// counterpart of pages/docs/[[...slug]].tsx — required for the same reason
+// (injected DYNAMIC routes 404 in `zfb dev`). Self-contained: only the three
+// sanctioned package entrypoints — no `pages/lib`, no `@/config`. Mirrors
+// the package's own `routes/locale-docs-slug.tsx` shape, rebuilt from the
+// route-context payload instead of the package-internal `_context.js`.
+//
+// Per-locale content dir + fallback notice (ported from
+// packages/zudo-doc/src/routes/locale-docs-slug.tsx and the showcase's
+// pages/[locale]/docs/[[...slug]].tsx): each route carries the locale's own
+// content directory (`getLocaleConfig(locale).dir`) and an `isFallback` flag.
+// A page that only exists in the default locale is served as an untranslated
+// FALLBACK — it must (a) read doc-history from the DEFAULT-locale content dir
+// (not the translated one, which has no such file), and (b) thread
+// `isFallback` so the chrome renders the "not translated yet" notice. Dropping
+// either — as this stub previously did by hardcoding `docsDir` for every
+// locale and never passing `isFallback` — silently breaks translated pages.
+//
+// docHistory note: same as the default-locale stub — when docHistory is
+// selected, the generator patches this file too.
+
+import type { JSX } from "preact";
+import { routeContext } from "virtual:zudo-doc-route-context";
+import {
+  createRouteContext,
+  type RouteContextPayload,
+} from "@takazudo/zudo-doc/route-context";
+import { createChrome } from "@takazudo/zudo-doc/chrome";
+
+const ctx = routeContext as unknown as RouteContextPayload;
+const routeCtx = createRouteContext(ctx);
+const { renderDocPage } = createChrome(routeCtx);
+
+export const frontmatter = { title: "Docs" };
+
+export function paths(): Array<{
+  params: { locale: string; slug: string[] };
+  props: unknown;
+}> {
+  const result: Array<{
+    params: { locale: string; slug: string[] };
+    props: unknown;
+  }> = [];
+
+  for (const locale of Object.keys(routeCtx.settings.locales)) {
+    const contentDir =
+      routeCtx.getLocaleConfig(locale)?.dir ?? routeCtx.settings.docsDir;
+    const source = routeCtx.resolveNavSource(locale, undefined, {
+      applyDefaultLocaleOnlyFilter: true,
+      keepUnlisted: true,
+    });
+    for (const item of routeCtx.buildDocRouteEntries({
+      source,
+      locale,
+      routeSig: `locale-docs;${locale}`,
+    })) {
+      result.push({
+        params: { locale, slug: item.slugParams },
+        props: {
+          ...(item.props as Record<string, unknown>),
+          // Fallback pages exist only in the default locale, so their
+          // doc-history lives under the EN docsDir; translated pages read
+          // their own locale dir.
+          contentDir: item.isFallback ? routeCtx.settings.docsDir : contentDir,
+          isFallback: item.isFallback,
+        },
+      });
+    }
+  }
+
+  return result;
+}
+
+type PageArgs = {
+  params: { locale: string; slug: string[] };
+  contentDir: string;
+  isFallback: boolean;
+} & Record<string, unknown>;
+
+export default function LocaleDocsPage(props: PageArgs): JSX.Element {
+  return renderDocPage(props as never, {
+    locale: props.params.locale,
+    isFallback: props.isFallback,
+    docHistoryContentDir: props.contentDir,
+  });
+}

package/templates/features/tagGovernance/files/scripts/tags-suggest.ts

@@ -16,7 +16,9 @@ import { parseArgs } from "node:util";
 import matter from "gray-matter";
 
 import { tagVocabulary } from "../src/config/tag-vocabulary";
-import type { TagVocabularyEntry } from "../src/config/tag-vocabulary-types";
+// Minimal-scaffold cutover (epic zudolab/zudo-doc#2651): the standalone
+// `tag-vocabulary-types.ts` shim is gone — the type ships from the package.
+import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
 
 const DEFAULT_HOST = "http://localhost:11434";
 const DEFAULT_MODEL = "qwen2.5:7b";

package/dist/settings-gen.d.ts

@@ -1,2 +0,0 @@
-import type { UserChoices } from "./prompts.js";
-export declare function generateSettingsFile(choices: UserChoices): string;

package/dist/settings-gen.js

@@ -1,319 +0,0 @@
-import { capitalize, getLangLabel, getSecondaryLang } from "./utils.js";
-export function generateSettingsFile(choices) {
-    const lines = [];
-    // Import types from settings-types (copied from template src/config/)
-    lines.push(`export type {`);
-    lines.push(`  HeaderNavChildItem,`);
-    lines.push(`  HeaderNavItem,`);
-    lines.push(`  HeaderRightItem,`);
-    lines.push(`  ColorModeConfig,`);
-    lines.push(`  HtmlPreviewConfig,`);
-    lines.push(`  LocaleConfig,`);
-    lines.push(`  VersionConfig,`);
-    lines.push(`  FooterConfig,`);
-    lines.push(`  FrontmatterPreviewConfig,`);
-    lines.push(`  BodyFootUtilAreaConfig,`);
-    lines.push(`  TagPlacement,`);
-    lines.push(`  TagGovernanceMode,`);
-    lines.push(`  TagVocabularyEntry,`);
-    lines.push(`  MetaTagsConfig,`);
-    lines.push(`} from "./settings-types";`);
-    lines.push(`import type {`);
-    lines.push(`  HeaderNavItem,`);
-    lines.push(`  HeaderRightItem,`);
-    lines.push(`  ColorModeConfig,`);
-    lines.push(`  HtmlPreviewConfig,`);
-    lines.push(`  LocaleConfig,`);
-    lines.push(`  VersionConfig,`);
-    lines.push(`  FooterConfig,`);
-    lines.push(`  FrontmatterPreviewConfig,`);
-    lines.push(`  BodyFootUtilAreaConfig,`);
-    lines.push(`  TagPlacement,`);
-    lines.push(`  TagGovernanceMode,`);
-    lines.push(`  MetaTagsConfig,`);
-    lines.push(`} from "./settings-types";`);
-    lines.push(``);
-    lines.push(`export const settings = {`);
-    if (choices.colorSchemeMode === "single") {
-        lines.push(`  colorScheme: ${JSON.stringify(choices.singleScheme ?? "Default Dark")},`);
-        lines.push(`  colorMode: false as ColorModeConfig | false,`);
-    }
-    else {
-        lines.push(`  colorScheme: ${JSON.stringify(choices.darkScheme ?? "Default Dark")},`);
-        lines.push(`  colorMode: {`);
-        lines.push(`    defaultMode: ${JSON.stringify(choices.defaultMode ?? "dark")},`);
-        lines.push(`    lightScheme: ${JSON.stringify(choices.lightScheme ?? "Default Light")},`);
-        lines.push(`    darkScheme: ${JSON.stringify(choices.darkScheme ?? "Default Dark")},`);
-        lines.push(`    respectPrefersColorScheme: ${choices.respectPrefersColorScheme ?? true},`);
-        lines.push(`  } satisfies ColorModeConfig as ColorModeConfig | false,`);
-    }
-    lines.push(`  siteName: ${JSON.stringify(capitalize(choices.projectName.replace(/-/g, " ")))},`);
-    lines.push(`  siteDescription: "" as string,`);
-    lines.push(`  base: "/",`);
-    lines.push(`  trailingSlash: false as boolean,`);
-    lines.push(`  noindex: ${choices.features.includes("noindex")} as boolean,`);
-    lines.push(`  editUrl: false as string | false,`);
-    const rawGithubUrl = (choices.githubUrl ?? "").trim();
-    if (rawGithubUrl) {
-        lines.push(`  githubUrl: ${JSON.stringify(rawGithubUrl)} as string | false,`);
-    }
-    else {
-        lines.push(`  githubUrl: false as string | false,`);
-    }
-    lines.push(`  siteUrl: "" as string,`);
-    lines.push(`  metaTags: {`);
-    if (choices.metaTags) {
-        const mt = choices.metaTags;
-        lines.push(`    description: ${mt.description !== undefined ? mt.description : true},`);
-        lines.push(`    keywords: ${mt.keywords !== undefined ? JSON.stringify(mt.keywords) : false},`);
-        lines.push(`    ogImage: ${mt.ogImage !== undefined ? JSON.stringify(mt.ogImage) : false},`);
-        lines.push(`    ogSiteName: ${mt.ogSiteName !== undefined ? mt.ogSiteName : true},`);
-        if (mt.twitterCard) {
-            lines.push(`    twitterCard: ${JSON.stringify(mt.twitterCard)},`);
-            if (mt.twitterSite) {
-                lines.push(`    twitterSite: ${JSON.stringify(mt.twitterSite)},`);
-            }
-            if (mt.twitterCreator) {
-                lines.push(`    twitterCreator: ${JSON.stringify(mt.twitterCreator)},`);
-            }
-        }
-        else {
-            lines.push(`    twitterCard: false,`);
-        }
-    }
-    else {
-        lines.push(`    description: true,`);
-        lines.push(`    keywords: false,`);
-        lines.push(`    ogImage: false,`);
-        lines.push(`    ogSiteName: true,`);
-        lines.push(`    twitterCard: false,`);
-    }
-    lines.push(`  } satisfies MetaTagsConfig as MetaTagsConfig,`);
-    lines.push(`  docsDir: "src/content/docs",`);
-    lines.push(`  defaultLocale: ${JSON.stringify(choices.defaultLang ?? "en")} as const,`);
-    if (choices.features.includes("i18n")) {
-        const secondaryLang = getSecondaryLang(choices.defaultLang);
-        const secondaryLabel = getLangLabel(secondaryLang);
-        lines.push(`  locales: {`);
-        lines.push(`    ${secondaryLang}: { label: ${JSON.stringify(secondaryLabel)}, dir: "src/content/docs-${secondaryLang}" },`);
-        lines.push(`  } satisfies Record<string, LocaleConfig>,`);
-    }
-    else {
-        // `as`, not `satisfies`: satisfies keeps the inferred type at literal {},
-        // so Object.entries(settings.locales) in the generated zfb.config.ts
-        // yields unknown values and `zfb check` fails with TS18046 (#2053).
-        lines.push(`  locales: {} as Record<string, LocaleConfig>,`);
-    }
-    // mermaid is controlled by the markdown.features block in zfb.config.ts
-    // (zfb next.12+). This field is retained for compatibility with framework
-    // components that still read settings.mermaid. See the markdown.features
-    // block in the generated zfb.config.ts for the canonical opt-in.
-    lines.push(`  mermaid: true,`);
-    lines.push(`  sitemap: false,`);
-    lines.push(`  docMetainfo: false,`);
-    lines.push(`  docTags: ${choices.features.includes("docTags")},`);
-    lines.push(`  tagPlacement: "after-title" as TagPlacement,`);
-    if (choices.features.includes("tagGovernance")) {
-        lines.push(`  tagGovernance: "warn" as TagGovernanceMode,`);
-        lines.push(`  tagVocabulary: true as boolean,`);
-    }
-    else {
-        lines.push(`  tagGovernance: "off" as TagGovernanceMode,`);
-        lines.push(`  tagVocabulary: false as boolean,`);
-    }
-    // Default false — fresh scaffolds typically don't need live frontmatter preview;
-    // users opt in once they're ready to wire up the preview panel.
-    lines.push(`  frontmatterPreview: false as FrontmatterPreviewConfig | false,`);
-    if (choices.features.includes("llmsTxt")) {
-        lines.push(`  llmsTxt: true,`);
-    }
-    else {
-        lines.push(`  llmsTxt: false,`);
-    }
-    lines.push(`  changelogs: false,`);
-    lines.push(`  math: false,`);
-    lines.push(`  cjkFriendly: ${choices.cjkFriendly ?? false} as boolean,`);
-    lines.push(`  onBrokenMarkdownLinks: "warn" as "warn" | "error" | "ignore",`);
-    lines.push(`  aiAssistant: false as boolean,`);
-    // When the user wires up `pages/api/ai-chat.tsx` (not shipped in any
-    // scaffold variant — W6A spec-lock Decision 5), this toggle short-circuits
-    // the endpoint with a fixed "disabled" reply. Default `false` here — the
-    // showcase ships with `true` because it deploys without an Anthropic key,
-    // but a fresh scaffold has `aiAssistant: false` and the user only enables
-    // the chat once they're wiring up a real `ANTHROPIC_API_KEY`. Defaulting
-    // demo mode off avoids silently disabling chat for them.
-    lines.push(`  aiChatDemoMode: false as boolean,`);
-    lines.push(`  aiChatAllowedOrigins: [] as string[],`);
-    lines.push(`  aiChatGlobalDailyLimit: false as number | false,`);
-    if (choices.features.includes("docHistory")) {
-        lines.push(`  docHistory: true,`);
-    }
-    else {
-        lines.push(`  docHistory: false,`);
-    }
-    // Package-owned route injection is on by default since the fast-follow (#2372).
-    // Generated projects include the field explicitly so settings.ts stays in sync
-    // with src/config/settings.ts (checked by check-fixture-settings-drift.mjs).
-    lines.push(`  packageOwnedRoutes: true,`);
-    if (choices.features.includes("bodyFootUtil")) {
-        lines.push(`  bodyFootUtilArea: {`);
-        lines.push(`    docHistory: ${choices.features.includes("docHistory")},`);
-        lines.push(`    viewSourceLink: ${Boolean(rawGithubUrl)},`);
-        lines.push(`  } satisfies BodyFootUtilAreaConfig as BodyFootUtilAreaConfig | false,`);
-    }
-    else {
-        lines.push(`  bodyFootUtilArea: false as BodyFootUtilAreaConfig | false,`);
-    }
-    if (choices.features.includes("designTokenPanel")) {
-        lines.push(`  designTokenPanel: true as boolean,`);
-    }
-    else {
-        lines.push(`  designTokenPanel: false as boolean,`);
-    }
-    lines.push(`  tocMinDepth: 2 as number,`);
-    lines.push(`  tocMaxDepth: 4 as number,`);
-    // Heading-ID (anchor) strategy — single source of truth shared by
-    // zfb.config.ts (markdown.features.headingIds) and the host TOC builder
-    // (pages/lib/_extract-headings.ts). "hierarchical" emits ancestor-prefixed
-    // anchors (foo / foo-moo / foo-moo-mew); "flat" is zfb's legacy scheme.
-    // Default to "hierarchical": safe for greenfield (no existing deep links to
-    // break) and the recommended scheme (upstream zfb#871).
-    lines.push(`  headingIdStrategy: "hierarchical" as "flat" | "hierarchical",`);
-    if (choices.features.includes("sidebarResizer")) {
-        lines.push(`  sidebarResizer: true as boolean,`);
-    }
-    else {
-        lines.push(`  sidebarResizer: false as boolean,`);
-    }
-    if (choices.features.includes("sidebarToggle")) {
-        lines.push(`  sidebarToggle: true as boolean,`);
-    }
-    else {
-        lines.push(`  sidebarToggle: false as boolean,`);
-    }
-    if (choices.features.includes("imageEnlarge")) {
-        lines.push(`  imageEnlarge: true as boolean,`);
-    }
-    else {
-        lines.push(`  imageEnlarge: false as boolean,`);
-    }
-    if (choices.features.includes("dynamicPageTransition")) {
-        lines.push(`  dynamicPageTransition: true as boolean,`);
-    }
-    else {
-        lines.push(`  dynamicPageTransition: false as boolean,`);
-    }
-    lines.push(`  htmlPreview: undefined as HtmlPreviewConfig | undefined,`);
-    if (choices.features.includes("versioning")) {
-        lines.push(`  versions: [] satisfies VersionConfig[] as VersionConfig[] | false,`);
-    }
-    else {
-        lines.push(`  versions: false as VersionConfig[] | false,`);
-    }
-    if (choices.features.includes("claudeResources")) {
-        lines.push(`  claudeResources: {`);
-        lines.push(`    claudeDir: ".claude",`);
-        lines.push(`  } as { claudeDir: string; projectRoot?: string; scanRoot?: string } | false,`);
-    }
-    else {
-        lines.push(`  claudeResources: false as { claudeDir: string; projectRoot?: string; scanRoot?: string } | false,`);
-    }
-    if (choices.features.includes("claudeResources")) {
-        lines.push(`  defaultLocaleOnlyPrefixes: [`);
-        lines.push(`    "/docs/claude-md/",`);
-        lines.push(`    "/docs/claude-skills/",`);
-        lines.push(`    "/docs/claude-agents/",`);
-        lines.push(`    "/docs/claude-commands/",`);
-        lines.push(`  ] as string[],`);
-    }
-    else {
-        lines.push(`  defaultLocaleOnlyPrefixes: [] as string[],`);
-    }
-    if (choices.features.includes("footerNavGroup") ||
-        choices.features.includes("footerCopyright") ||
-        choices.features.includes("footerTaglist")) {
-        lines.push(`  footer: {`);
-        if (choices.features.includes("footerNavGroup")) {
-            lines.push(`    links: [`);
-            lines.push(`      {`);
-            lines.push(`        title: "Docs",`);
-            lines.push(`        items: [`);
-            lines.push(`          { label: "Getting Started", href: "/docs/getting-started" },`);
-            lines.push(`        ],`);
-            lines.push(`      },`);
-            lines.push(`    ],`);
-        }
-        else {
-            lines.push(`    links: [],`);
-        }
-        if (choices.features.includes("footerCopyright")) {
-            lines.push(`    copyright: "Copyright © ${new Date().getFullYear()} Your Name. Built with zudo-doc.",`);
-        }
-        if (choices.features.includes("footerTaglist")) {
-            lines.push(`    taglist: {`);
-            lines.push(`      enabled: true,`);
-            lines.push(`      groupBy: "group",`);
-            lines.push(`    },`);
-        }
-        lines.push(`  } satisfies FooterConfig as FooterConfig | false,`);
-    }
-    else {
-        lines.push(`  footer: false as FooterConfig | false,`);
-    }
-    lines.push(`  headerNav: [`);
-    lines.push(`    { label: "Getting Started", path: "/docs/getting-started", categoryMatch: "getting-started" },`);
-    // The "claude" categoryMatch is load-bearing beyond the header link: getCategoryOrder()
-    // derives the satellite-grouping prefixes from headerNav, so without this entry
-    // groupSatelliteNodes() never nests claude-md/claude-skills/... under the "claude"
-    // overview node and they spread out as separate top-level cards on the index sitemap.
-    if (choices.features.includes("claudeResources")) {
-        lines.push(`    { label: "Claude", path: "/docs/claude", categoryMatch: "claude" },`);
-    }
-    if (choices.features.includes("changelog")) {
-        lines.push(`    { label: "Changelog", path: "/docs/changelog", categoryMatch: "changelog" },`);
-    }
-    lines.push(`  ] satisfies HeaderNavItem[] as HeaderNavItem[],`);
-    lines.push(`  headerRightItems: [`);
-    if (choices.headerRightItems !== undefined) {
-        // User-supplied override (including empty array): emit each entry verbatim,
-        // in the chosen order. An empty array means "no header-right items" — honor it.
-        // DEFENSIVE STRIP: drop any "design-token-panel" trigger when the
-        // designTokenPanel feature is off — the type "design-token-panel" is absent
-        // from HeaderRightTriggerName in a feature-off scaffold (gated via
-        // @slot:settings-types:trigger-names), so emitting it would cause a TS error
-        // (zudolab/zudo-doc#2162).
-        for (const item of choices.headerRightItems) {
-            if (item.type === "trigger" &&
-                item.trigger === "design-token-panel" &&
-                !choices.features.includes("designTokenPanel")) {
-                continue;
-            }
-            if (item.type === "trigger") {
-                lines.push(`    { type: "trigger", trigger: ${JSON.stringify(item.trigger)} },`);
-            }
-            else {
-                lines.push(`    { type: "component", component: ${JSON.stringify(item.component)} },`);
-            }
-        }
-    }
-    else {
-        // Default fallback: hardcoded order, gated on selected features.
-        if (choices.features.includes("designTokenPanel")) {
-            lines.push(`    { type: "trigger", trigger: "design-token-panel" },`);
-        }
-        if (choices.features.includes("versioning")) {
-            lines.push(`    { type: "component", component: "version-switcher" },`);
-        }
-        lines.push(`    { type: "component", component: "github-link" },`);
-        lines.push(`    { type: "component", component: "theme-toggle" },`);
-        if (choices.features.includes("search")) {
-            lines.push(`    { type: "component", component: "search" },`);
-        }
-        if (choices.features.includes("i18n")) {
-            lines.push(`    { type: "component", component: "language-switcher" },`);
-        }
-    }
-    lines.push(`  ] satisfies HeaderRightItem[] as HeaderRightItem[],`);
-    lines.push(`};`);
-    return lines.join("\n") + "\n";
-}

package/templates/base/.htmlvalidate.json

@@ -1,5 +0,0 @@
-{
-  "rules": {
-    "element-permitted-content": "error"
-  }
-}

package/templates/base/.zfb/doc-history-meta.json

@@ -1 +0,0 @@
-{}

package/templates/base/pages/_data.ts

@@ -1,160 +0,0 @@
-// pages/_data.ts — zfb-compatible data helpers for doc page modules.
-//
-// Provides the bridge between zfb's CollectionEntry (from "zfb/content") and
-// the utility functions in @/utils/docs that expect DocsEntry (which carries
-// an `id` field mirroring Astro's collection entry id).
-//
-// Sync convention (ADR-004):
-//   getCollection() resolves from the pre-loaded ContentSnapshot without an
-//   async boundary. paths() exports call getDocs() without await. The Promise
-//   wrapper on the type is a v0 artefact — the synchronous snapshot path is
-//   the production contract.
-
-import { getCollection } from "zfb/content";
-import type { CollectionEntry } from "zfb/content";
-import type { DocsData } from "@/config/docs-schema";
-import type { DocsEntry } from "@/types/docs-entry";
-import type { DocPageEntry } from "./lib/doc-page-props";
-import { toRouteSlug } from "@/utils/slug";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * Frontmatter shape shared by all docs collections (EN, locale, versioned).
- *
- * Re-exported alias for `DocsData` (the `z.infer`-derived type from
- * `src/config/docs-schema.ts`) so call sites that import `ZfbDocsData` from
- * `pages/_data` continue to work without changes.
- *
- * The `[key: string]: unknown` index signature comes from `.passthrough()` on
- * the zod schema — custom frontmatter keys remain accessible downstream (e.g.
- * for frontmatter-preview) without extra casting.
- */
-export type ZfbDocsData = DocsData;
-
-/**
- * zfb collection entry augmented with the `id` and `collection` fields that
- * @/utils/docs utility functions (buildNavTree, buildBreadcrumbs, …) expect
- * from DocsEntry.
- *
- * `id` is bridged from `slug` — in Astro, `id` was the file-path identifier
- * (e.g. "getting-started/intro"); in zfb, the same role is played by `slug`.
- * Mapping them keeps the utility functions working without modification.
- */
-export type ZfbDocsEntry = CollectionEntry<ZfbDocsData> & {
-  /** Bridged from `slug` for @/utils/docs compat. */
-  id: string;
-  /** Collection name, e.g. "docs", "docs-ja", "docs-v-1.0". */
-  collection: string;
-};
-
-// ---------------------------------------------------------------------------
-// Loaders
-// ---------------------------------------------------------------------------
-
-/**
- * Load docs from a named collection synchronously (ADR-004 sync contract).
- *
- * `getCollection` resolves from the ContentSnapshot when called inside a
- * paths() evaluation. The `as unknown as` cast converts the nominal Promise
- * wrapper to a plain array — safe because the snapshot path is synchronous.
- *
- * The returned entries include:
- *   - All CollectionEntry fields (slug, data, body, module_specifier, Content)
- *   - `id` — same value as `slug`, for @/utils/docs compat
- *   - `collection` — the collection name, for DocsEntry compat
- */
-export function getDocs(collectionName: string): ZfbDocsEntry[] {
-  const entries = getCollection<ZfbDocsData>(collectionName);
-  return entries.map((e) => ({
-    ...e,
-    // Astro-compat: strip a trailing `/index` from the entry id so
-    // `getting-started/index.mdx` → id "getting-started" (matching
-    // Astro 5's `glob()` collection loader). Downstream nav helpers
-    // (`buildNavTree`, `buildBreadcrumbs`, …) keyed off the stripped
-    // form long before zfb existed; emitting the unstripped slug here
-    // produces ambiguous-URL collisions at paths()-expansion time.
-    id: stripIndexSuffix(e.slug),
-    collection: collectionName,
-  }));
-}
-
-// The `id` field bridged onto every entry is the canonical route slug, so it
-// routes through the one shared rule (`toRouteSlug` in @/utils/slug) — bare
-// root `index` → "" (URL /docs/), nested `x/index` → "x". Previously this was
-// a standalone copy of the strip logic (the lone "" dissenter of the five
-// index-stripping sites); consolidating it here means there is one source of
-// truth. See @/utils/slug for the canonical-root rationale (#1891 / #1873).
-function stripIndexSuffix(slug: string): string {
-  return toRouteSlug(slug);
-}
-
-/**
- * Augment a raw zfb collection result with the Astro-style
- * `id`/`collection` fields that downstream `@/utils/docs` helpers
- * (and the `DocPageEntry` extender shape used by `[...slug].tsx`
- * pages) expect. Use this when a page needs a typed array more
- * specific than `DocsEntry` — pages that only need `DocsEntry[]`
- * can use [`loadDocs`] / [`getDocs`] directly.
- */
-export function bridgeEntries<T = ZfbDocsData>(
-  entries: ReadonlyArray<CollectionEntry<T>>,
-  collectionName: string,
-): Array<CollectionEntry<T> & { id: string; collection: string }> {
-  return entries.map((e) => ({
-    ...e,
-    id: stripIndexSuffix(e.slug),
-    collection: collectionName,
-  }));
-}
-
-/**
- * Typed bridge from a raw zfb collection result to `DocPageEntry[]`.
- *
- * This is the **single, justified** cast at the zfb/DocsEntry boundary.
- * `CollectionEntry<ZfbDocsData> & { id, collection }` structurally satisfies
- * `DocPageEntry` because:
- *   - `id` and `collection` are added by `bridgeEntries`
- *   - `data` (ZfbDocsData) structurally satisfies `DocsEntry.data` (all
- *     required/optional fields are present; the index signature is wider)
- *   - `body`, `slug`, `module_specifier`, `Content` are provided by
- *     `CollectionEntry<ZfbDocsData>`
- * The plain `as DocPageEntry[]` (not `as unknown as`) is intentional — it
- * expresses that this is a well-understood structural subtype relationship,
- * not an escape from the type system. The zfb type is the source of truth;
- * DocsEntry/DocPageEntry are local compatibility shapes for @/utils/docs.
- */
-export function bridgeDocsEntries(
-  entries: ReadonlyArray<CollectionEntry<ZfbDocsData>>,
-  collectionName: string,
-): DocPageEntry[] {
-  return bridgeEntries(entries, collectionName) as DocPageEntry[];
-}
-
-/**
- * One-shot helper for paths()/render-time pages that just need a
- * `DocsEntry[]` for `@/utils/docs` consumption — wraps `getDocs` so
- * call sites stay one-line. Use this from any page that previously did
- * `getCollection("docs") as unknown as DocsEntry[]` — that idiom
- * silently dropped the `id`/`collection` fields the utility helpers
- * read, which threw `Cannot read properties of undefined` at runtime.
- *
- * `ZfbDocsEntry` structurally satisfies `DocsEntry`: it carries `id`,
- * `collection`, `data` (ZfbDocsData satisfies DocsEntry.data field-for-
- * field), `body`, plus the zfb-specific extras (`slug`, `Content`, etc.)
- * that DocsEntry does not require.
- */
-export function loadDocs(collectionName: string): DocsEntry[] {
-  return getDocs(collectionName);
-}
-
-/**
- * Filter out draft entries.
- * Drafts are always excluded in static-build paths() context.
- */
-export function filterDrafts(entries: ZfbDocsEntry[]): ZfbDocsEntry[] {
-  return entries.filter((e) => !e.data.draft);
-}
-