@doc-kit/core 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @doc-kit/core
 
+## 1.1.0
+
+### Minor Changes
+
+- [#1090](https://github.com/nodejs/doc-kit/pull/1090) [`0a9dc37`](https://github.com/nodejs/doc-kit/commit/0a9dc37dc96f8044c76c3ca9b35e97895a87d1fd) Thanks [@avivkeller](https://github.com/avivkeller)! - perf: build the site one page at a time, and `all.html` from the module pages
+
+- [#1057](https://github.com/nodejs/doc-kit/pull/1057) [`da5d8e6`](https://github.com/nodejs/doc-kit/commit/da5d8e63d0d33fe7a95c46afb8d5140d576827b4) Thanks [@avivkeller](https://github.com/avivkeller)! - feat: `dependent` generators and the `section-pages` generator
+
 ## 1.0.1
 
 ### Patch Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doc-kit/core",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The doc-kit engine: the pipeline and shared APIs that power the doc-kit generators and CLI",
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   ],
   "dependencies": {
     "@actions/core": "^3.0.0",
-    "@node-core/rehype-shiki": "^1.4.3",
+    "@node-core/rehype-shiki": "^1.5.0",
     "@swc/html-wasm": "^1.15.46",
     "@swc/wasm": "^1.15.46",
     "acorn": "^8.17.0",
@@ -53,7 +53,7 @@
     "github-slugger": "^2.0.0",
     "glob-parent": "^6.0.2",
     "hastscript": "^9.0.1",
-    "piscina": "^5.3.0",
+    "piscina": "^5.3.1",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-mdx": "^3.1.1",
@@ -61,7 +61,7 @@
     "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
     "semver": "^7.8.5",
-    "shiki": "^4.3.0",
+    "shiki": "^4.4.3",
     "tinyglobby": "^0.2.17",
     "unified": "^11.0.5",
     "unist-builder": "^4.0.0",

package/src/generators/index.mjs

@@ -22,6 +22,7 @@ export const publicGenerators = {
   'llms-txt': '@doc-kit/generator-react/llms-txt',
   sitemap: '@doc-kit/generator-react/sitemap',
   html: '@doc-kit/generator-react/html',
+  'section-pages': '@doc-kit/generator-react/section-pages',
 };
 
 // These ones are special since they don't produce standard output,

package/src/generators/loader.mjs

@@ -3,6 +3,8 @@
 import { isAbsolute } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { enforceArray } from '#utils/array.mjs';
+
 import { allGenerators } from './index.mjs';
 
 /**
@@ -67,7 +69,7 @@ export const loadGenerator = async specifier => {
 
 /**
  * Loads the given generators plus the transitive closure of their
- * dependencies (via `dependsOn`).
+ * dependencies (via `dependsOn`) and dependents (via `dependent`).
  *
  * @param {string[]} targets - Shorthand names, paths, or import specifiers
  * @returns {Promise<Map<string, GeneratorMetadata>>} Loaded generators keyed
@@ -87,8 +89,11 @@ export const loadGenerators = async targets => {
     const generator = await loadGenerator(specifier);
     generators.set(specifier, generator);
 
-    if (generator.dependsOn) {
-      queue.push(resolveGeneratorSpecifier(generator.dependsOn));
+    for (const related of [
+      ...enforceArray(generator.dependsOn ?? []),
+      ...enforceArray(generator.dependent ?? []),
+    ]) {
+      queue.push(resolveGeneratorSpecifier(related));
     }
   }
 

package/src/generators/metadata/types.d.ts

@@ -120,6 +120,23 @@ export interface StabilityData extends Data {
  */
 export type StabilityNode = NodeWithData<Blockquote, StabilityData>;
 
+/**
+ * Describes a chunk page: a section of a module rendered as a page of its own
+ * (see the `section-pages` generator). Present on every entry of a chunk page.
+ */
+export interface ChunkInfo {
+  /** The `api` of the module the chunk was split from */
+  api: string;
+  /** The `path` of the module the chunk was split from */
+  path: string;
+  /** The section's anchor on the full module page */
+  slug: string;
+  /** The chunk's position within the module, in document order */
+  index: number;
+  /** The original depth of the chunk's heading */
+  depth: number;
+}
+
 /**
  * Complete metadata entry for a single API documentation element.
  *
@@ -136,6 +153,8 @@ export interface MetadataEntry extends YAMLProperties {
   synthetic?: boolean;
   /** Whether this page was authored as MDX (JSX-in-Markdown). */
   mdx?: boolean;
+  /** Set when this entry belongs to a chunk page rather than a full page. */
+  chunk?: ChunkInfo;
   /** Processed heading with metadata */
   heading: HeadingNode;
   /** Stability classification information */

package/src/generators/pipeline.mjs

@@ -0,0 +1,169 @@
+'use strict';
+
+import { enforceArray } from '#utils/array.mjs';
+
+import { resolveGeneratorSpecifier } from './loader.mjs';
+
+/**
+ * The resolved specifiers of the generators a generator is delivered through.
+ *
+ * @param {GeneratorMetadata | undefined} generator
+ * @returns {string[]}
+ */
+const dependentsOf = generator =>
+  enforceArray(generator?.dependent ?? []).map(resolveGeneratorSpecifier);
+
+/**
+ * Collects the generators reached from the given ones through `dependsOn`.
+ *
+ * @param {string[]} specifiers - Resolved generator specifiers
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+ * @returns {Set<string>}
+ */
+const dependencyClosure = (specifiers, generators) => {
+  const closure = new Set();
+  const stack = [...specifiers];
+
+  while (stack.length > 0) {
+    const specifier = stack.pop();
+
+    if (closure.has(specifier)) {
+      continue;
+    }
+
+    closure.add(specifier);
+
+    const { dependsOn } = generators.get(specifier) ?? {};
+
+    if (dependsOn) {
+      stack.push(resolveGeneratorSpecifier(dependsOn));
+    }
+  }
+
+  return closure;
+};
+
+/**
+ * Splices a generator into a dependent's pipeline: walking from the dependent
+ * up its dependency chain, the first generator that consumes the splicing
+ * generator's own input is rewired to consume the splicing generator instead.
+ *
+ * @param {string} specifier - The generator to splice in
+ * @param {string} dependent - The pipeline to splice it into
+ * @param {Map<string, string | undefined>} inputOf - Effective inputs, mutated
+ * @param {string} name - The splicing generator's name, for errors
+ */
+const splice = (specifier, dependent, inputOf, name) => {
+  const upstream = inputOf.get(specifier);
+  const visited = new Set();
+
+  let current = dependent;
+
+  while (current !== undefined && current !== specifier) {
+    if (visited.has(current)) {
+      break;
+    }
+
+    visited.add(current);
+
+    if (inputOf.get(current) === upstream) {
+      inputOf.set(current, specifier);
+      return;
+    }
+
+    current = inputOf.get(current);
+  }
+
+  throw new Error(
+    `Generator "${name}" declares "${dependent}" as its dependent, but ` +
+      `nothing in that pipeline consumes "${upstream ?? 'no input'}", so ` +
+      'there is nowhere to splice it in.'
+  );
+};
+
+/**
+ * Follows a generator's `dependent` links to the generators that finally
+ * deliver its output. When some of its dependents are already part of the
+ * run, only those deliver it; otherwise all of them do.
+ *
+ * @param {string} specifier - Resolved generator specifier
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+ * @param {Set<string>} requested - Generators already part of the run
+ * @param {Set<string>} [seen] - Guards against dependent cycles
+ * @returns {string[]} Resolved specifiers of the terminal generators
+ */
+const resolveTerminals = (
+  specifier,
+  generators,
+  requested,
+  seen = new Set()
+) => {
+  if (seen.has(specifier)) {
+    return [];
+  }
+
+  seen.add(specifier);
+
+  const dependents = dependentsOf(generators.get(specifier));
+
+  if (dependents.length === 0) {
+    return [specifier];
+  }
+
+  const active = dependents.filter(dependent => requested.has(dependent));
+
+  return (active.length > 0 ? active : dependents).flatMap(dependent =>
+    resolveTerminals(dependent, generators, requested, seen)
+  );
+};
+
+/**
+ * Resolves the effective pipeline for a run: which generator each generator
+ * reads its input from, and which generators the run finally collects.
+ *
+ * By default a generator reads from its `dependsOn`. A generator that declares
+ * one or more `dependent`s is spliced into each dependent's pipeline (see
+ * {@link splice}). Several generators may splice at the same point; each later
+ * one is inserted upstream of the earlier ones, forming a chain.
+ *
+ * A requested generator that declares dependents is delivered through them,
+ * so the run collects their output rather than the generator's own: through
+ * the dependents that are already part of the run when there are any, and
+ * through all of them otherwise.
+ *
+ * @param {string[]} targets - Requested targets, as resolved specifiers
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators,
+ * including every dependency and dependent of the targets
+ * @returns {{ targets: string[], inputOf: Map<string, string | undefined> }}
+ * The generators to collect, and each generator's effective input generator
+ */
+export const resolvePipeline = (targets, generators) => {
+  /** @type {Map<string, string | undefined>} */
+  const inputOf = new Map();
+
+  for (const [specifier, { dependsOn }] of generators) {
+    inputOf.set(
+      specifier,
+      dependsOn ? resolveGeneratorSpecifier(dependsOn) : undefined
+    );
+  }
+
+  for (const [specifier, generator] of generators) {
+    for (const dependent of dependentsOf(generator)) {
+      splice(specifier, dependent, inputOf, generator.name);
+    }
+  }
+
+  const requested = dependencyClosure(targets, generators);
+  const collected = [];
+
+  for (const target of targets) {
+    for (const terminal of resolveTerminals(target, generators, requested)) {
+      if (!collected.includes(terminal)) {
+        collected.push(terminal);
+      }
+    }
+  }
+
+  return { targets: collected, inputOf };
+};

package/src/generators/types.d.ts

@@ -97,6 +97,26 @@ declare global {
      */
     dependsOn: string | undefined;
 
+    /**
+     * The generator(s) this generator's output is delivered through, declared
+     * as import specifiers. This is the inverse of `dependsOn`: rather than
+     * pulling a dependency in, it pushes this generator into another
+     * generator's pipeline.
+     *
+     * The orchestrator splices this generator in front of the first generator
+     * in each dependent's dependency chain that consumes the same `dependsOn`
+     * as this one. For example, a generator with
+     * `dependsOn: '@doc-kit/core/metadata'` and
+     * `dependent: '@doc-kit/generator-react/html'` is inserted between
+     * `metadata` and `jsx-ast` (the consumer of `metadata` on the way to
+     * `html`), so its output is what `jsx-ast` — and therefore `html` — sees.
+     *
+     * Requesting a generator that declares dependents runs them as well, and
+     * the run's result is their output: when some of the dependents are
+     * already part of the run, only those; otherwise all of them.
+     */
+    dependent?: string | string[];
+
     /**
      * Generators are abstract and the different generators have different sort of inputs and outputs.
      * For example, a MDX generator would take the raw AST and output MDX with React Components;

package/src/generators.mjs

@@ -5,6 +5,7 @@ import {
   loadGenerators,
   resolveGeneratorSpecifier,
 } from './generators/loader.mjs';
+import { resolvePipeline } from './generators/pipeline.mjs';
 import logger from './logger/index.mjs';
 import createWorkerPool from './threading/index.mjs';
 import createParallelWorker from './threading/parallel.mjs';
@@ -44,9 +45,12 @@ const createGenerator = () => {
    *
    * @param {string} specifier - Resolved generator specifier to schedule
    * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+   * @param {Map<string, string | undefined>} inputOf - Each generator's
+   * effective input generator (its dependency, unless another generator was
+   * spliced in front of it via `dependent`)
    * @param {import('./utils/configuration/types').Configuration} configuration - Runtime options
    */
-  const scheduleGenerator = (specifier, generators, configuration) => {
+  const scheduleGenerator = (specifier, generators, inputOf, configuration) => {
     if (cache.has(specifier)) {
       return;
     }
@@ -54,12 +58,11 @@ const createGenerator = () => {
     const generator = generators.get(specifier);
     const { name, generate, hasParallelProcessor } = generator;
 
-    const dependsOn =
-      generator.dependsOn && resolveGeneratorSpecifier(generator.dependsOn);
+    const dependsOn = inputOf.get(specifier);
 
     // Schedule dependency first
     if (dependsOn && !cache.has(dependsOn)) {
-      scheduleGenerator(dependsOn, generators, configuration);
+      scheduleGenerator(dependsOn, generators, inputOf, configuration);
     }
 
     generatorsLogger.debug(`Scheduling "${name}"`, {
@@ -104,8 +107,16 @@ const createGenerator = () => {
 
     // Resolve shorthand names and load the full dependency closure up front,
     // so scheduling below is fully synchronous.
-    const targets = target.map(resolveGeneratorSpecifier);
-    const generators = await loadGenerators(targets);
+    const generators = await loadGenerators(
+      target.map(resolveGeneratorSpecifier)
+    );
+
+    // Work out who reads from whom once generators declaring a `dependent`
+    // have been spliced in, and which generators the run finally collects.
+    const { targets, inputOf } = resolvePipeline(
+      target.map(resolveGeneratorSpecifier),
+      generators
+    );
 
     generatorsLogger.debug(`Starting pipeline`, {
       generators: targets.join(', '),
@@ -114,18 +125,14 @@ const createGenerator = () => {
 
     // Compute consumer counts up front so dependencies can be evicted as soon
     // as their last consumer runs (must be ready before any generator starts).
-    cache.populateConsumerCounts(targets, specifier => {
-      const { dependsOn } = generators.get(specifier);
-
-      return dependsOn && resolveGeneratorSpecifier(dependsOn);
-    });
+    cache.populateConsumerCounts(targets, specifier => inputOf.get(specifier));
 
     // Create worker pool
     pool = createWorkerPool(threads);
 
     // Schedule all generators
     for (const specifier of targets) {
-      scheduleGenerator(specifier, generators, configuration);
+      scheduleGenerator(specifier, generators, inputOf, configuration);
     }
 
     // Start all collections in parallel (don't await sequentially). Consuming

package/src/parsers/markdown.mjs

@@ -22,9 +22,7 @@ const NODE_LTS_VERSION_REGEX = /Long Term Support/i;
 export const parseChangelog = async path => {
   const changelog = await loadFromURL(path);
 
-  const nodeMajors = Array.from(changelog.matchAll(NODE_VERSIONS_REGEX));
-
-  return nodeMajors.map(match => ({
+  return Array.from(changelog.matchAll(NODE_VERSIONS_REGEX), match => ({
     version: coerce(match[1]),
     isLts: NODE_LTS_VERSION_REGEX.test(match[2]),
   }));
@@ -43,7 +41,8 @@ export const parseIndex = async path => {
 
   const index = await loadFromURL(path);
 
-  const items = Array.from(index.matchAll(LIST_ITEM_REGEX));
-
-  return items.map(([, section, api]) => ({ section, api }));
+  return Array.from(index.matchAll(LIST_ITEM_REGEX), ([, section, api]) => ({
+    section,
+    api,
+  }));
 };

package/src/utils/configuration/constants.mjs

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * The default `threads` ceiling. Each worker that highlights code holds Shiki's
+ * grammars and regex engine (~300MB) on top of the pages it is building, so
+ * past a few threads memory, not CPU, is what runs out. `--threads` raises it.
+ */
+export const DEFAULT_MAX_THREADS = 4;
+
+/**
+ * The default number of items each worker task processes.
+ */
+export const DEFAULT_CHUNK_SIZE = 10;

package/src/utils/configuration/index.mjs

@@ -18,6 +18,8 @@ import { enforceArray } from '#utils/array.mjs';
 import { leftHandAssign } from '#utils/generators.mjs';
 import { deepMerge } from '#utils/misc.mjs';
 
+import { DEFAULT_CHUNK_SIZE, DEFAULT_MAX_THREADS } from './constants.mjs';
+
 const configExplorer = cosmiconfig('doc-kit');
 
 /**
@@ -68,8 +70,11 @@ export const getDefaultConfig = (generators, config) =>
       // riscv64 with sv39. Running multiple generators that use wasm in
       // parallel could cause failures to allocate new wasm instance.
       // See also https://github.com/nodejs/node/pull/60591
-      threads: process.arch === 'riscv64' ? 1 : cpus().length,
-      chunkSize: 10,
+      threads:
+        process.arch === 'riscv64'
+          ? 1
+          : Math.min(cpus().length, DEFAULT_MAX_THREADS),
+      chunkSize: DEFAULT_CHUNK_SIZE,
     })
   );
 

package/src/utils/remark-shiki.mjs

@@ -0,0 +1,29 @@
+'use strict';
+
+import rehypeStringify from 'rehype-stringify';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+
+import syntaxHighlighter from './highlighter.mjs';
+import { lazy } from './misc.mjs';
+import { rehypeOptions } from './remark.mjs';
+
+/**
+ * Retrieves an instance of Remark configured to output stringified HTML code
+ * including parsing Code Boxes with syntax highlighting.
+ *
+ * This lives apart from `./remark.mjs` because importing it loads Shiki (every
+ * grammar plus the regex engine, ~250MB per process). Only the generators that
+ * highlight code — `legacy-html` here — should pay for that.
+ */
+export const getRemarkRehypeWithShiki = lazy(() =>
+  unified()
+    .use(remarkParse)
+    // legacy-html gets the minimal (unhighlighted) type rendering
+    .use(remarkRehype, rehypeOptions)
+    // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
+    // and transform them into HAST nodes
+    .use(syntaxHighlighter)
+    .use(rehypeStringify, { allowDangerousHtml: true })
+);

package/src/utils/remark.mjs

@@ -8,13 +8,13 @@ import remarkRehype from 'remark-rehype';
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 
-import syntaxHighlighter from './highlighter.mjs';
 import { lazy } from './misc.mjs';
 import { typeAnnotationToHast } from './type-annotations/hast.mjs';
 import remarkTypeAnnotations from './type-annotations/remark.mjs';
 
-// Nodes the rehype pipelines pass through untouched.
-const passThrough = ['element'];
+// Nothing in this module loads Shiki: the `ast` and `metadata` stages (and
+// every worker that runs them) import it, and none of them highlight code.
+// The highlighting pipeline lives in `./remark-shiki.mjs`.
 
 /**
  * Renders an MDX JSX element as just its children, so the surrounding prose
@@ -30,15 +30,28 @@ const mdxElementToChildren = (state, node) => state.all(node);
  */
 const dropNode = () => undefined;
 
-// The HTML-string pipelines cannot render MDX nodes (rendering those is the
-// React generators' job): JSX elements degrade to their children so the
-// surrounding prose still renders, and expressions/ESM are dropped.
-const mdxToHastHandlers = {
-  mdxJsxTextElement: mdxElementToChildren,
-  mdxJsxFlowElement: mdxElementToChildren,
-  mdxFlowExpression: dropNode,
-  mdxTextExpression: dropNode,
-  mdxjsEsm: dropNode,
+/**
+ * The `remark-rehype` options shared by the HTML-string pipelines.
+ *
+ * Existing HTML nodes pass through untouched (they were created during the
+ * rehype process), and dangerous HTML is allowed since the Markdown sources
+ * are trusted. The MDX node types cannot be rendered to an HTML string (that
+ * is the React generators' job): JSX elements degrade to their children so the
+ * surrounding prose still renders, and expressions/ESM are dropped.
+ *
+ * @type {import('remark-rehype').Options}
+ */
+export const rehypeOptions = {
+  allowDangerousHtml: true,
+  passThrough: ['element'],
+  handlers: {
+    typeAnnotation: typeAnnotationToHast,
+    mdxJsxTextElement: mdxElementToChildren,
+    mdxJsxFlowElement: mdxElementToChildren,
+    mdxFlowExpression: dropNode,
+    mdxTextExpression: dropNode,
+    mdxjsEsm: dropNode,
+  },
 };
 
 /**
@@ -72,41 +85,6 @@ export const getRemarkMdx = lazy(() =>
 export const getRemarkRehype = lazy(() =>
   unified()
     .use(remarkParse)
-    // We make Rehype ignore existing HTML nodes (just the node itself, not its children)
-    // as these are nodes we manually created during the rehype process
-    // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(remarkRehype, {
-      allowDangerousHtml: true,
-      passThrough,
-      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
-    })
-    // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(rehypeStringify, { allowDangerousHtml: true })
-);
-
-/**
- * Retrieves an instance of Remark configured to output stringified HTML code
- * including parsing Code Boxes with syntax highlighting
- */
-export const getRemarkRehypeWithShiki = lazy(() =>
-  unified()
-    .use(remarkParse)
-    // We make Rehype ignore existing HTML nodes (just the node itself, not its children)
-    // as these are nodes we manually created during the rehype process
-    // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(remarkRehype, {
-      allowDangerousHtml: true,
-      passThrough,
-      // legacy-html gets the minimal (unhighlighted) type rendering
-      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
-    })
-    // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
-    // and transform them into HAST nodes
-    .use(syntaxHighlighter)
-    // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
+    .use(remarkRehype, rehypeOptions)
     .use(rehypeStringify, { allowDangerousHtml: true })
 );

package/src/utils/type-annotations/hast.mjs

@@ -1,9 +1,5 @@
 'use strict';
 
-import { highlighter } from '#utils/highlighter.mjs';
-
-const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes();
-
 /**
  * Slices a type's text by its resolved link ranges into hast children —
  * plain text segments interleaved with `<a class="type-link">` anchors.
@@ -59,57 +55,3 @@ export const typeAnnotationToHast = (state, node) => {
 
   return state.applyData(node, result);
 };
-
-/**
- * Syntax-highlighted mdast→hast handler for `typeAnnotation` nodes, used by
- * the web (JSX) pipeline. The whole type is highlighted as one inline
- * fragment, and each resolved identifier's exact character range is wrapped
- * in an `<a>` via Shiki decorations. Values that are not TypeScript (display
- * names such as `HTTP/2 Headers Object`) are highlighted as plain text, so
- * their prose is not coloured as operators and numeric literals.
- *
- * Falls back to the minimal handler when the type failed to parse or nothing
- * resolved (no point paying for highlighting then).
- *
- * @param {import('mdast-util-to-hast').State} state
- * @param {import('mdast').Node} node
- * @returns {import('hast').Element}
- */
-export const typeAnnotationToHighlightedHast = (state, node) => {
-  const links = node.data?.links ?? [];
-
-  if (node.data?.parseError || links.length === 0) {
-    return typeAnnotationToHast(state, node);
-  }
-
-  const root = highlighter.shiki.codeToHast(node.value, {
-    lang: node.data?.typescript ? 'typescript' : 'text',
-    themes: { light: lightTheme, dark: darkTheme },
-    decorations: links.map(({ start, end, href }) => ({
-      start,
-      end,
-      tagName: 'a',
-      properties: { href, class: 'type-link' },
-      alwaysWrap: true,
-    })),
-  });
-
-  // codeToHast wraps the highlighted line in <pre><code>; re-shape that into
-  // a single inline <code> element ("only the outermost type opens/closes
-  // the code fragment")
-  const [preElement] = root.children;
-  const [codeElement] = preElement.children;
-
-  const result = {
-    type: 'element',
-    tagName: 'code',
-    properties: {
-      class: `${preElement.properties.class} type`,
-    },
-    children: codeElement.children,
-  };
-
-  state.patch(node, result);
-
-  return state.applyData(node, result);
-};

package/src/utils/type-annotations/highlighted.mjs

@@ -0,0 +1,64 @@
+'use strict';
+
+import { highlighter } from '#utils/highlighter.mjs';
+
+import { typeAnnotationToHast } from './hast.mjs';
+
+// Kept apart from `./hast.mjs` on purpose: importing this module loads Shiki
+// (every grammar plus the regex engine), which only the pipelines that
+// highlight should pay for. The `ast` and `metadata` stages never do.
+const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes();
+
+/**
+ * Syntax-highlighted mdast→hast handler for `typeAnnotation` nodes, used by
+ * the web (JSX) pipeline. The whole type is highlighted as one inline
+ * fragment, and each resolved identifier's exact character range is wrapped
+ * in an `<a>` via Shiki decorations. Values that are not TypeScript (display
+ * names such as `HTTP/2 Headers Object`) are highlighted as plain text, so
+ * their prose is not coloured as operators and numeric literals.
+ *
+ * Falls back to the minimal handler when the type failed to parse or nothing
+ * resolved (no point paying for highlighting then).
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('mdast').Node} node
+ * @returns {import('hast').Element}
+ */
+export const typeAnnotationToHighlightedHast = (state, node) => {
+  const links = node.data?.links ?? [];
+
+  if (node.data?.parseError || links.length === 0) {
+    return typeAnnotationToHast(state, node);
+  }
+
+  const root = highlighter.shiki.codeToHast(node.value, {
+    lang: node.data?.typescript ? 'typescript' : 'text',
+    themes: { light: lightTheme, dark: darkTheme },
+    decorations: links.map(({ start, end, href }) => ({
+      start,
+      end,
+      tagName: 'a',
+      properties: { href, class: 'type-link' },
+      alwaysWrap: true,
+    })),
+  });
+
+  // codeToHast wraps the highlighted line in <pre><code>; re-shape that into
+  // a single inline <code> element ("only the outermost type opens/closes
+  // the code fragment")
+  const [preElement] = root.children;
+  const [codeElement] = preElement.children;
+
+  const result = {
+    type: 'element',
+    tagName: 'code',
+    properties: {
+      class: `${preElement.properties.class} type`,
+    },
+    children: codeElement.children,
+  };
+
+  state.patch(node, result);
+
+  return state.applyData(node, result);
+};