@takazudo/zudo-doc 0.2.22 → 1.0.0

package/routes-src/_context.ts

@@ -0,0 +1,314 @@
+// routes/_context — the route-context reconstruction seam (epic Package-First
+// Finale #2356, A1 #2361; ADR docs/adr/route-injection-seam.md, Decision 1).
+//
+// Every package route entrypoint imports `{ routeContext }` from the virtual
+// module `virtual:zudo-doc-route-context` (SERIALIZABLE DATA ONLY: `settings`,
+// `translations`, `tagVocabulary`) and rebuilds the full injected context by
+// calling the ALREADY-EXISTING package factories with importable package
+// subpaths — never raw host functions, never `@/` aliases. This module does
+// that reconstruction ONCE and exposes the wired runtime context so each
+// entrypoint stays a thin `paths()` + default-export shell (mirroring the kept
+// `pages/*.tsx` stubs).
+//
+// The host-dep → package-subpath map this wires (ADR table):
+//   buildNavTree/collectAutoIndexNodes/groupSatelliteNodes/isNavVisible/
+//     findNode/firstRoutedHref/buildBreadcrumbs ... ./routes/_docs-helpers
+//     (the package `docs` helpers, on `@takazudo/zudo-doc/sidebar-tree`)
+//   loadCategoryMeta ........................... @takazudo/zudo-doc/sidebar-tree
+//   extractHeadings ............................ @takazudo/zudo-doc/extract-headings
+//   toRouteSlug/toSlugParams/toTitleCase/toHistorySlug ... @takazudo/zudo-doc/slug
+//   resolveTag / collectTags ................... @takazudo/zudo-doc/tag-helpers
+//   getNavSectionForSlug/getNavSubtree/getCategoryOrder .. @takazudo/zudo-doc/nav-scope
+//   url helpers ................................ @takazudo/zudo-doc/url-helpers
+//   mergeLocaleDocs ............................ @takazudo/zudo-doc/locale-merge
+//   stableDocs (content bridge) ................ ./routes/_docs-helpers (zfb/content)
+//   resolveNavSource/… ......................... @takazudo/zudo-doc/nav-source-docs
+//   buildDocRouteEntries ....................... @takazudo/zudo-doc/doc-route-entries
+//   route enumeration .......................... @takazudo/zudo-doc/route-enumerators
+//   i18n (t/getLocaleLabel/defaultLocale/locales) reconstructed from settings +
+//     translations as a FactoryI18n.
+
+// Virtual module, resolved by the routes plugin at build via
+// addVirtualModule("virtual:zudo-doc-route-context", …). Not present on disk;
+// the package ships ambient typings for it (routes/_virtual.d.ts).
+import { routeContext } from "virtual:zudo-doc-route-context";
+
+import type { Settings } from "@takazudo/zudo-doc/settings";
+import type { FactoryI18n } from "@takazudo/zudo-doc/factory-context";
+import { makeUrlHelpers, type UrlHelpers } from "@takazudo/zudo-doc/url-helpers";
+import {
+  loadCategoryMeta,
+  type CategoryMeta,
+} from "@takazudo/zudo-doc/sidebar-tree";
+import { extractHeadings as extractHeadingsBase } from "@takazudo/zudo-doc/extract-headings";
+import { toRouteSlug, toSlugParams } from "@takazudo/zudo-doc/slug";
+import { resolveTag, type TagVocabularyEntry } from "@takazudo/zudo-doc/tag-helpers";
+import {
+  getCategoryOrder as getCategoryOrderBase,
+  getNavSectionForSlug as getNavSectionForSlugBase,
+  getNavSubtree as getNavSubtreeBase,
+} from "@takazudo/zudo-doc/nav-scope";
+import { mergeLocaleDocs } from "@takazudo/zudo-doc/locale-merge";
+import {
+  createNavSourceDocs,
+  type NavSourceDocsAPI,
+} from "@takazudo/zudo-doc/nav-source-docs";
+import {
+  createDocRouteEntries,
+  type DocRouteEntriesAPI,
+} from "@takazudo/zudo-doc/doc-route-entries";
+import {
+  createRouteEnumerators,
+  type RouteEnumeratorsAPI,
+  type DocsEntryForTags,
+  type TagInfoForEnum,
+} from "@takazudo/zudo-doc/route-enumerators";
+import type { DocNavNode, DocPageEntry } from "@takazudo/zudo-doc/doc-page-props";
+import type { HeadingItem } from "@takazudo/zudo-doc/extract-headings";
+import {
+  stableDocs,
+  isNavVisible,
+  buildNavTree,
+  buildBreadcrumbs,
+  collectAutoIndexNodes,
+  groupSatelliteNodes,
+  findNode,
+  firstRoutedHref,
+} from "./_docs-helpers.js";
+
+// ---------------------------------------------------------------------------
+// The serializable route-context payload (re-exported for entrypoints).
+// ---------------------------------------------------------------------------
+
+export interface RouteContextPayload {
+  settings: Settings;
+  translations: Record<string, Record<string, string>>;
+  tagVocabulary: readonly TagVocabularyEntry[];
+}
+
+/** The serializable route-context (from the virtual module). */
+export const ctx = routeContext as unknown as RouteContextPayload;
+export const settings: Settings = ctx.settings;
+const translations = ctx.translations;
+const tagVocabulary = ctx.tagVocabulary;
+
+// ---------------------------------------------------------------------------
+// i18n — reconstruct a FactoryI18n from settings + translations (Decision 1).
+// ---------------------------------------------------------------------------
+
+export const defaultLocale: string = settings.defaultLocale;
+export const locales: readonly string[] = [
+  defaultLocale,
+  ...Object.keys(settings.locales),
+];
+
+export function getLocaleConfig(locale: string): { label: string; dir: string } | undefined {
+  return (settings.locales as Record<string, { label: string; dir: string } | undefined>)[locale];
+}
+
+export function getLocaleLabel(locale: string): string {
+  if (locale === defaultLocale) return defaultLocale.toUpperCase();
+  return getLocaleConfig(locale)?.label ?? locale.toUpperCase();
+}
+
+export function t(key: string, locale: string = defaultLocale): string {
+  return translations[locale]?.[key] ?? translations[defaultLocale]?.[key] ?? key;
+}
+
+export const i18n: FactoryI18n = {
+  defaultLocale,
+  locales,
+  getLocaleLabel,
+  t,
+};
+
+// ---------------------------------------------------------------------------
+// URL helpers (@takazudo/zudo-doc/url-helpers).
+// ---------------------------------------------------------------------------
+
+export const urlHelpers: UrlHelpers = makeUrlHelpers(settings, i18n);
+export const {
+  withBase,
+  stripBase,
+  docsUrl,
+  versionedDocsUrl,
+  navHref,
+  isDefaultLocaleOnlyPath,
+  absoluteUrl,
+  isExternal,
+  resolveHref,
+  buildLocaleLinks,
+} = urlHelpers;
+
+// ---------------------------------------------------------------------------
+// nav-scope (@takazudo/zudo-doc/nav-scope) — parameterized by settings.headerNav.
+// ---------------------------------------------------------------------------
+
+export function getCategoryOrder(): string[] {
+  return getCategoryOrderBase(settings.headerNav);
+}
+export function getNavSectionForSlug(slug: string): string | undefined {
+  return getNavSectionForSlugBase(slug, settings.headerNav);
+}
+export function getNavSubtree(tree: DocNavNode[], categoryMatch?: string): DocNavNode[] {
+  return getNavSubtreeBase(tree, categoryMatch, settings.headerNav);
+}
+
+// ---------------------------------------------------------------------------
+// extract-headings — bound to settings depth window + id strategy.
+// ---------------------------------------------------------------------------
+
+export function extractHeadings(body: string): HeadingItem[] {
+  return extractHeadingsBase(body, {
+    tocMinDepth: settings.tocMinDepth,
+    tocMaxDepth: settings.tocMaxDepth,
+    strategy: settings.headingIdStrategy,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// tag-helpers — collectTags reconstructed package-side (the host version lives
+// in src/utils/tags.ts because it depends on the host DocsEntry; here it is
+// parameterized by the virtual-module tagVocabulary + settings.tagGovernance).
+// ---------------------------------------------------------------------------
+
+export interface TagInfo {
+  tag: string;
+  count: number;
+  docs: { slug: string; title: string; description?: string }[];
+}
+
+function getVocab(): readonly TagVocabularyEntry[] | false {
+  return settings.tagVocabulary ? tagVocabulary : false;
+}
+
+export function resolveTagBound(raw: string) {
+  return resolveTag(raw, getVocab(), settings.tagGovernance);
+}
+
+export function collectTags(
+  entries: ReadonlyArray<{ id: string; data: { slug?: string; title?: string; description?: string; tags?: string[] } }>,
+  slugFn: (id: string, data: { slug?: string }) => string,
+): Map<string, TagInfo> {
+  const tagMap = new Map<string, TagInfo>();
+  for (const entry of entries) {
+    const rawTags = entry.data.tags ?? [];
+    const slug = slugFn(entry.id, entry.data);
+    const seen = new Set<string>();
+    for (const raw of rawTags) {
+      const resolved = resolveTagBound(raw);
+      if (resolved.deprecated) continue;
+      if (seen.has(resolved.canonical)) continue;
+      seen.add(resolved.canonical);
+      if (!tagMap.has(resolved.canonical)) {
+        tagMap.set(resolved.canonical, { tag: resolved.canonical, count: 0, docs: [] });
+      }
+      const info = tagMap.get(resolved.canonical)!;
+      info.count++;
+      info.docs.push({
+        slug,
+        title: entry.data.title ?? "",
+        description: entry.data.description,
+      });
+    }
+  }
+  return tagMap;
+}
+
+// ---------------------------------------------------------------------------
+// Nav-source resolver (@takazudo/zudo-doc/nav-source-docs).
+// ---------------------------------------------------------------------------
+
+const navSourceDocs: NavSourceDocsAPI = createNavSourceDocs({
+  defaultLocale,
+  docsDir: settings.docsDir,
+  getVersions: () => settings.versions,
+  getLocaleConfig,
+  loadCategoryMeta: loadCategoryMeta as (dir: string) => Map<string, CategoryMeta>,
+  isNavVisible,
+  isDefaultLocaleOnlyPath,
+  stableDocs,
+});
+
+export const {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs,
+} = navSourceDocs;
+
+// ---------------------------------------------------------------------------
+// doc-route-entries (@takazudo/zudo-doc/doc-route-entries).
+// ---------------------------------------------------------------------------
+
+const docRouteEntries: DocRouteEntriesAPI = createDocRouteEntries({
+  buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) =>
+    buildNavTree(
+      docs,
+      locale,
+      categoryMeta as Map<string, CategoryMeta>,
+      (slug, loc) => docsUrl(slug, loc),
+    ),
+  buildBreadcrumbs: (tree: DocNavNode[], slug: string, locale: string, urlFor?: (slug: string) => string) =>
+    buildBreadcrumbs(
+      tree,
+      slug,
+      locale === defaultLocale ? withBase("/") : withBase(`/${locale}/`),
+      urlFor,
+    ),
+  collectAutoIndexNodes,
+  getNavSectionForSlug,
+  getNavSubtree,
+  toRouteSlug,
+  toSlugParams,
+  extractHeadings,
+});
+
+export const { buildDocRouteEntries } = docRouteEntries;
+
+// ---------------------------------------------------------------------------
+// route-enumerators (@takazudo/zudo-doc/route-enumerators).
+// ---------------------------------------------------------------------------
+
+const routeEnumerators: RouteEnumeratorsAPI = createRouteEnumerators({
+  defaultLocale,
+  getLocaleKeys: () => Object.keys(settings.locales),
+  getVersions: () => settings.versions,
+  getDocTags: () => settings.docTags,
+  docsUrl,
+  versionedDocsUrl,
+  withBase,
+  loadDocs: (collectionName: string) => stableDocs(collectionName) as unknown as DocsEntryForTags[],
+  isDefaultLocaleOnlyPath,
+  collectTags: (docs: DocsEntryForTags[], slugFn): Map<string, TagInfoForEnum> =>
+    collectTags(docs as unknown as Array<{ id: string; data: { slug?: string; title?: string; description?: string; tags?: string[] } }>, slugFn) as unknown as Map<string, TagInfoForEnum>,
+  toRouteSlug,
+  buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) =>
+    buildNavTree(docs, locale, categoryMeta as Map<string, CategoryMeta>, (slug, loc) => docsUrl(slug, loc)),
+  collectAutoIndexNodes,
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  mergeLocaleDocs: mergeLocaleDocs as RouteEnumeratorsAPIDeps["mergeLocaleDocs"],
+});
+
+// Local alias so the `mergeLocaleDocs` cast above reads clearly.
+type RouteEnumeratorsAPIDeps = Parameters<typeof createRouteEnumerators>[0];
+
+export const {
+  enumerateDocsRoutes,
+  enumerateTagsRoutes,
+  enumerateVersionedRoutes,
+  enumerateAllRoutes,
+} = routeEnumerators;
+
+// Re-export the pure nav-tree helpers entrypoints reach for directly.
+export {
+  buildNavTree,
+  groupSatelliteNodes,
+  findNode,
+  firstRoutedHref,
+  collectAutoIndexNodes,
+  isNavVisible,
+  stableDocs,
+  toRouteSlug,
+  toSlugParams,
+};

package/routes-src/_docs-helpers.ts

@@ -0,0 +1,284 @@
+// routes/_docs-helpers — package-side nav-tree helpers for the package-owned
+// route entrypoints (epic Package-First Finale #2356, A1 #2361).
+//
+// The host's `src/utils/docs.ts` `buildNavTree` / `buildBreadcrumbs` /
+// `collectAutoIndexNodes` / `groupSatelliteNodes` / `findNode` /
+// `firstRoutedHref` are host-only wrappers around the package primitive
+// `buildSidebarTree` (`@takazudo/zudo-doc/sidebar-tree`). The package route
+// entrypoints inject these same helpers into the doc-route / nav-source /
+// nav-wrapper factories, so this module reproduces them WITHOUT the host `@/`
+// alias — the "+ package `docs` helpers" note in the ADR's host-dep table.
+//
+// Faithful to the host derivation (root-index node synthesis, NavNode shape,
+// satellite grouping, breadcrumb walk) but without the host-only LRU /
+// identity caches: build-time array-identity stability already comes from the
+// snapshot-anchored `stableDocs` (below) + `memoizeDerived` in the factories.
+//
+// `stableDocs` (the content bridge — Decision 5) imports `@takazudo/zfb/content`
+// directly (NOT the host `zfb/content` tsconfig alias — Decision 2), anchoring
+// the bridged + draft-filtered array on the snapshot so repeat callers within a
+// build get the SAME instance and the nav-tree / doc-route memos short-circuit.
+
+import {
+  getCollection,
+  getContentSnapshot,
+  type CollectionEntry,
+} from "@takazudo/zfb/content";
+import {
+  buildSidebarTree,
+  type CategoryMeta,
+  type SidebarNode,
+} from "@takazudo/zudo-doc/sidebar-tree";
+import { toRouteSlug } from "@takazudo/zudo-doc/slug";
+import type { DocNavNode, DocPageEntry, DocPageFrontmatter } from "@takazudo/zudo-doc/doc-page-props";
+
+export type { CategoryMeta, DocNavNode, DocPageEntry };
+
+// ---------------------------------------------------------------------------
+// Content bridge — snapshot-anchored stable docs (Decision 5)
+// ---------------------------------------------------------------------------
+
+/** The stable per-build anchor array for a collection — the raw readonly
+ *  snapshot array zfb installs once. `undefined` on the fs-fallback path. */
+function snapshotAnchor(name: string): readonly unknown[] | undefined {
+  return getContentSnapshot()?.collections[name];
+}
+
+const bridgedByAnchor = new WeakMap<object, DocPageEntry[]>();
+
+/** Bridge a raw zfb collection entry onto the `DocPageEntry` shape the factories
+ *  expect (Astro-compat `id`/`collection`, with `index` suffix stripped via the
+ *  canonical root-slug rule). */
+function bridgeEntry(
+  e: CollectionEntry<DocPageFrontmatter>,
+  collectionName: string,
+): DocPageEntry {
+  return {
+    slug: e.slug,
+    id: toRouteSlug(e.slug),
+    collection: collectionName,
+    data: e.data,
+    body: e.body,
+    module_specifier: e.module_specifier,
+    Content: e.Content,
+  };
+}
+
+function buildBridged(collectionName: string): DocPageEntry[] {
+  const raw = getCollection<DocPageFrontmatter>(collectionName);
+  return raw.map((e) => bridgeEntry(e, 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); the no-snapshot (fs-fallback / unit-test) path computes fresh and is
+ * deliberately unmemoized. Passed as `stableDocs` to `createNavSourceDocs`.
+ */
+export function stableDocs(collectionName: string): DocPageEntry[] {
+  const anchor = snapshotAnchor(collectionName);
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// Nav-tree helpers — ported from src/utils/docs.ts onto buildSidebarTree
+// ---------------------------------------------------------------------------
+
+/** Filter predicate: true when a doc should appear in navigation. */
+export function isNavVisible(doc: DocPageEntry): boolean {
+  return !doc.data.unlisted && !doc.data.standalone;
+}
+
+/** A docs-href builder: `(slug, locale) => url`. */
+export type BuildHref = (slug: string, locale: string) => string;
+
+export interface BuildNavTreeOptions {
+  buildHref?: BuildHref;
+}
+
+function toNavNode(node: SidebarNode): DocNavNode {
+  return {
+    slug: node.id,
+    label: node.label,
+    description: node.description,
+    position: node.sidebar_position ?? 999,
+    href: node.href,
+    hasPage: node.hasPage,
+    children: node.children.map(toNavNode),
+    sortOrder: node.sortOrder ?? "asc",
+  };
+}
+
+/** Last entry whose package-derived slug is empty ("") — the entry the shared
+ *  builder skips. Last one wins (mirrors the host builder's overwrite). */
+function findRootIndexDoc(docs: DocPageEntry[]): DocPageEntry | undefined {
+  let found: DocPageEntry | undefined;
+  for (const d of docs) {
+    const slug = d.data.slug ?? d.id.replace(/\/index$/, "");
+    if (slug === "") found = d;
+  }
+  return found;
+}
+
+function toRootNavNode(
+  doc: DocPageEntry,
+  locale: string,
+  buildHref: BuildHref,
+  categoryMeta?: Map<string, CategoryMeta>,
+): DocNavNode {
+  const meta = categoryMeta?.get("");
+  const noPage = doc.data.category_no_page ?? meta?.noPage;
+  const sortOrder =
+    (doc.data.category_sort_order as "asc" | "desc" | undefined) ?? meta?.sortOrder ?? "asc";
+  return {
+    slug: "",
+    label:
+      (doc.data.sidebar_label as string | undefined) ??
+      doc.data.title ??
+      meta?.label ??
+      "",
+    description: doc.data.description ?? meta?.description,
+    position: (doc.data.sidebar_position as number | undefined) ?? meta?.position ?? 999,
+    href: noPage ? undefined : buildHref("", locale),
+    hasPage: noPage !== true,
+    children: [],
+    sortOrder,
+  };
+}
+
+/**
+ * Build a recursive navigation tree from a flat doc collection. Delegates tree
+ * construction to the shared `buildSidebarTree`; keeps the host-side concerns
+ * (DocNavNode shape, root-index node synthesis). `buildHref` parameterizes the
+ * href space (default: the injected `docsUrl`). Unlike the host copy this drops
+ * the LRU / identity caches — the snapshot-anchored `stableDocs` already makes
+ * the input arrays identity-stable so the factory-level `memoizeDerived` short-
+ * circuits per build.
+ */
+export function buildNavTree(
+  docs: DocPageEntry[],
+  locale: string,
+  categoryMeta: Map<string, CategoryMeta> | undefined,
+  buildHref: BuildHref,
+  options?: BuildNavTreeOptions,
+): DocNavNode[] {
+  const href: BuildHref = options?.buildHref ?? buildHref;
+  const sidebarTree = buildSidebarTree(
+    docs.map((d) => ({ id: d.id, data: d.data })),
+    locale,
+    {
+      categoryMeta,
+      buildHref: (slug, loc) => href(slug, loc),
+      // Host call sites own visibility; disable the builder's default filter so
+      // breadcrumb (unfiltered) and nav (pre-filtered) paths are unchanged.
+      isNavVisible: () => true,
+    },
+  );
+  const result = sidebarTree.map(toNavNode);
+
+  const rootDoc = findRootIndexDoc(docs);
+  if (rootDoc) {
+    result.push(toRootNavNode(rootDoc, locale, href, categoryMeta));
+    result.sort((a, b) => {
+      const posCompare = a.position - b.position;
+      if (posCompare !== 0) return posCompare;
+      return a.slug.localeCompare(b.slug);
+    });
+  }
+  return result;
+}
+
+/** Group "satellite" nodes (slug-prefix siblings) under their primary node. */
+export function groupSatelliteNodes(tree: DocNavNode[], prefixes: string[]): DocNavNode[] {
+  const result = [...tree];
+  for (const prefix of prefixes) {
+    const primaryIdx = result.findIndex((n) => n.slug === prefix);
+    if (primaryIdx < 0) continue;
+    const primary = result[primaryIdx];
+    if (!primary) continue;
+    const satelliteIdxs: number[] = [];
+    for (let i = 0; i < result.length; i++) {
+      const node = result[i];
+      if (node && i !== primaryIdx && node.slug.startsWith(`${prefix}-`)) {
+        satelliteIdxs.push(i);
+      }
+    }
+    if (satelliteIdxs.length === 0) continue;
+    const extraChildren: DocNavNode[] = [];
+    for (const idx of satelliteIdxs) {
+      const node = result[idx];
+      if (node) extraChildren.push(node);
+    }
+    result[primaryIdx] = { ...primary, children: [...primary.children, ...extraChildren] };
+    for (const idx of satelliteIdxs.reverse()) result.splice(idx, 1);
+  }
+  return result;
+}
+
+/** Find a node by slug anywhere in the tree. */
+export function findNode(nodes: DocNavNode[], slug: string): DocNavNode | undefined {
+  for (const node of nodes) {
+    if (node.slug === slug) return node;
+    const found = findNode(node.children, slug);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/** Href of the first routed descendant, walking children depth-first. */
+export function firstRoutedHref(node: DocNavNode): string | undefined {
+  for (const child of node.children) {
+    if (child.hasPage && child.href) return child.href;
+    const nested = firstRoutedHref(child);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+/** Collect all category nodes that have children but no page (no index.mdx). */
+export function collectAutoIndexNodes(nodes: DocNavNode[]): DocNavNode[] {
+  const result: DocNavNode[] = [];
+  for (const node of nodes) {
+    if (!node.hasPage && node.children.length > 0 && node.href) result.push(node);
+    result.push(...collectAutoIndexNodes(node.children));
+  }
+  return result;
+}
+
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+/** Build breadcrumb trail by walking the nav tree. `homeHref` is the locale
+ *  docs root (injected). `hrefFor` optionally remaps intermediate crumbs into
+ *  a versioned URL space. */
+export function buildBreadcrumbs(
+  tree: DocNavNode[],
+  slug: string,
+  homeHref: string,
+  hrefFor?: (slug: string) => string,
+): BreadcrumbItem[] {
+  const parts = slug.split("/");
+  const crumbs: BreadcrumbItem[] = [{ label: "", href: homeHref }];
+  let nodes = tree;
+  for (let i = 0; i < parts.length; i++) {
+    const partialSlug = parts.slice(0, i + 1).join("/");
+    const node = nodes.find((n) => n.slug === partialSlug);
+    if (!node) break;
+    const isLast = i === parts.length - 1;
+    const href = isLast
+      ? undefined
+      : hrefFor && node.href !== undefined
+        ? hrefFor(node.slug)
+        : node.href;
+    crumbs.push({ label: node.label, href });
+    nodes = node.children;
+  }
+  return crumbs;
+}

package/routes-src/_virtual.d.ts

@@ -0,0 +1,15 @@
+// Ambient typing for the route-context virtual module emitted by the routes
+// plugin (`addVirtualModule("virtual:zudo-doc-route-context", …)`). The module
+// has no on-disk source — it is materialised at build by the zfb plugin runtime
+// — so this declaration gives the package route entrypoints a typed import.
+//
+// The payload is SERIALIZABLE DATA ONLY (ADR Decision 1): `settings`,
+// `translations`, `tagVocabulary`. `_context.ts` narrows it to the concrete
+// `RouteContextPayload` at the seam.
+declare module "virtual:zudo-doc-route-context" {
+  export const routeContext: {
+    settings: unknown;
+    translations: Record<string, Record<string, string>>;
+    tagVocabulary: ReadonlyArray<Record<string, unknown>>;
+  };
+}

package/routes-src/api-ai-chat.tsx

@@ -0,0 +1,46 @@
+// Package route entrypoint: /api/ai-chat — package-owned equivalent of
+// pages/api/ai-chat.tsx (A1 #2361). SSR route (prerender = false), injected
+// with `opts: { prerender: false }` by the routes plugin (Decision 3).
+//
+// SCOPE NOTE (A1): the FULL ai-chat server handler (CORS allowlist, prompt-
+// injection screening, KV rate limiting, audit logging, the Anthropic client)
+// lives host-side in `pages/api/_ai-chat-*` and is NOT yet package-shipped — it
+// depends on host-only modules and CF env bindings that the serializable
+// route-context virtual module does not carry. This package entrypoint proves
+// the SSR-route seam (prerender shape + demo-mode short-circuit driven from the
+// virtual-module `settings`) and returns a safe disabled-by-default response;
+// re-homing the full handler into the package is deferred to the render-proof
+// follow-up (A2 #2363 / a later sub-issue). With `packageOwnedRoutes` off this
+// is never evaluated, and even on it is dropped if the user keeps their
+// `pages/api/ai-chat.tsx` stub (Decision 6).
+
+import { settings } from "./_context.js";
+
+// `frontmatter` is required by zfb's TSX page contract; without it zfb defaults
+// the route to SSG and the `prerender = false` below is ignored.
+export const frontmatter = { title: "AI Chat API" };
+
+export const prerender = false;
+
+const DISABLED_MESSAGE =
+  "This feature is disabled on this demo. Need per project setup to enable this.";
+
+function jsonResponse(body: Record<string, unknown>, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+export default function AiChatHandler(): Response {
+  // Package default: no real Anthropic-backed handler is wired here (see the
+  // scope note). Reply with the stable disabled message regardless of method —
+  // the host route (kept as a `pages/` stub) owns the full implementation.
+  if (settings.aiChatDemoMode === false && settings.aiAssistant) {
+    return jsonResponse(
+      { error: "ai-chat handler not provided by the package route (see A1 #2361)" },
+      501,
+    );
+  }
+  return jsonResponse({ response: DISABLED_MESSAGE }, 200);
+}