create-zudo-doc 0.2.21 → 0.2.22

package/templates/base/src/utils/docs.ts

@@ -123,6 +123,17 @@ function navTreeCacheKey(
     .join(",")}`;
 }
 
+/** A docs-href builder: `(slug, locale) => url`. Lets a caller inject the URL
+ *  space the tree's hrefs are minted in (e.g. a versioned route's own URLs)
+ *  instead of the default latest-route `docsUrl`. */
+export type BuildHref = (slug: string, locale: Locale) => string;
+
+/** Optional injected dependencies for {@link buildNavTree}. */
+export interface BuildNavTreeOptions {
+  /** Override the href builder used for every node (defaults to `docsUrl`). */
+  buildHref?: BuildHref;
+}
+
 /**
  * Build a recursive navigation tree from a flat content collection.
  * Mirrors the filesystem: directories become category nodes, files become leaves.
@@ -131,28 +142,45 @@ function navTreeCacheKey(
  * framework builder (`buildSidebarTree` in @takazudo/zudo-doc/sidebar-tree);
  * this function keeps the host-side concerns: the NavNode shape consumed by
  * every host nav surface, the content-key cache, and the identity fast-path.
+ *
+ * `options.buildHref` parameterizes the href space (#2344, S1a): callers pass it
+ * to mint hrefs in their own route's URL space. Omit it to keep the default
+ * latest-route `docsUrl` behavior — every existing 3-arg call site is unchanged.
  */
 export function buildNavTree(
   docs: DocsEntry[],
   lang: Locale = defaultLocale,
   categoryMeta?: Map<string, CategoryMeta>,
+  options?: BuildNavTreeOptions,
 ): NavNode[] {
+  const buildHref: BuildHref = options?.buildHref ?? ((slug, locale) => docsUrl(slug, locale));
+  // Both cache layers are keyed by (docs, lang, categoryMeta) and assume the
+  // default `docsUrl` href space. A custom `buildHref` mints a DIFFERENT href
+  // space for the same key, so it must skip both the read (would return a tree
+  // with default hrefs) and the write (would poison the default-href cache for
+  // later callers). Only the default-href path — every current call site — is
+  // cached; custom-href callers (versioned routes, S6/S7/S8) recompute. The
+  // cache exists for the hot default path, which this preserves exactly.
+  const useCache = options?.buildHref === undefined;
+
   // Identity fast-path: stable array instance already seen for this
   // (lang, categoryMeta)? Return its tree without recomputing the key.
-  const byIdentity = navTreeByIdentity.get(docs);
-  if (byIdentity) {
-    for (const slot of byIdentity) {
-      if (slot.lang === lang && slot.categoryMeta === categoryMeta) {
-        return slot.tree;
+  if (useCache) {
+    const byIdentity = navTreeByIdentity.get(docs);
+    if (byIdentity) {
+      for (const slot of byIdentity) {
+        if (slot.lang === lang && slot.categoryMeta === categoryMeta) {
+          return slot.tree;
+        }
       }
     }
-  }
 
-  const cacheKey = navTreeCacheKey(docs, lang, categoryMeta);
-  const cached = navTreeCacheGet(cacheKey);
-  if (cached) {
-    rememberIdentity(docs, lang, categoryMeta, cached);
-    return cached;
+    const cacheKey = navTreeCacheKey(docs, lang, categoryMeta);
+    const cached = navTreeCacheGet(cacheKey);
+    if (cached) {
+      rememberIdentity(docs, lang, categoryMeta, cached);
+      return cached;
+    }
   }
 
   const sidebarTree = buildSidebarTree(
@@ -166,7 +194,7 @@ export function buildNavTree(
     lang,
     {
       categoryMeta,
-      buildHref: (slug, locale) => docsUrl(slug, locale),
+      buildHref: (slug, locale) => buildHref(slug, locale as Locale),
       // Host call sites own visibility: nav surfaces pre-filter via
       // `stableNavDocs(docs.filter(isNavVisible))`, while the breadcrumb tree
       // intentionally builds from the UNFILTERED list so unlisted pages still
@@ -186,7 +214,7 @@ export function buildNavTree(
   // already-sorted rest).
   const rootDoc = findRootIndexDoc(docs);
   if (rootDoc) {
-    result.push(toRootNavNode(rootDoc, lang, categoryMeta));
+    result.push(toRootNavNode(rootDoc, lang, buildHref, categoryMeta));
     result.sort((a, b) => {
       const posCompare = a.position - b.position;
       if (posCompare !== 0) return posCompare;
@@ -194,8 +222,10 @@ export function buildNavTree(
     });
   }
 
-  navTreeCacheSet(cacheKey, result);
-  rememberIdentity(docs, lang, categoryMeta, result);
+  if (useCache) {
+    navTreeCacheSet(navTreeCacheKey(docs, lang, categoryMeta), result);
+    rememberIdentity(docs, lang, categoryMeta, result);
+  }
   return result;
 }
 
@@ -219,6 +249,7 @@ function findRootIndexDoc(docs: DocsEntry[]): DocsEntry | undefined {
 function toRootNavNode(
   doc: DocsEntry,
   lang: Locale,
+  buildHref: BuildHref,
   categoryMeta?: Map<string, CategoryMeta>,
 ): NavNode {
   const meta = categoryMeta?.get("");
@@ -229,7 +260,7 @@ function toRootNavNode(
     label: doc.data.sidebar_label ?? doc.data.title ?? meta?.label ?? "",
     description: doc.data.description ?? meta?.description,
     position: doc.data.sidebar_position ?? meta?.position ?? 999,
-    href: noPage ? undefined : docsUrl("", lang),
+    href: noPage ? undefined : buildHref("", lang),
     hasPage: noPage !== true,
     children: [],
     sortOrder,

package/templates/base/src/utils/github.ts

@@ -1,19 +1,22 @@
-import { settings } from "@/config/settings";
+// Host thin-stub — see @takazudo/zudo-doc/github-helpers (epic #2344, S7).
+//
+// `buildGitHubRepoUrl` and `buildGitHubSourceUrl` are now parameterized pure
+// functions in the package; this module wraps them with the host's
+// `settings.githubUrl` singleton.
 
-function trimTrailingSlash(url: string): string {
-  return url.replace(/\/+$/, "");
-}
+import { settings } from "@/config/settings";
+import {
+  buildGitHubRepoUrl as _buildGitHubRepoUrl,
+  buildGitHubSourceUrl as _buildGitHubSourceUrl,
+} from "@takazudo/zudo-doc/github-helpers";
 
 export function buildGitHubRepoUrl(): string | null {
-  if (!settings.githubUrl) return null;
-  return trimTrailingSlash(settings.githubUrl as string);
+  return _buildGitHubRepoUrl(settings.githubUrl);
 }
 
 export function buildGitHubSourceUrl(
   contentDir: string,
   entryId: string,
 ): string | null {
-  const repoUrl = buildGitHubRepoUrl();
-  if (!repoUrl) return null;
-  return `${repoUrl}/blob/HEAD/${contentDir}/${entryId}`;
+  return _buildGitHubSourceUrl(settings.githubUrl, contentDir, entryId);
 }

package/templates/base/src/utils/nav-scope.ts

@@ -1,63 +1,34 @@
+// Host thin-stub for nav-scope utilities (epic #2344, S5).
+// Core logic lives in @takazudo/zudo-doc/nav-scope; this stub wires
+// the host's `settings.headerNav` singleton.
 import { settings } from "@/config/settings";
 import type { NavNode } from "@/utils/docs";
 export type { HeaderNavItem } from "@/config/settings";
 
+import {
+  getCategoryOrder as _getCategoryOrder,
+  getNavSectionForSlug as _getNavSectionForSlug,
+  getNavSubtree as _getNavSubtree,
+} from "@takazudo/zudo-doc/nav-scope";
+
 /** Collect all categoryMatch strings from headerNav, including children (ordered). */
 export function getCategoryOrder(): string[] {
-  return settings.headerNav.flatMap((item) => {
-    const matches: string[] = [];
-    if (item.categoryMatch) matches.push(item.categoryMatch);
-    if (item.children) {
-      for (const child of item.children) {
-        if (child.categoryMatch) matches.push(child.categoryMatch);
-      }
-    }
-    return matches;
-  });
+  return _getCategoryOrder(settings.headerNav);
 }
 
 /**
- * Given a doc's slug (e.g. "getting-started/introduction" or "claude-agents/doc-reviewer"),
- * return the categoryMatch value of the headerNav item it belongs to.
+ * Given a doc's slug, return the categoryMatch value of the headerNav item it belongs to.
  */
 export function getNavSectionForSlug(slug: string): string | undefined {
-  const topCategory = slug.split("/")[0] ?? "";
-  const all = getCategoryOrder();
-
-  // First pass: find explicit matchers (not "!")
-  const explicitMatches = all.filter(
-    (cm) => cm !== "!" && topCategory.startsWith(cm),
-  );
-  if (explicitMatches.length > 0) {
-    // Longest prefix match wins
-    return explicitMatches.sort((a, b) => b.length - a.length)[0];
-  }
-
-  // Second pass: return the default ("!") matcher
-  const defaultItem = settings.headerNav.find(
-    (item) => item.categoryMatch === "!",
-  );
-  return defaultItem?.categoryMatch;
+  return _getNavSectionForSlug(slug, settings.headerNav);
 }
 
 /**
  * Filter top-level NavNodes by a headerNav categoryMatch value.
- * - "!" means everything NOT claimed by explicit matchers
- * - "claude" means nodes whose slug starts with "claude"
- * - undefined means all nodes
  */
 export function getNavSubtree(
   tree: NavNode[],
   categoryMatch?: string,
 ): NavNode[] {
-  if (!categoryMatch) return tree;
-
-  if (categoryMatch === "!") {
-    const explicitPrefixes = getCategoryOrder().filter((cm) => cm !== "!");
-    return tree.filter(
-      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix)),
-    );
-  }
-
-  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+  return _getNavSubtree(tree, categoryMatch, settings.headerNav);
 }

package/templates/base/src/utils/sidebar.ts

@@ -1,10 +1,16 @@
+// Host thin-stub for sidebar utilities (epic #2344, S5).
+// Core logic lives in @takazudo/zudo-doc/sidebar-utils; this stub wires
+// the host's singletons (sidebars config, getCategoryOrder for the "!" filter).
 import sidebars from "@/config/sidebars";
 import type { SidebarItem } from "@/config/sidebars";
 import type { NavNode, CategoryMeta } from "@/utils/docs";
-import { buildNavTree, findNode } from "@/utils/docs";
-import { getNavSubtree } from "@/utils/nav-scope";
+import { buildNavTree } from "@/utils/docs";
+import { getCategoryOrder } from "@/utils/nav-scope";
 import type { Locale } from "@/config/i18n";
 import type { DocsEntry } from "@/types/docs-entry";
+import { buildSidebarForSection as _buildSidebarForSection } from "@takazudo/zudo-doc/sidebar-utils";
+
+export type { SidebarItem };
 
 /**
  * Build sidebar nodes for a given nav section.
@@ -17,88 +23,14 @@ export function buildSidebarForSection(
   categoryMatch?: string,
   categoryMeta?: Map<string, CategoryMeta>,
 ): NavNode[] {
-  const tree = buildNavTree(docs, lang, categoryMeta);
-
-  // Check if there's a sidebar config for this section
-  const sectionKey = categoryMatch ?? "default";
-  const config = sidebars[sectionKey];
-
-  if (!config || config.length === 0) {
-    // Fall back to auto-generated
-    return getNavSubtree(tree, categoryMatch);
-  }
-
-  // Resolve config to nodes
-  return resolveItems(config, tree, lang);
-}
-
-function resolveItems(
-  items: SidebarItem[],
-  tree: NavNode[],
-  lang: Locale,
-): NavNode[] {
-  return items.flatMap((item) => resolveItem(item, tree, lang));
-}
-
-function resolveItem(
-  item: SidebarItem,
-  tree: NavNode[],
-  lang: Locale,
-): NavNode[] {
-  if (typeof item === "string") {
-    // String shorthand = doc reference (always rendered as leaf, children stripped)
-    const node = findNode(tree, item);
-    return node ? [{ ...node, children: [] }] : [];
-  }
-
-  switch (item.type) {
-    case "doc": {
-      const node = findNode(tree, item.id);
-      if (!node) return [];
-      // Doc references always render as leaves — strip children so they
-      // don't duplicate structure that the explicit config already defines.
-      return [{ ...node, children: [], ...(item.label ? { label: item.label } : {}) }];
-    }
-    case "link": {
-      return [
-        {
-          slug: `__link__${item.href}`,
-          label: item.label,
-          href: item.href,
-          position: 0,
-          hasPage: false,
-          children: [],
-        },
-      ];
-    }
-    case "category": {
-      const children = resolveItems(item.items, tree, lang);
-      if (item.sortOrder === "desc") {
-        children.reverse();
-      }
-      return [
-        {
-          slug: `__category__${item.label}`,
-          label: item.label,
-          position: 0,
-          hasPage: false,
-          href: undefined,
-          children,
-          sortOrder: item.sortOrder,
-          collapsed: item.collapsed,
-        },
-      ];
-    }
-    case "autogenerated": {
-      if (item.dirName) {
-        const node = findNode(tree, item.dirName);
-        return node ? node.children : [];
-      }
-      return tree;
-    }
-    default: {
-      const _exhaustive: never = item;
-      throw new Error(`Unhandled sidebar item type: ${JSON.stringify(_exhaustive)}`);
-    }
-  }
+  const explicitPrefixes = getCategoryOrder().filter((cm) => cm !== "!");
+  return _buildSidebarForSection(
+    docs,
+    lang,
+    categoryMatch,
+    categoryMeta,
+    sidebars,
+    (d, l, meta) => buildNavTree(d as DocsEntry[], l as Locale, meta as Map<string, CategoryMeta>),
+    explicitPrefixes,
+  ) as NavNode[];
 }

package/templates/base/src/utils/slug.ts

@@ -1,53 +1,10 @@
-// Canonical root-slug rule (zudolab/zudo-doc#1891, closes #1873).
-//
-// A doc collection's bare root `index.mdx` must resolve to the canonical
-// URL `/docs/` — i.e. an EMPTY route slug `""` — NOT `/docs/index/`.
-// Five independent index-stripping sites historically disagreed on what a
-// bare root `index` becomes; this helper is the single source of truth they
-// all route through (the standalone doc-history-server package duplicates the
-// one-liner with a pointer comment back here — it cannot import across the
-// package boundary; see its CLAUDE.md).
-//
-// Rule:
-//   - bare root  "index"      → ""   (URL /docs/)
-//   - nested     "x/index"    → "x"  (URL /docs/x/)
-//   - everything else         → unchanged
-//
-// doc-history storage uses the OPPOSITE convention: the per-page JSON and the
-// build-time meta manifest key the root entry under "index" (an empty path
-// segment is unroutable — the server regex /^\/doc-history\/(.+)\.json$/ and
-// the `<locale>/<slug>.json` composition both reject ""). `toHistorySlug`
-// applies the `"" -> "index"` sentinel so the doc-history client fetch path
-// and the meta-manifest lookup land on the stored key. See `toHistorySlug`.
-export function toRouteSlug(id: string): string {
-  if (id === "index") return "";
-  return id.replace(/\/index$/, "");
-}
-
-// Doc-history storage sentinel — the inverse of the bare-root case of
-// `toRouteSlug`. The canonical route slug for a root index is "" (→ /docs/),
-// but doc-history JSON is stored/served under "index" (an empty path segment
-// is unroutable). Apply this to the route slug BEFORE composing the
-// doc-history fetch path and the meta-manifest key so root pages resolve to
-// e.g. /doc-history/index.json and /doc-history/<locale>/index.json.
-// Non-empty slugs pass through unchanged.
-export function toHistorySlug(routeSlug: string): string {
-  return routeSlug === "" ? "index" : routeSlug;
-}
-
-// Convert a canonical route slug into the `params.slug` array zfb's
-// optional-catchall route (`[[...slug]]`) expects. The bare root ("") maps to
-// `[]` (zero segments → /docs/); a naive `"".split("/")` yields `[""]`, which
-// zfb's catchall router REJECTS (empty array element), silently dropping the
-// entire route. Every `.split("/")` at a docs route's paths() site must go
-// through this helper.
-export function toSlugParams(routeSlug: string): string[] {
-  return routeSlug === "" ? [] : routeSlug.split("/");
-}
-
-export function toTitleCase(str: string): string {
-  return str
-    .split("-")
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
-}
+// Thin re-export shim. The canonical slug rules moved into the package
+// (`@takazudo/zudo-doc/slug`) as part of the package-first migration (#2344,
+// S1a). Host code keeps importing from `@/utils/slug`; the implementation —
+// including the canonical-root rule (#1891 / #1873) — lives once in the package.
+export {
+  toRouteSlug,
+  toHistorySlug,
+  toSlugParams,
+  toTitleCase,
+} from "@takazudo/zudo-doc/slug";

package/templates/base/src/utils/smart-break.tsx

@@ -1,120 +1,12 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-import type { VNode } from "preact";
-
-/**
- * Heuristic: does `text` look like a URL, filesystem path, or similar
- * structure where inserting <wbr> after delimiters aids line-wrapping?
- *
- * Returns true for URLs (contain "://"), POSIX-style absolute/relative
- * paths ("/", "./", "../"), Windows drive paths ("C:\\..." or "C:/..."),
- * strings with 2+ slashes (or backslashes) between alphanumerics, and
- * plausible domain-plus-slash strings.
- *
- * Returns false for empty input and prose-y hyphen/slash/dot combinations
- * like "and/or", "well-known", "state-of-the-art", "1.2.3-beta.4", "UI/UX".
- */
-export function isPathLike(text: string): boolean {
-  if (!text) return false;
-  if (text.includes("://")) return true;
-  // starts with "/", "./", or "../"
-  if (/^\.{0,2}\//.test(text)) return true;
-  // Windows drive letter paths, either backslash or forward slash
-  if (/^[A-Za-z]:[\\/]/.test(text)) return true;
-  // 2+ forward slashes appearing between alphanumeric runs
-  const forwardMatches = text.match(/[A-Za-z0-9]\/[A-Za-z0-9]/g);
-  if (forwardMatches && forwardMatches.length >= 2) return true;
-  // 2+ backslashes appearing between alphanumeric runs
-  const backMatches = text.match(/[A-Za-z0-9]\\[A-Za-z0-9]/g);
-  if (backMatches && backMatches.length >= 2) return true;
-  // Plausible domain-ish: a "." between alphanumerics AND at least one slash
-  const hasDomainDot = /[A-Za-z0-9]\.[A-Za-z0-9]/.test(text);
-  const hasSlash = /[\\/]/.test(text);
-  if (hasDomainDot && hasSlash) return true;
-  return false;
-}
-
-// Delimiter set: / \ - _ . : ? # & =
-// Capture in split so the delimiter is preserved at odd indices.
-const DELIM_SPLIT = /([/\\\-_.:?#&=])/;
-
-const HTML_ESCAPE_MAP: Record<string, string> = {
-  "&": "&amp;",
-  "<": "&lt;",
-  ">": "&gt;",
-  '"': "&quot;",
-  "'": "&#39;",
-};
-
-function htmlEscape(s: string): string {
-  return s.replace(/[&<>"']/g, (ch) => HTML_ESCAPE_MAP[ch]!);
-}
-
-/**
- * If `text` is path-like, return a Preact fragment with <wbr/> inserted
- * after each delimiter (/, \, -, _, ., :, ?, #, &, =). Otherwise return
- * the input string unchanged so callers can trust non-path prose passes
- * through untouched.
- */
-export function smartBreak(text: string): VNode | string {
-  if (!isPathLike(text)) return text;
-  const parts = text.split(DELIM_SPLIT);
-  const nodes: (string | VNode)[] = [];
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i] ?? "";
-    if (part === "") continue;
-    nodes.push(part);
-    // Captured delimiter groups always land at odd indices.
-    if (i % 2 === 1) nodes.push(<wbr key={`wbr-${i}`} />);
-  }
-  return <>{nodes}</>;
-}
-
-/**
- * Preact function component wrapper — pure, server-renderable.
- * Stringifies children and defers to smartBreak.
- */
-export function SmartBreak({ children }: { children?: unknown }): VNode {
-  return <>{smartBreak(String(children ?? ""))}</>;
-}
-
-/**
- * HTML-escape `text` and inject a literal "<wbr>" tag after every
- * delimiter character. Unlike smartBreakToHtml, this does NOT check
- * isPathLike — it unconditionally breaks on delimiters.
- *
- * Useful when a caller has already decided that a larger string is
- * path-like and wants to apply the same wbr-injection rule to a
- * substring (e.g. a segment produced by splitting on a search-query
- * regex) without re-running the heuristic on fragments that are too
- * short to be classified correctly on their own.
- *
- * Byte-identical to smartBreakToHtml for inputs where isPathLike is
- * true, so the shared contract holds.
- */
-export function escapeAndInjectWbr(text: string): string {
-  const parts = text.split(DELIM_SPLIT);
-  let out = "";
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i] ?? "";
-    if (part === "") continue;
-    out += htmlEscape(part);
-    if (i % 2 === 1) out += "<wbr>";
-  }
-  return out;
-}
-
-/**
- * HTML-string counterpart of smartBreak. Produces a safe HTML string
- * with literal "<wbr>" tags injected after each delimiter in path-like
- * input, and HTML-escaped text elsewhere. For non-path input, returns
- * the HTML-escaped text unchanged (no wbr injection).
- *
- * Use this when the consumer cannot render Preact VNodes (e.g. building
- * an HTML string for `set:html` / dangerouslySetInnerHTML).
- */
-export function smartBreakToHtml(text: string): string {
-  if (!isPathLike(text)) return htmlEscape(text);
-  return escapeAndInjectWbr(text);
-}
+// Thin re-export shim. The smart-break helpers moved into the package
+// (`@takazudo/zudo-doc/smart-break`) as part of the package-first migration
+// (#2344, S1a) — consolidating with the former toc-local copy. Host code keeps
+// importing from `@/utils/smart-break`; the implementation lives once in the
+// package.
+export {
+  isPathLike,
+  smartBreak,
+  SmartBreak,
+  escapeAndInjectWbr,
+  smartBreakToHtml,
+} from "@takazudo/zudo-doc/smart-break";

package/templates/base/src/utils/tags.ts

@@ -1,7 +1,23 @@
+// Host thin-stub — see @takazudo/zudo-doc/tag-helpers (epic #2344, S7).
+//
+// `resolveTag` and `resolvePageTags` are now parameterized pure functions in the
+// package; this module remains backward-compatible by wrapping them with the
+// host's `settings.tagVocabulary` / `settings.tagGovernance` + the
+// `tagVocabulary` entries from `@/config/tag-vocabulary`.
+//
+// `collectTags` stays host-side because it depends on `DocsEntry` from the
+// host's content collections. It calls the local `resolveTag` wrapper which
+// in turn delegates to the package.
+
 import type { DocsEntry } from "@/types/docs-entry";
 import { settings } from "@/config/settings";
 import { tagVocabulary } from "@/config/tag-vocabulary";
-import type { TagVocabularyEntry } from "@/config/tag-vocabulary-types";
+import {
+  resolveTag as _resolveTag,
+  resolvePageTags as _resolvePageTags,
+} from "@takazudo/zudo-doc/tag-helpers";
+
+export type { ResolvedTag } from "@takazudo/zudo-doc/tag-helpers";
 
 export interface TagInfo {
   tag: string;
@@ -9,69 +25,19 @@ export interface TagInfo {
   docs: { slug: string; title: string; description?: string }[];
 }
 
-export interface ResolvedTag {
-  /** Canonical id after alias/redirect rewrites. Equal to the raw input when unchanged. */
-  canonical: string;
-  /** True when the canonical id should be dropped from aggregation (deprecated without redirect). */
-  deprecated: boolean;
-  /** True when the raw input matched a vocabulary entry (as id or alias). */
-  known: boolean;
-}
-
-interface VocabularyIndex {
-  byId: Map<string, TagVocabularyEntry>;
-  byAlias: Map<string, TagVocabularyEntry>;
-}
-
-let cachedIndex: VocabularyIndex | null = null;
-function getIndex(): VocabularyIndex {
-  if (cachedIndex) return cachedIndex;
-  const byId = new Map<string, TagVocabularyEntry>();
-  const byAlias = new Map<string, TagVocabularyEntry>();
-  for (const entry of tagVocabulary) {
-    byId.set(entry.id, entry);
-    for (const alias of entry.aliases ?? []) byAlias.set(alias, entry);
-  }
-  cachedIndex = { byId, byAlias };
-  return cachedIndex;
-}
-
-function vocabularyActive(): boolean {
-  return Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
+// Helpers that pass the host's settings + vocabulary entries to the package fns.
+function getVocab() {
+  return settings.tagVocabulary ? tagVocabulary : false;
 }
 
 /**
  * Resolve a raw tag string to its canonical form.
  *
- * When the vocabulary is inactive (`tagVocabulary: false` or
- * `tagGovernance: "off"`), the raw value passes through unchanged with
- * `known: false, deprecated: false`. Otherwise:
- *
- * - A direct id match returns that id.
- * - An alias match returns the aliased entry's id.
- * - `deprecated: { redirect: "<id>" }` rewrites to the redirect target.
- * - `deprecated: true` (no redirect) returns `deprecated: true` so callers
- *   can drop the tag from aggregation.
- * - An unknown value returns the raw string with `known: false`.
+ * Thin wrapper around `@takazudo/zudo-doc/tag-helpers` `resolveTag` that
+ * injects the host's tag vocabulary and governance settings.
  */
-export function resolveTag(raw: string): ResolvedTag {
-  if (!vocabularyActive()) {
-    return { canonical: raw, deprecated: false, known: false };
-  }
-  const { byId, byAlias } = getIndex();
-  const entry = byId.get(raw) ?? byAlias.get(raw);
-  if (!entry) return { canonical: raw, deprecated: false, known: false };
-  const dep = entry.deprecated;
-  if (dep && typeof dep === "object" && dep.redirect) {
-    const target = byId.get(dep.redirect);
-    if (target) return { canonical: target.id, deprecated: false, known: true };
-    // Redirect points at a missing id — treat like plain deprecation.
-    return { canonical: entry.id, deprecated: true, known: true };
-  }
-  if (dep === true) {
-    return { canonical: entry.id, deprecated: true, known: true };
-  }
-  return { canonical: entry.id, deprecated: false, known: true };
+export function resolveTag(raw: string) {
+  return _resolveTag(raw, getVocab(), settings.tagGovernance);
 }
 
 /**
@@ -80,16 +46,7 @@ export function resolveTag(raw: string): ResolvedTag {
  * produced by alias collapse are removed.
  */
 export function resolvePageTags(rawTags: readonly string[]): string[] {
-  const out: string[] = [];
-  const seen = new Set<string>();
-  for (const raw of rawTags) {
-    const { canonical, deprecated } = resolveTag(raw);
-    if (deprecated) continue;
-    if (seen.has(canonical)) continue;
-    seen.add(canonical);
-    out.push(canonical);
-  }
-  return out;
+  return _resolvePageTags(rawTags, getVocab(), settings.tagGovernance);
 }
 
 export function collectTags(