@astryxdesign/cli 0.6.3-canary.60b419f → 0.6.3-canary.685131c

package/api/build/build.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * astryx --json build (no query) — the "how to build a page" playbook signal.
  */
 export type BuildHelpResponse = {
     type: "build.help";
@@ -11,7 +11,7 @@ export type BuildHelpResponse = {
     };
 };
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * astryx --json build "<idea>" — the composition kit for what you're building.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static

package/api/build/build.type.mjs

@@ -7,7 +7,7 @@
  */
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * astryx --json build (no query) — the "how to build a page" playbook signal.
  *
  * @typedef {object} BuildHelpResponse
  * @property {'build.help'} type
@@ -16,7 +16,7 @@
  */
 
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * astryx --json build "<idea>" — the composition kit for what you're building.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static

package/api/component/component.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json component [--list] [--category X] [--detail names|compact|full]
+ * astryx --json component [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `component.list` type across all three detail levels;
  * the depth is carried in `data.detail` and `data.components` holds the grouped
@@ -55,7 +55,7 @@ export type ComponentBriefEntry = {
     import: string;
 };
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  */
 export type ComponentDetailResponse = {
     type: "component.detail";
@@ -81,14 +81,14 @@ export type ComponentOwnership = {
     sourceAvailable: boolean;
 };
 /**
- * xds --json component <name> --props
+ * astryx --json component <name> --props
  */
 export type ComponentDetailPropsResponse = {
     type: "component.detail.props";
     data: import("@astryxdesign/cli/authoring").ComponentPropDoc[];
 };
 /**
- * xds --json component <name> --source
+ * astryx --json component <name> --source
  */
 export type ComponentDetailSourceResponse = {
     type: "component.detail.source";
@@ -98,7 +98,7 @@ export type ComponentDetailSourceResponse = {
     };
 };
 /**
- * xds --json component <name> --showcase
+ * astryx --json component <name> --showcase
  */
 export type ComponentDetailShowcaseResponse = {
     type: "component.detail.showcase";
@@ -109,7 +109,7 @@ export type ComponentDetailShowcaseResponse = {
     };
 };
 /**
- * xds --json component <name> --blocks
+ * astryx --json component <name> --blocks
  */
 export type ComponentDetailBlocksResponse = {
     type: "component.detail.blocks";

package/api/component/component.type.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Colocated types for the `component` command — source of truth for the
  * component command's JSON responses. These typedefs describe the `{type, data}`
- * envelopes emitted by `xds --json component` and returned by the `component()`
+ * envelopes emitted by `astryx --json component` and returned by the `component()`
  * API; the `types/component.d.ts` barrel re-exports them for consumers.
  *
  * Detail-level contract for list views (brief < compact < full):
@@ -11,23 +11,23 @@
  *   --detail compact  Names + 1-line description + import path.
  *   --detail full     Full ComponentDoc per entry (props, theming, examples, etc.).
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json component                      -> component.list (data.detail='names')
- * xds --json component --list               -> component.list (data.detail='names')
- * xds --json component --category Form      -> component.list (filtered)
- * xds --json component --list --detail compact -> component.list (data.detail='compact')
- * xds --json component --list --detail full -> component.list (data.detail='full')
- * xds --json component Button               -> component.detail
- * xds --json component Button --props       -> component.detail.props
- * xds --json component Button --source      -> component.detail.source
- * xds --json component Button --showcase    -> component.detail.showcase
- * xds --json component Button --blocks      -> component.detail.blocks
- * (not found)                               -> CLIError
+ * astryx --json component                         -> component.list (data.detail='names')
+ * astryx --json component --list                  -> component.list (data.detail='names')
+ * astryx --json component --category Form         -> component.list (filtered)
+ * astryx --json component --list --detail compact -> component.list (data.detail='compact')
+ * astryx --json component --list --detail full    -> component.list (data.detail='full')
+ * astryx --json component Button                  -> component.detail
+ * astryx --json component Button --props          -> component.detail.props
+ * astryx --json component Button --source         -> component.detail.source
+ * astryx --json component Button --showcase       -> component.detail.showcase
+ * astryx --json component Button --blocks         -> component.detail.blocks
+ * (not found)                                     -> CLIError
  */
 
 /**
- * xds --json component [--list] [--category X] [--detail names|compact|full]
+ * astryx --json component [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `component.list` type across all three detail levels;
  * the depth is carried in `data.detail` and `data.components` holds the grouped
@@ -70,7 +70,7 @@
  */
 
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  * @typedef {object} ComponentDetailResponse
  * @property {'component.detail'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership} data
@@ -87,28 +87,28 @@
  */
 
 /**
- * xds --json component <name> --props
+ * astryx --json component <name> --props
  * @typedef {object} ComponentDetailPropsResponse
  * @property {'component.detail.props'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentPropDoc[]} data
  */
 
 /**
- * xds --json component <name> --source
+ * astryx --json component <name> --source
  * @typedef {object} ComponentDetailSourceResponse
  * @property {'component.detail.source'} type
  * @property {{component: string; source: string}} data
  */
 
 /**
- * xds --json component <name> --showcase
+ * astryx --json component <name> --showcase
  * @typedef {object} ComponentDetailShowcaseResponse
  * @property {'component.detail.showcase'} type
  * @property {{component: string; aspectRatio: number; source: string}} data
  */
 
 /**
- * xds --json component <name> --blocks
+ * astryx --json component <name> --blocks
  * @typedef {object} ComponentDetailBlocksResponse
  * @property {'component.detail.blocks'} type
  * @property {{component: string; showcase: BlockEntry | null; examples: BlockEntry[]; related: BlockEntry[]}} data

package/api/discover/discover.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverListResponse = {
     type: "discover.list";
@@ -25,21 +25,21 @@ export type DiscoverListEntry = {
     displayName?: string | undefined;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailResponse = {
     type: "discover.detail";
     data: DiscoverListEntry;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailDocResponse = {
     type: "discover.detail.doc";
     data: import("@astryxdesign/cli/authoring").ComponentDoc;
 };
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover <searchterm> (multiple matches)
  */
 export type DiscoverSearchResponse = {
     type: "discover.search";

package/api/discover/discover.type.mjs

@@ -6,16 +6,16 @@
  *
  * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json discover                            -> discover.list
- * xds --json discover @scope/name                -> discover.detail
- * xds --json discover @scope/name/Component      -> discover.detail.doc
- * xds --json discover <searchterm> (1 match)     -> discover.detail.doc
- * xds --json discover <searchterm> (N matches)   -> discover.search
- * (not found)                                    -> CLIError
+ * astryx --json discover                          -> discover.list
+ * astryx --json discover @scope/name              -> discover.detail
+ * astryx --json discover @scope/name/Component    -> discover.detail.doc
+ * astryx --json discover <searchterm> (1 match)   -> discover.detail.doc
+ * astryx --json discover <searchterm> (N matches) -> discover.search
+ * (not found)                                     -> CLIError
  */
 
 /**
- * xds --json discover
+ * astryx --json discover
  * @typedef {object} DiscoverListResponse
  * @property {'discover.list'} type
  * @property {DiscoverListEntry[]} data
@@ -35,21 +35,21 @@
  */
 
 /**
- * xds --json discover @scope/name
+ * astryx --json discover @scope/name
  * @typedef {object} DiscoverDetailResponse
  * @property {'discover.detail'} type
  * @property {DiscoverListEntry} data
  */
 
 /**
- * xds --json discover @scope/name/Component
+ * astryx --json discover @scope/name/Component
  * @typedef {object} DiscoverDetailDocResponse
  * @property {'discover.detail.doc'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc} data
  */
 
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover <searchterm> (multiple matches)
  * @typedef {object} DiscoverSearchResponse
  * @property {'discover.search'} type
  * @property {{query: string, matches: DiscoverSearchEntry[]}} data

package/api/docs/_adapter.d.mts

@@ -16,40 +16,43 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * The overlay languages a topic ships for its own file or any extension.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {string[]}
  */
-export function loadReferenceDocs(docPath: string, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
 /**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
+ * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
+ * Memoized per catalog, so a read that references a topic twice loads it once.
+ * Every read of the catalog shares the memoized node, so it is frozen; the
+ * lenses hand readers copies.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function lowerTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
- * The overlay languages a topic ships for its own file or any extension.
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog: DocsCatalog, lang: string | null): (topic: string) => Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode | null>;
+/**
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
+export function compileTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
+ * when unmatched) and lower it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
@@ -59,7 +62,7 @@ export function overlayLanguages(entry: import("../../foundation/discovery/docs-
  * @param {string} [options.cwd]
  * @returns {Promise<{
  *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
  *   lang: string | null,
  * }>}
  */
@@ -70,7 +73,7 @@ export function resolveTopicDocs(topic: string, options?: {
     cwd?: string | undefined;
 }): Promise<{
     catalog: DocsCatalog;
-    docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
+    node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
     lang: string | null;
 }>;
 /** The localized overlays a docs read can apply. */

package/api/docs/_adapter.mjs

@@ -7,29 +7,24 @@
  *   packages/cli/assets/docs/{topic}.doc.mjs plus every topic the configured
  *   integrations contribute — and, when a --dense/--zh overlay is requested,
  *   the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
- * @output Catalog access, overlay- and extension-merged reference-doc data,
- *   and a combined resolve step ({catalog, docsData}) that the detail and
- *   section leaves share.
- * @position Sits beside docs.mjs (api/docs/). Owns everything ≥2 leaves need so
- *   no leaf re-implements resolution, overlay merging, or unknown-topic
- *   handling. Discovery itself lives in foundation/discovery/docs-discovery,
- *   which api/search and the agent-docs block read through the same catalog.
+ * @output Catalog access, the compiler input for a topic, and the compiled
+ *   node for it: lowered (overlaid, extensions merged, keys stamped) or linked
+ *   (token references resolved too), memoized per catalog.
+ * @position Sits beside docs.mjs (api/docs/). Loads authored files and hands
+ *   them to foundation/doc-compiler, so no leaf, doctor check or search loads,
+ *   merges, or resolves docs on its own. Discovery itself lives in
+ *   foundation/discovery/docs-discovery, which the catalog comes from.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
 import {Project} from '../../foundation/config/project.mjs';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {
-  DocsCatalog,
-  mergeTopic,
-  problemsInTopic,
-  withSourceTitle,
-} from '../../foundation/discovery/docs-discovery.mjs';
-import {
-  sectionKeyProblems,
-  withSectionKeys,
-} from '../../foundation/discovery/docs-section-key.mjs';
+  linkReferenceTopic,
+  lowerReferenceTopic,
+} from '../../foundation/doc-compiler/compile.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {parseDoc} from '../../authoring/doctypes/parse.mjs';
@@ -56,108 +51,6 @@ export async function loadDocsCatalog(cwd = process.cwd()) {
   }
 }
 
-/**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
- */
-export async function loadReferenceDocs(docPath, {lang} = {}) {
-  const mod = await import(pathToFileURL(docPath).href);
-  const parsed = parseDoc(mod.docs ?? mod.default, path.basename(docPath));
-  if (!('sections' in parsed)) {
-    throw new Error(`${path.basename(docPath)} is not a reference document.`);
-  }
-  const problems = problemsInTopic(parsed);
-  if (problems.length > 0) {
-    throw new Error(
-      `${path.basename(docPath)} is invalid: ${problems.join('; ')}`,
-    );
-  }
-  const docs = parsed;
-  if (!lang || lang === 'en') return docs;
-
-  const translationPath = overlayPath(docPath, lang);
-  if (!fs.existsSync(translationPath)) return docs;
-
-  const translationMod = await import(pathToFileURL(translationPath).href);
-  const translation = translationMod.docsZh || translationMod.docsDense;
-  if (!translation) return docs;
-
-  // Overlays are keyed to a base section by title (`section`), not by array
-  // position. Position-keying silently grafted each overlay title onto whatever
-  // base section happened to share its index, so an overlay that omitted or
-  // reordered a section corrupted every section after it — `docs tokens --dense`
-  // printed the colour table under a "Spacing" heading (#2182). An overlay may
-  // now cover any subset of sections, in any order; sections it does not name
-  // keep their base content.
-  /** @type {Map<string, any>} */
-  const bySection = new Map();
-  for (const ts of translation.sections ?? []) {
-    if (ts?.section != null) bySection.set(ts.section, ts);
-  }
-
-  return {
-    ...docs,
-    description: translation.description || docs.description,
-    sections: docs.sections.map(
-      (
-        /** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section,
-      ) => {
-        const ts = bySection.get(section.title);
-        if (!ts) return section;
-        const localized = {
-          ...section,
-          title: ts.title || section.title,
-          content: section.content.map(
-            (
-              /** @type {import('@astryxdesign/cli/authoring').ReferenceContentBlock} */ block,
-              /** @type {number} */ bi,
-            ) => {
-              const tb = ts.content?.[bi];
-              if (!tb) return block;
-              if (tb.type === 'prose' && block.type === 'prose')
-                return {...block, text: tb.text};
-              if (tb.type === 'list' && block.type === 'list')
-                return {...block, items: tb.items};
-              return block;
-            },
-          ),
-        };
-        return withSourceTitle(localized, section.title);
-      },
-    ),
-  };
-}
-
-/**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
- */
-export async function loadTopicDoc(entry, {lang} = {}) {
-  let doc = await loadReferenceDocs(entry.path, {lang});
-  for (const extension of entry.extensions) {
-    doc = mergeTopic(doc, await loadReferenceDocs(extension.path, {lang}));
-    // Merging matches on keys, so this holds unless merge itself regresses.
-    const problems = sectionKeyProblems(doc.sections);
-    if (problems.length > 0) {
-      throw new Error(
-        `${path.basename(extension.path)}, extending ${entry.name}, leaves two sections with one key: ${problems.join('; ')}`,
-      );
-    }
-  }
-  // Derived keys are stamped only now, so they never take part in merging.
-  return withSectionKeys(doc);
-}
-
 /** The localized overlays a docs read can apply. */
 export const OVERLAY_LANGUAGES = ['zh', 'dense'];
 
@@ -186,11 +79,148 @@ export function overlayLanguages(entry) {
   );
 }
 
+/**
+ * The overlay a read applies: none for the authored language.
+ * @param {string | null | undefined} lang
+ * @returns {string | null}
+ */
+function overlayLanguage(lang) {
+  return lang && lang !== 'en' ? lang : null;
+}
+
+/**
+ * Load one authored file and the overlay for `lang`. A failure is recorded on
+ * the result, not thrown, so the compiler reports it in reading order.
+ * @param {string} docPath
+ * @param {string | null} lang
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').AuthoredFile>}
+ */
+async function loadAuthoredFile(docPath, lang) {
+  const file = path.basename(docPath);
+  let doc;
+  try {
+    const mod = await import(pathToFileURL(docPath).href);
+    doc = parseDoc(mod.docs ?? mod.default, file);
+  } catch (error) {
+    return {file, error};
+  }
+  if (!lang) return {file, doc};
+  const translationPath = overlayPath(docPath, lang);
+  if (!fs.existsSync(translationPath)) return {file, doc};
+  try {
+    const translationMod = await import(pathToFileURL(translationPath).href);
+    return {
+      file,
+      doc,
+      overlay: translationMod.docsZh || translationMod.docsDense || null,
+    };
+  } catch (overlayError) {
+    return {file, doc, overlayError};
+  }
+}
+
+/**
+ * Everything the compiler needs for one topic, read from disk.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} lang
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').ReferenceTopicInput>}
+ */
+async function loadCompilerInput(entry, lang) {
+  const extensions = [];
+  for (const extension of entry.extensions) {
+    extensions.push({
+      ...(await loadAuthoredFile(extension.path, lang)),
+      provider: extension.package,
+    });
+  }
+  return {
+    id: entry.name,
+    provider: entry.package,
+    replaces: entry.replaces ?? null,
+    lang,
+    base: await loadAuthoredFile(entry.path, lang),
+    extensions,
+  };
+}
+
+/** @type {WeakMap<DocsCatalog, Map<string, Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>>>} */
+const loweredByCatalog = new WeakMap();
+
+/**
+ * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
+ * Memoized per catalog, so a read that references a topic twice loads it once.
+ * Every read of the catalog shares the memoized node, so it is frozen; the
+ * lenses hand readers copies.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
+ */
+export function lowerTopic(catalog, entry, lang = null) {
+  const overlay = overlayLanguage(lang);
+  let cache = loweredByCatalog.get(catalog);
+  if (!cache) {
+    cache = new Map();
+    loweredByCatalog.set(catalog, cache);
+  }
+  const key = `${entry.name.toLowerCase()}\u0000${overlay ?? ''}`;
+  let lowered = cache.get(key);
+  if (!lowered) {
+    lowered = loadCompilerInput(entry, overlay).then(input =>
+      deepFreeze(lowerReferenceTopic(input)),
+    );
+    cache.set(key, lowered);
+  }
+  return lowered;
+}
+
+/**
+ * Freeze a value and everything in it.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+/**
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog, lang) {
+  return async topic => {
+    const target = catalog.resolve(topic);
+    return target ? lowerTopic(catalog, target, lang) : null;
+  };
+}
+
+/**
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
+ */
+export async function compileTopic(catalog, entry, lang = null) {
+  return linkReferenceTopic(
+    await lowerTopic(catalog, entry, lang),
+    referenceTargets(catalog, lang),
+  );
+}
+
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
+ * when unmatched) and lower it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
@@ -200,7 +230,7 @@ export function overlayLanguages(entry) {
  * @param {string} [options.cwd]
  * @returns {Promise<{
  *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
  *   lang: string | null,
  * }>}
  */
@@ -221,6 +251,6 @@ export async function resolveTopicDocs(topic, options = {}) {
     );
   }
 
-  const docsData = await loadTopicDoc(entry, {lang: effectiveLang});
-  return {catalog, docsData, lang: effectiveLang};
+  const node = await lowerTopic(catalog, entry, effectiveLang);
+  return {catalog, node, lang: effectiveLang};
 }