@ng-doc/utils 22.0.0-beta.2 → 22.1.0

package/index.esm.js

@@ -2,11 +2,14 @@ import rehypeMinifyWhitespace from 'rehype-minify-whitespace';
 import rehypeParse from 'rehype-parse';
 import rehypeStringify from 'rehype-stringify';
 import { unified } from 'unified';
-import { KEYWORD_ALLOWED_LANGUAGES, asArray, NG_DOC_ELEMENT } from '@ng-doc/core';
+import { KEYWORD_ALLOWED_LANGUAGES, asArray, NG_DOC_ELEMENT, NG_DOC_SYNTAX_THEME_NAME, ngDocSyntaxTheme } from '@ng-doc/core';
 import { isElement as isElement$1 } from 'hast-util-is-element';
 import { toString } from 'hast-util-to-string';
 import { visitParents, SKIP } from 'unist-util-visit-parents';
 import rehypeShiki from '@shikijs/rehype';
+import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
+import { createHash } from 'node:crypto';
+import { createHighlighter, bundledLanguages } from 'shiki';
 import { visit } from 'unist-util-visit';
 import GithubSlugger from 'github-slugger';
 import { hasProperty } from 'hast-util-has-property';
@@ -90,8 +93,472 @@ function isHeading(node) {
     return isElement$1(node, HEADINGS);
 }
 
+/**
+ * Where a keyword may link inside code.
+ *
+ * The keywords plugin splits code into words and looks each one up. A word that happens to be a
+ * keyword is not always a reference to it: an object key (`group: 'Colors'`), a property after a
+ * dot, a string, an HTML attribute value or a file name in inline code (`vite.config.mjs`) only
+ * share its name. Highlighted code carries no token scopes (Shiki emits colours only, and adjacent
+ * tokens of one colour are merged), so this module reads the position of a word from the code text
+ * itself with a small lexer: strings and comments, the characters around the word, and the names
+ * the code declares. The result only depends on the code, never on the keyword set, so the words a
+ * page records as used keywords are exactly the ones that may link.
+ */
+const WORD_CHARACTER = /[*\p{L}\w$@-]/u;
+const IDENTIFIER_BEFORE = /[\p{L}\w$@-]+$/u;
+const WHOLE_KEYWORD = /^\s*[*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?\s*$/u;
+/** Characters that make inline code read as TypeScript rather than as a name, path or prose. */
+const CODE_PUNCTUATION = /[(){}[\]<>|:=@]/;
+/** Inline code that starts like a TypeScript declaration. */
+const DECLARATION_START = /^\s*(?:export|import|class|interface|type|const|let|var|function|enum|abstract|declare)\s/;
+/** Inline code that starts with an HTML tag. */
+const HTML_START = /^\s*<\/?[A-Za-z]/;
+/** Syntax words. They never link, even before `(` (`if (`, `function (`, `super(`). */
+const SYNTAX_WORDS = new Set([
+    'await',
+    'break',
+    'case',
+    'catch',
+    'continue',
+    'debugger',
+    'delete',
+    'do',
+    'else',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'instanceof',
+    'new',
+    'null',
+    'return',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+/**
+ * TypeScript keywords and modifiers that are also valid names. They link only when called, so that
+ * RxJS `of(…)` and `from(…)` still link while `readonly` in `readonly size = input()` or `from`
+ * in an import does not.
+ */
+const RESERVED_WORDS = new Set([
+    'abstract',
+    'accessor',
+    'any',
+    'as',
+    'asserts',
+    'async',
+    'bigint',
+    'boolean',
+    'class',
+    'const',
+    'constructor',
+    'declare',
+    'default',
+    'enum',
+    'export',
+    'extends',
+    'from',
+    'get',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'number',
+    'object',
+    'of',
+    'out',
+    'override',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'symbol',
+    'type',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+]);
+/** The characters before a name in a type position: `: Type`, `A | B`, `A & B`, `Generic<Type`. */
+const TYPE_CONTEXT = [':', '|', '&', '<'];
+/** The words before a name in a type position, or before a type alias's name. */
+const TYPE_WORDS = ['type', 'extends', 'keyof', 'typeof'];
+/** What a character of code is, in a scan's marks. */
+const CODE = 0;
+const STRING = 1;
+const COMMENT = 2;
+/** The text of a TypeScript template literal, outside its `${…}` expressions. */
+const TEMPLATE = 3;
+/** An Angular control flow block in an inline template (`@if`, `@for`, `@defer`). */
+const CONTROL_FLOW = /^@[a-z]+$/;
+const NOT_A_REFERENCE = Object.freeze({ link: false });
+const REFERENCE = Object.freeze({ link: true });
+/**
+ * The positions of the words of inline code, or `undefined` when no word of it may link.
+ *
+ * Inline code links when it is one keyword reference as a whole (`NgDocPage`, `*GuidePage#anchor`,
+ * `NgDocPage.title`, with an optional `?query`), or when it reads as TypeScript: it contains code
+ * punctuation (a call, generics, a union, an array type, a decorator, a type annotation) or starts
+ * with a declaration. Then its words link where they would in a TypeScript code block. Anything
+ * else (a file name like `vite.ng-doc.config.mjs`, a path, a command, prose, an HTML tag) stays
+ * plain text.
+ * @param text - The text of the inline code element.
+ */
+function scanInlineCode(text) {
+    if (WHOLE_KEYWORD.test(text)) {
+        return { whole: true, position: () => REFERENCE };
+    }
+    if (HTML_START.test(text) || !(CODE_PUNCTUATION.test(text) || DECLARATION_START.test(text))) {
+        return undefined;
+    }
+    const scan = scanTypeScript(text);
+    // A message or a sentence with some punctuation (`Refusing to overwrite unowned output`) is not
+    // code: TypeScript never has three plain names in a row.
+    return isProse(text, scan.masked) ? undefined : scan;
+}
+/**
+ * The positions of the words of a code block.
+ * @param text - The text of the block's `code` element.
+ * @param mode - How the block's language is read.
+ */
+function scanCodeBlock(text, mode) {
+    return mode === 'html' ? scanHtml(text) : scanTypeScript(text);
+}
+/**
+ * TypeScript: a word links unless it is inside a string or a comment (in a template literal, only
+ * Angular control flow blocks and the names of custom elements link), a syntax word, a reserved
+ * word that is not called, a property after a dot (it then links only as a whole `Owner.member`
+ * keyword), a declared name (an object key, a property, a parameter or a variable before `:`,
+ * `?:`, `!:` or `=`), or a name the code binds itself (`const`/`let`/`var`, or an import from a
+ * relative module).
+ * @param text - The code.
+ */
+function scanTypeScript(text) {
+    const masked = maskTypeScript(text);
+    const locals = localBindings(text, masked);
+    return {
+        whole: false,
+        masked,
+        position(start, end, key) {
+            if (masked[start] === TEMPLATE) {
+                // A template literal is usually an inline Angular template: its control flow blocks and
+                // the names of custom elements (`<ng-content>`, `</ng-container>`; a standard element
+                // such as `<input>` has no dash) refer to Angular and components, while its attributes
+                // and text are the template's own.
+                const before = text[start - 1] ?? '';
+                const element = key.includes('-') && (before === '<' || (before === '/' && text[start - 2] === '<'));
+                const controlFlow = CONTROL_FLOW.test(key) && !WORD_CHARACTER.test(before);
+                return element || controlFlow ? REFERENCE : NOT_A_REFERENCE;
+            }
+            if (masked[start] !== CODE) {
+                return NOT_A_REFERENCE;
+            }
+            const previous = previousSignificant(text, start, masked);
+            const next = nextSignificant(text, end, masked);
+            const nextCharacter = text[next] ?? '';
+            if (SYNTAX_WORDS.has(key) || (RESERVED_WORDS.has(key) && nextCharacter !== '(')) {
+                return NOT_A_REFERENCE;
+            }
+            if (text[previous] === '.' && text[previous - 1] !== '.') {
+                // `owner.member` and `owner?.member`
+                const ownerEnd = text[previous - 1] === '?' ? previous - 1 : previous;
+                const owner = text.slice(0, ownerEnd).match(IDENTIFIER_BEFORE)?.[0];
+                const word = text.slice(start, end);
+                return owner && !/[.#]/.test(word)
+                    ? { link: true, keyword: `${owner}.${key.toLowerCase()}` }
+                    : NOT_A_REFERENCE;
+            }
+            if (isDeclaredName(text, masked, previous, next)) {
+                return NOT_A_REFERENCE;
+            }
+            return locals.has(key) ? NOT_A_REFERENCE : REFERENCE;
+        },
+    };
+}
+/**
+ * Whether the word between `previous` and `next` is a name being declared rather than used.
+ * @param text - The code.
+ * @param masked - The marks of its strings and comments.
+ * @param previous - The index of the significant character before the word, or -1.
+ * @param next - The index of the significant character after the word.
+ */
+function isDeclaredName(text, masked, previous, next) {
+    const after = text[next];
+    const afterNext = text[nextSignificant(text, next + 1, masked)];
+    if (after === ':' && text[next + 1] !== ':') {
+        // `cond ? Value : other` and `case Value:` use the name.
+        const ternary = text[previous] === '?' && text[previous + 1] !== '.';
+        return !ternary && previousWord(text, previous) !== 'case';
+    }
+    if ((after === '?' || after === '!') && afterNext === ':') {
+        return true;
+    }
+    if (after === '?' && (afterNext === ')' || afterNext === ',')) {
+        return true;
+    }
+    if (after === '=' && text[next + 1] !== '=' && text[next + 1] !== '>') {
+        // A type before `=` (`size: NgDocSize = …`, `<T extends Base = Base>`) is used, and
+        // `type Name = …` declares a type alias, which is linked like a class.
+        return (!TYPE_CONTEXT.includes(text[previous] ?? '') &&
+            !TYPE_WORDS.includes(previousWord(text, previous)));
+    }
+    return false;
+}
+/**
+ * HTML: a word links unless it is inside a comment or an attribute value. Which keywords may link
+ * in HTML at all (the selectors of components and directives) is decided by their languages.
+ * @param text - The code.
+ */
+function scanHtml(text) {
+    const masked = maskHtml(text);
+    return {
+        whole: false,
+        position: (start) => (masked[start] === CODE ? REFERENCE : NOT_A_REFERENCE),
+    };
+}
+/**
+ * Marks the characters of TypeScript strings and comments. The `${…}` expressions of template
+ * literals stay code. Regular expression literals are not recognised.
+ * @param text - The code.
+ */
+function maskTypeScript(text) {
+    const masked = new Uint8Array(text.length);
+    // The brace depth of every open `${` of a template literal, innermost last.
+    const templates = [];
+    let depth = 0;
+    let index = 0;
+    const string = (quote) => {
+        const start = index++;
+        while (index < text.length && text[index] !== quote && text[index] !== '\n') {
+            index += text[index] === '\\' ? 2 : 1;
+        }
+        masked.fill(STRING, start, Math.min(++index, text.length));
+    };
+    const template = () => {
+        const start = index++;
+        while (index < text.length && text[index] !== '`') {
+            if (text[index] === '\\') {
+                index += 2;
+            }
+            else if (text[index] === '$' && text[index + 1] === '{') {
+                masked.fill(TEMPLATE, start, index);
+                templates.push(depth);
+                index += 2;
+                return;
+            }
+            else {
+                index++;
+            }
+        }
+        masked.fill(TEMPLATE, start, Math.min(++index, text.length));
+    };
+    while (index < text.length) {
+        const character = text[index];
+        if (character === '/' && text[index + 1] === '/') {
+            const end = text.indexOf('\n', index);
+            const stop = end < 0 ? text.length : end;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (character === '/' && text[index + 1] === '*') {
+            const end = text.indexOf('*/', index + 2);
+            const stop = end < 0 ? text.length : end + 2;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (character === "'" || character === '"') {
+            string(character);
+        }
+        else if (character === '`') {
+            template();
+        }
+        else if (character === '{') {
+            depth++;
+            index++;
+        }
+        else if (character === '}') {
+            if (templates.length && templates[templates.length - 1] === depth) {
+                // The end of a `${…}` expression: the template literal goes on.
+                templates.pop();
+                template();
+            }
+            else {
+                depth--;
+                index++;
+            }
+        }
+        else {
+            index++;
+        }
+    }
+    return masked;
+}
+/**
+ * Marks the characters of HTML comments and attribute values.
+ * @param text - The code.
+ */
+function maskHtml(text) {
+    const masked = new Uint8Array(text.length);
+    let index = 0;
+    while (index < text.length) {
+        if (text.startsWith('<!--', index)) {
+            const end = text.indexOf('-->', index + 4);
+            const stop = end < 0 ? text.length : end + 3;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (text[index] === '<' && /[A-Za-z/]/.test(text[index + 1] ?? '')) {
+            index = maskTag(text, index + 1, masked);
+        }
+        else {
+            index++;
+        }
+    }
+    return masked;
+}
+/**
+ * Marks the attribute values of the tag that starts at `index` and returns the index after it.
+ * @param text - The code.
+ * @param index - The index after the tag's `<`.
+ * @param masked - The marks.
+ */
+function maskTag(text, index, masked) {
+    while (index < text.length && text[index] !== '>') {
+        if (text[index] !== '=') {
+            index++;
+            continue;
+        }
+        index++;
+        while (text[index] === ' ' || text[index] === '\t' || text[index] === '\n')
+            index++;
+        const quote = text[index];
+        const start = index;
+        if (quote === '"' || quote === "'") {
+            const end = text.indexOf(quote, index + 1);
+            index = end < 0 ? text.length : end + 1;
+        }
+        else {
+            while (index < text.length && !/[\s>]/.test(text[index] ?? ''))
+                index++;
+        }
+        masked.fill(STRING, start, index);
+    }
+    return index + 1;
+}
+/**
+ * The names the code binds itself: `const`, `let` and `var` declarations and the names imported
+ * from relative modules. A use of such a name refers to the code's own binding, not to a keyword
+ * of the same name (`const config = …; export default config;`).
+ * @param text - The code.
+ * @param masked - The marks of its strings and comments.
+ */
+function localBindings(text, masked) {
+    const names = new Set();
+    for (const match of text.matchAll(/\b(?:const|let|var)\s+([\p{L}_$][\p{L}\w$]*)/gu)) {
+        if (!masked[match.index])
+            names.add(match[1] ?? '');
+    }
+    for (const match of text.matchAll(/\bimport\s+(?:type\s+)?([^;]*?)\s+from\s+(['"])\.{1,2}\/[^'"]*\2/gu)) {
+        if (masked[match.index])
+            continue;
+        for (const name of (match[1] ?? '').matchAll(/([\p{L}_$][\p{L}\w$]*)(?:\s+as\s+([\p{L}_$][\p{L}\w$]*))?/gu)) {
+            const local = name[2] ?? name[1] ?? '';
+            if (local !== 'type' && local !== 'as')
+                names.add(local);
+        }
+    }
+    return names;
+}
+/**
+ * Whether inline code reads as a sentence: three plain names in a row, separated by spaces only,
+ * outside strings and comments.
+ * @param text - The inline code.
+ * @param masked - The marks of its strings and comments.
+ */
+function isProse(text, masked) {
+    for (const match of text.matchAll(/[\p{L}_$][\p{L}\w$]*(?: [\p{L}_$][\p{L}\w$]*){2,}/gu)) {
+        const words = match[0].split(' ');
+        const plain = words.filter((word) => !SYNTAX_WORDS.has(word) && !RESERVED_WORDS.has(word));
+        if (!masked[match.index] && plain.length >= 3) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The index of the last character before `index` that is neither whitespace nor in a comment, or
+ * -1.
+ * @param text - The code.
+ * @param index - The index to look back from.
+ * @param masked - The marks of its strings and comments.
+ */
+function previousSignificant(text, index, masked) {
+    let position = index - 1;
+    while (position >= 0 && insignificant(text, position, masked))
+        position--;
+    return position;
+}
+/**
+ * The index of the first character at or after `index` that is neither whitespace nor in a
+ * comment.
+ * @param text - The code.
+ * @param index - The index to look from.
+ * @param masked - The marks of its strings and comments.
+ */
+function nextSignificant(text, index, masked) {
+    let position = index;
+    while (position < text.length && insignificant(text, position, masked))
+        position++;
+    return position;
+}
+/**
+ * Whether the character at `index` is whitespace or part of a comment.
+ * @param text - The code.
+ * @param index - The index of the character.
+ * @param masked - The marks of its strings and comments.
+ */
+function insignificant(text, index, masked) {
+    return masked[index] === COMMENT || /\s/.test(text[index] ?? '');
+}
+/**
+ * The word that ends at `index` (inclusive), or an empty string.
+ * @param text - The code.
+ * @param index - The index of the word's last character.
+ */
+function previousWord(text, index) {
+    let start = index;
+    while (start >= 0 && WORD_CHARACTER.test(text[start] ?? ''))
+        start--;
+    return text.slice(start + 1, index + 1);
+}
+
 const ALWAYS_ALLOWED_LANGUAGES = ['typescript', 'ts', 'angular-ts'];
-const LANGUAGES = ['typescript', 'ts', 'angular-ts', ...KEYWORD_ALLOWED_LANGUAGES];
+const HTML_LANGUAGES = [...KEYWORD_ALLOWED_LANGUAGES];
+const LANGUAGES = [...ALWAYS_ALLOWED_LANGUAGES, ...HTML_LANGUAGES];
 const SPLIT_REGEXP = /([*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?)/u;
 const MATCH_KEYWORD_REGEXP = /(?<key>[*\p{L}\w$@-]+)((?<delimiter>[.#])(?<anchor>[\p{L}\w-]+))?(?<queryParams>\?[\w=&]+)?/u;
 /**
@@ -107,24 +574,48 @@ function keywordsPlugin(config) {
         const lang = asArray(node.properties?.['className'] ?? [])
             .find((className) => className.startsWith('language-'))
             ?.replace('language-', '') ?? '';
-        if (isInlineCode || LANGUAGES.includes(lang)) {
-            visitParents(node, 'text', (node, ancestors) => {
-                if (hasLinkAncestor(ancestors)) {
-                    return;
-                }
-                const parent = ancestors[ancestors.length - 1];
-                const index = parent.children.indexOf(node);
-                // Parse the text for words that we can convert to links
-                const nodes = getNodes(node, parent, isInlineCode, config, lang);
-                // Replace the text node with the links and leftover text nodes
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-ignore
-                Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
-                // Do not visit this node's children or the newly added nodes
-                return [SKIP, index + nodes.length];
-            });
+        if (!isInlineCode && !LANGUAGES.includes(lang)) {
+            return;
         }
+        const offsets = textOffsets(node);
+        const text = Array.from(offsets.keys())
+            .map((textNode) => textNode.value)
+            .join('');
+        const scan = isInlineCode
+            ? scanInlineCode(text)
+            : scanCodeBlock(text, HTML_LANGUAGES.includes(lang) ? 'html' : 'typescript');
+        if (!scan) {
+            return;
+        }
+        visitParents(node, 'text', (node, ancestors) => {
+            if (hasLinkAncestor(ancestors)) {
+                return;
+            }
+            const parent = ancestors[ancestors.length - 1];
+            const index = parent.children.indexOf(node);
+            // Parse the text for words that we can convert to links
+            const nodes = getNodes(node, parent, isInlineCode, config, lang, scan, offsets.get(node) ?? 0);
+            // Replace the text node with the links and leftover text nodes
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
+            // Do not visit this node's children or the newly added nodes
+            return [SKIP, index + nodes.length];
+        });
+    });
+}
+/**
+ * The offset of every text node of a code element in the element's text, in document order.
+ * @param node - The code element.
+ */
+function textOffsets(node) {
+    const offsets = new Map();
+    let offset = 0;
+    visitParents(node, 'text', (text) => {
+        offsets.set(text, offset);
+        offset += text.value.length;
     });
+    return offsets;
 }
 /**
  *
@@ -133,19 +624,31 @@ function keywordsPlugin(config) {
  * @param isInlineCode
  * @param config
  * @param language
+ * @param scan - The positions of the code element's words.
+ * @param offset - The offset of the text node in the code element's text.
  */
-function getNodes(node, parent, isInlineCode, config, language) {
+function getNodes(node, parent, isInlineCode, config, language, scan, offset) {
     const { addUsedKeyword, getKeyword } = config;
+    let start = offset;
     return toString(node)
         .split(SPLIT_REGEXP)
         .map((word) => {
+        const wordStart = start;
+        start += word.length;
         const match = word.match(MATCH_KEYWORD_REGEXP);
         if (!match) {
             return { type: 'text', value: word };
         }
         const { key = '', delimiter = '', anchor = '', queryParams = '', } = match.groups;
-        const usedKeyword = `${key}${delimiter}${anchor?.toLowerCase()}`;
-        const rootKeyword = getKeyword?.(key);
+        const position = scan.position(wordStart, wordStart + word.length, key);
+        // Not a reference to a keyword: an object key, a string, a file name and the like
+        if (!position.link) {
+            return { type: 'text', value: word };
+        }
+        // A member after a dot is looked up as a whole `Owner.member`
+        const isMember = position.keyword !== undefined;
+        const usedKeyword = position.keyword ?? `${key}${delimiter}${anchor?.toLowerCase()}`;
+        const rootKeyword = isMember ? undefined : getKeyword?.(key);
         const keyword = getKeyword?.(usedKeyword);
         const isGuideKeyword = key.startsWith('*');
         const isLanguageAllowed = (!keyword?.languages && ALWAYS_ALLOWED_LANGUAGES.includes(language)) ||
@@ -161,7 +664,9 @@ function getNodes(node, parent, isInlineCode, config, language) {
         addUsedKeyword?.(usedKeyword);
         const notFoundGuideKeyword = isGuideKeyword && !keyword;
         const notFoundApiAnchorKeyword = !!rootKeyword && !!anchor && !keyword;
-        if (getKeyword && isInlineCode && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
+        // Only inline code that is one keyword reference as a whole fails on a missing one: in code,
+        // `*` and `.` are operators, not keyword syntax.
+        if (getKeyword && scan.whole && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
             throw new Error(`Route with keyword "${word}" is missing.`);
         }
         // Convert code tag to a link tag or highlight it with a class
@@ -180,7 +685,7 @@ function getNodes(node, parent, isInlineCode, config, language) {
         }
         // Add link inside the code if it's a link to the API entity
         return keyword
-            ? createLinkNode(isInlineCode ? keyword.title : word, keyword.path, keyword.type, keyword.description)
+            ? createLinkNode(isInlineCode && !isMember ? keyword.title : word, keyword.path, keyword.type, keyword.description)
             : { type: 'text', value: word };
     });
 }
@@ -259,6 +764,160 @@ function addHeadingAnchors(route) {
     });
 }
 
+const languagePrefix$1 = 'language-';
+/**
+ * One `@shikijs/rehype` transformer per theme pair and languages in this thread. It loads its
+ * highlighter once (every bundled language, the extra ones, the themes and the WASM), where the plain plugin, created again for
+ * every document, asks for the highlighter and loads every language and theme into it again on
+ * each call. A transformer whose highlighter failed to load is forgotten, so the next document
+ * tries again and fails with the same error, as the plain plugin does.
+ */
+const highlighters = new Map();
+/**
+ * The plain `@shikijs/rehype` plugin, with a cache of its results per block.
+ *
+ * It selects the blocks exactly as the plugin does (`pre` elements whose first child is a `code`
+ * element with properties, with the language of its `language-*` class or the default language)
+ * and leaves the tree unchanged while it keys them. A miss is highlighted by the plugin's own
+ * transformer, on a tree that holds only that block, so it gets exactly the plugin's options,
+ * language fallback, meta parsing and transformers. A failing block throws the plugin's error at
+ * the same block, since a hit cannot fail (the cache holds only blocks that were highlighted), and
+ * nothing is stored for it. Every value is serialized before the tree is changed, and every block
+ * is replaced with nodes parsed from it, so later plugins, which change the tree, never change a
+ * value or a node another block shares. A document whose blocks all hit (or that has none) never
+ * loads Shiki once the cache shows that its themes load.
+ */
+function cachedShikiPlugin(settings) {
+    const { cache, themes, languages, identity, defaultLanguage } = settings;
+    const id = `${themes.light}\n${themes.dark}\n${languages ?? ''}\n${settings.grammars ?? 'all'}`;
+    return async (tree) => {
+        const blocks = [];
+        visit(tree, 'element', (node, index, parent) => {
+            if (!parent || index == null || node.tagName !== 'pre')
+                return;
+            const head = node.children[0];
+            if (!head || head.type !== 'element' || head.tagName !== 'code' || !head.properties)
+                return;
+            const classes = head.properties['className'];
+            const languageClass = Array.isArray(classes)
+                ? classes.find((item) => typeof item === 'string' && item.startsWith(languagePrefix$1))
+                : undefined;
+            const lang = typeof languageClass === 'string'
+                ? languageClass.slice(languagePrefix$1.length)
+                : defaultLanguage;
+            if (!lang)
+                return;
+            const data = head.data;
+            const meta = data?.meta ?? head.properties['metastring']?.toString() ?? '';
+            const code = toString(head);
+            blocks.push({
+                node,
+                parent,
+                key: cache.key({
+                    options: identity,
+                    themes,
+                    ...(languages === undefined ? {} : { languages }),
+                    lang,
+                    meta,
+                    code,
+                }),
+            });
+        });
+        let highlighter;
+        const load = async () => (highlighter ??= await highlighterFor(id, settings.transformer));
+        if (cache.loads?.(themes) !== true)
+            await load();
+        const values = [];
+        for (const block of blocks) {
+            const cached = cache.get(block.key);
+            const hit = cached === undefined ? undefined : fragment(cached);
+            if (hit && !cache.verify) {
+                values.push(hit);
+                continue;
+            }
+            const fresh = await highlight(await load(), block.node);
+            if (hit && fresh !== cached)
+                cache.mismatch?.(block.key);
+            if (fresh !== cached)
+                cache.set(block.key, fresh);
+            values.push(JSON.parse(fresh));
+        }
+        blocks.forEach((block, position) => {
+            const index = block.parent.children.indexOf(block.node);
+            // A block nested in another block's `pre` was replaced inside that detached element.
+            if (index >= 0)
+                block.parent.children.splice(index, 1, ...values[position]);
+        });
+    };
+}
+function highlighterFor(id, transformer) {
+    const known = highlighters.get(id);
+    if (known)
+        return known;
+    const created = (async () => {
+        const transform = transformer();
+        // An empty tree makes the transformer load its highlighter, so that a failure to load is told
+        // apart from a block's own failure.
+        await transform({ type: 'root', children: [] });
+        return transform;
+    })();
+    highlighters.set(id, created);
+    created.catch(() => {
+        if (highlighters.get(id) === created)
+            highlighters.delete(id);
+    });
+    return created;
+}
+/** The JSON of the nodes the plugin replaces `node` with. */
+async function highlight(transform, node) {
+    const root = { type: 'root', children: [node] };
+    await transform(root);
+    return JSON.stringify(root.children);
+}
+/**
+ * A cached value as fresh nodes, or undefined when it is not a JSON array of HAST elements or of
+ * roots of elements (what `@shikijs/rehype` puts in place of a block).
+ */
+function fragment(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) && parsed.length > 0 && parsed.every(isReplacement)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isReplacement(value) {
+    if (isNode(value))
+        return value.type === 'element';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const node = value;
+    const children = node['children'];
+    return (node['type'] === 'root' &&
+        Array.isArray(children) &&
+        children.length > 0 &&
+        children.every((child) => isNode(child) && child.type === 'element'));
+}
+function isNode(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const node = value;
+    if (node['type'] === 'text')
+        return typeof node['value'] === 'string';
+    const properties = node['properties'];
+    const children = node['children'];
+    return (node['type'] === 'element' &&
+        typeof node['tagName'] === 'string' &&
+        !!properties &&
+        typeof properties === 'object' &&
+        !Array.isArray(properties) &&
+        Array.isArray(children) &&
+        children.every(isNode));
+}
+
 /**
  * Highlight code lines
  */
@@ -349,6 +1008,9 @@ function sluggerPlugin(addAnchor, headings = ['h1', 'h2', 'h3', 'h4']) {
                 if (node.properties) {
                     const id = attrSlug && attrSlugType === 'member' ? attrSlug : slugger.slug(dataToSlug);
                     node.properties['id'] = id;
+                    if (isHeading) {
+                        hideLeadingEmoji(node);
+                    }
                     addAnchor({
                         anchorId: id,
                         anchor: new GithubSlugger().slug(dataToSlug),
@@ -363,6 +1025,31 @@ function sluggerPlugin(addAnchor, headings = ['h1', 'h2', 'h3', 'h4']) {
         });
     };
 }
+/**
+ * A leading emoji of a heading: one pictograph with its modifiers and joined parts, or a flag.
+ * `libs/builder/helpers/keyword-heading-title.ts` strips the same emoji from keyword titles; keep
+ * both patterns in step.
+ */
+const LEADING_EMOJI = /^(?:\p{Regional_Indicator}{2}|(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)(?:\p{Emoji_Modifier}|\uFE0F|\u200D\p{Extended_Pictographic}\uFE0F?)*)(?=\s)/u;
+/**
+ * Wraps a decorative leading emoji of a heading in an `aria-hidden` span, so screen readers skip
+ * it. It runs after the heading's id and anchor are taken from the text, so neither changes.
+ * @param heading - The heading element.
+ */
+function hideLeadingEmoji(heading) {
+    const first = heading.children[0];
+    const emoji = first?.type === 'text' ? LEADING_EMOJI.exec(first.value)?.[0] : undefined;
+    if (!emoji) {
+        return;
+    }
+    const rest = { type: 'text', value: first.value.slice(emoji.length) };
+    heading.children.splice(0, 1, {
+        type: 'element',
+        tagName: 'span',
+        properties: { ariaHidden: 'true' },
+        children: [{ type: 'text', value: emoji }],
+    }, rest);
+}
 /**
  *
  * @param ancestors
@@ -401,6 +1088,185 @@ function wrapTablePlugin () {
     };
 }
 
+/**
+ * Loading only the Shiki grammars that code blocks use, with the same result as loading every
+ * bundled grammar.
+ *
+ * `@shikijs/rehype` sets its highlighter up with every bundled grammar, which takes seconds. A
+ * grammar's highlighting depends only on the grammars it can reach: the languages it embeds
+ * (`embeddedLangs`, and `embeddedLangsLazy`, which it uses once they are loaded), the scopes its
+ * rules include, and the grammars that inject into its scopes (`injectTo`, matched by scope
+ * prefix, in registration order). {@link ShikiGrammars.closure} is that set, closed under the
+ * same rules, plus every grammar that shares an injection target with an injector in it, so the
+ * injections of a scope are always registered together. Loaded in the order in which loading every
+ * bundled grammar registers them (the first mention of each name), a closure gives the
+ * highlighter the same grammars, injections and injection order for its languages as loading
+ * everything, whatever else was loaded before: a highlighter only grows by whole closures, and
+ * each scope's grammars are complete when the scope is first loaded.
+ */
+class ShikiGrammars {
+    constructor(registrations) {
+        this.byName = new Map();
+        this.byScope = new Map();
+        this.injectors = new Map();
+        this.order = new Map();
+        this.closures = new Map();
+        this.loaded = new WeakMap();
+        const mention = (name) => {
+            if (!this.order.has(name))
+                this.order.set(name, this.order.size);
+        };
+        for (const registration of registrations) {
+            mention(registration.name);
+            for (const embedded of registration.embeddedLangs ?? [])
+                mention(embedded);
+            if (this.byScope.has(registration.scopeName))
+                continue;
+            this.byScope.set(registration.scopeName, registration);
+            this.byName.set(registration.name, registration);
+            for (const alias of registration.aliases ?? [])
+                this.byName.set(alias, registration);
+            for (const target of registration.injectTo ?? []) {
+                const list = this.injectors.get(target) ?? [];
+                list.push(registration);
+                this.injectors.set(target, list);
+            }
+        }
+    }
+    /**
+     * The bundled grammars, in the order `@shikijs/rehype` registers them: every bundled language
+     * name, each with the registrations of its module.
+     */
+    static async create() {
+        const modules = await Promise.all(Object.keys(bundledLanguages).map((name) => bundledLanguages[name]()));
+        return new ShikiGrammars(modules.flatMap((module) => module.default));
+    }
+    /**
+     * The grammars that a block of `language` can reach, in registration order; empty for a
+     * language that no bundled grammar names (it falls back to plain text, as before).
+     * @param language
+     */
+    closure(language) {
+        const known = this.closures.get(language);
+        if (known)
+            return known;
+        const set = new Set();
+        const queue = [this.byName.get(language)];
+        while (queue.length) {
+            const registration = queue.pop();
+            if (!registration || set.has(registration))
+                continue;
+            set.add(registration);
+            for (const name of [
+                ...(registration.embeddedLangs ?? []),
+                ...(registration.embeddedLangsLazy ?? []),
+            ])
+                queue.push(this.byName.get(name));
+            for (const scope of includedScopes(registration))
+                queue.push(this.byScope.get(scope));
+            for (const prefix of prefixes(registration.scopeName))
+                queue.push(...(this.injectors.get(prefix) ?? []));
+            for (const target of registration.injectTo ?? [])
+                queue.push(...(this.injectors.get(target) ?? []));
+        }
+        const closure = [...set].sort((left, right) => this.order.get(left.name) - this.order.get(right.name));
+        this.closures.set(language, closure);
+        return closure;
+    }
+    /**
+     * Loads the closures of `languages` that `highlighter` does not hold yet.
+     * @param highlighter
+     * @param languages
+     */
+    load(highlighter, languages) {
+        let loaded = this.loaded.get(highlighter);
+        if (!loaded)
+            this.loaded.set(highlighter, (loaded = new Set()));
+        const missing = new Set();
+        for (const language of languages)
+            for (const registration of this.closure(language))
+                if (!loaded.has(registration.name))
+                    missing.add(registration);
+        if (!missing.size)
+            return;
+        const batch = [...missing].sort((left, right) => this.order.get(left.name) - this.order.get(right.name));
+        highlighter.loadLanguageSync(batch);
+        for (const registration of batch)
+            loaded.add(registration.name);
+    }
+}
+let grammars;
+/** The bundled grammars of this thread, read once. */
+function shikiGrammars() {
+    grammars ??= ShikiGrammars.create().catch((error) => {
+        grammars = undefined;
+        throw error;
+    });
+    return grammars;
+}
+/**
+ * A highlighter with the given themes and no language: {@link ShikiGrammars.load} adds them.
+ * @param themes
+ */
+function createGrammarlessHighlighter(themes) {
+    return createHighlighter({ themes, langs: [] });
+}
+const languagePrefix = 'language-';
+/**
+ * The language of every block `@shikijs/rehype` highlights in `tree` (a `pre` whose first child is
+ * a `code` element with properties): its `language-*` class, or `defaultLanguage`.
+ * @param tree
+ * @param defaultLanguage
+ */
+function blockLanguages(tree, defaultLanguage) {
+    const languages = new Set();
+    visit(tree, 'element', (node) => {
+        if (node.tagName !== 'pre')
+            return;
+        const head = node.children[0];
+        if (!head || head.type !== 'element' || head.tagName !== 'code' || !head.properties)
+            return;
+        const classes = head.properties['className'];
+        const languageClass = Array.isArray(classes)
+            ? classes.find((item) => typeof item === 'string' && item.startsWith(languagePrefix))
+            : undefined;
+        languages.add(typeof languageClass === 'string'
+            ? languageClass.slice(languagePrefix.length)
+            : defaultLanguage);
+    });
+    return languages;
+}
+/**
+ * The scopes that a grammar's rules include from other grammars (`include: "source.x#rule"`).
+ * @param registration
+ */
+function includedScopes(registration) {
+    const scopes = new Set();
+    const walk = (value) => {
+        if (Array.isArray(value))
+            value.forEach(walk);
+        else if (value && typeof value === 'object')
+            for (const [key, item] of Object.entries(value)) {
+                if (key === 'include' && typeof item === 'string') {
+                    if (!item.startsWith('#') && !item.startsWith('$'))
+                        scopes.add(item.split('#')[0]);
+                }
+                else
+                    walk(item);
+            }
+    };
+    walk(registration);
+    return scopes;
+}
+/**
+ * `a`, `a.b` and `a.b.c` for `a.b.c`: the scopes an injection target matches.
+ * @param scope
+ */
+function prefixes(scope) {
+    const parts = scope.split('.');
+    return parts.map((_, index) => parts.slice(0, index + 1).join('.'));
+}
+
 /**
  *
  * @param html
@@ -408,6 +1274,12 @@ function wrapTablePlugin () {
  */
 async function processHtml(html, config) {
     const anchors = new Set();
+    const themes = {
+        light: config.lightTheme ?? 'github-light',
+        dark: config.darkTheme ?? 'ayu-dark',
+    };
+    const langs = config.langs?.length ? config.langs : undefined;
+    const used = !langs && config.grammars === 'used';
     try {
         const content = await unified()
             .use(rehypeParse, { fragment: true })
@@ -415,16 +1287,30 @@ async function processHtml(html, config) {
             .use(mermaidPlugin)
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             // @ts-ignore
-            .use(rehypeShiki, {
-            defaultLanguage: 'ts',
-            fallbackLanguage: 'text',
-            addLanguageClass: true,
-            parseMetaString: (meta) => JSON.parse(meta?.replace(/\\/g, '') || '{}'),
-            themes: {
-                light: config.lightTheme ?? 'github-light',
-                dark: config.darkTheme ?? 'ayu-dark',
-            },
-        })
+            .use(config.highlight
+            ? [
+                [
+                    cachedShikiPlugin,
+                    {
+                        cache: config.highlight,
+                        themes,
+                        ...(langs ? { languages: languagesId(langs) } : {}),
+                        ...(used ? { grammars: 'used' } : {}),
+                        identity: HIGHLIGHT_IDENTITY,
+                        defaultLanguage: DEFAULT_LANGUAGE,
+                        transformer: () => langs
+                            ? withLanguages(themes, langs)
+                            : used
+                                ? withUsedGrammars(themes)
+                                : rehypeShiki(shikiOptions(themes)),
+                    },
+                ],
+            ]
+            : langs
+                ? [[() => withLanguages(themes, langs)]]
+                : used
+                    ? [[() => withUsedGrammars(themes)]]
+                    : [[rehypeShiki, shikiOptions(themes)]])
             .use(highlightCodeLines)
             .use(wrapTablePlugin)
             .use(sluggerPlugin, anchors.add.bind(anchors), config.headings)
@@ -439,6 +1325,135 @@ async function processHtml(html, config) {
         return { content: html, anchors: [], error };
     }
 }
+const DEFAULT_LANGUAGE = 'ts';
+/**
+ * What a cached block's options stand for in its key ({@link NgDocHighlightCache}). Bump `format`
+ * whenever {@link shikiOptions} or the cached plugin change.
+ */
+const HIGHLIGHT_IDENTITY = {
+    format: 2,
+    defaultLanguage: DEFAULT_LANGUAGE,
+    fallbackLanguage: 'text',
+    addLanguageClass: true,
+    parseMetaString: 'json-without-backslashes',
+    tokenizeTimeLimit: 0,
+};
+/**
+ * The options both highlighting paths give `@shikijs/rehype`.
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ */
+function shikiOptions(themes) {
+    return {
+        defaultLanguage: DEFAULT_LANGUAGE,
+        fallbackLanguage: 'text',
+        addLanguageClass: true,
+        parseMetaString: (meta) => JSON.parse(meta?.replace(/\\/g, '') || '{}'),
+        // Shiki stops tokenizing a line after 500 ms by default and silently colours the rest of
+        // it like the last token. A slow or pre-empted process then renders other HTML than a fast
+        // one, so the build output would depend on machine load. No limit keeps it deterministic.
+        tokenizeTimeLimit: 0,
+        themes: {
+            light: shikiTheme(themes.light),
+            dark: shikiTheme(themes.dark),
+        },
+    };
+}
+/**
+ * A Shiki theme by name. NgDoc's own theme is not bundled with Shiki, so its name resolves to a new
+ * copy of it; any other name is left to Shiki.
+ * @param name - The theme name.
+ */
+function shikiTheme(name) {
+    return name === NG_DOC_SYNTAX_THEME_NAME ? ngDocSyntaxTheme() : name;
+}
+/**
+ * The highlighters with extra languages in this thread, by themes and languages. Each loads every
+ * bundled language and the given ones once; nothing loads into it later, so a block highlights
+ * the same whatever was highlighted before, and documents with other languages (or none) never
+ * see these.
+ */
+const languageHighlighters = new Map();
+const languageIds = new WeakMap();
+/**
+ * The identity of a list of languages: the digest of its JSON.
+ * @param langs
+ */
+function languagesId(langs) {
+    let id = languageIds.get(langs);
+    if (id === undefined) {
+        id = createHash('sha256').update(JSON.stringify(langs)).digest('hex');
+        languageIds.set(langs, id);
+    }
+    return id;
+}
+/**
+ * The `@shikijs/rehype` transformer over the highlighter with these languages, with the options of
+ * the plain plugin. A highlighter that failed to load is forgotten, so that the next document tries
+ * again and fails with the same error.
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ * @param langs - The extra languages.
+ */
+function withLanguages(themes, langs) {
+    const id = `${themes.light}\n${themes.dark}\n${languagesId(langs)}`;
+    return async (tree) => {
+        let highlighter = languageHighlighters.get(id);
+        if (!highlighter) {
+            highlighter = createHighlighter({
+                themes: [shikiTheme(themes.light), shikiTheme(themes.dark)],
+                // Later registrations of a name replace earlier ones, so the given languages win.
+                langs: [...Object.keys(bundledLanguages), ...langs],
+            });
+            languageHighlighters.set(id, highlighter);
+            const created = highlighter;
+            created.catch(() => {
+                if (languageHighlighters.get(id) === created)
+                    languageHighlighters.delete(id);
+            });
+        }
+        const transform = rehypeShikiFromHighlighter(await highlighter, shikiOptions(themes));
+        await transform(tree);
+    };
+}
+/**
+ * The highlighters that load only the grammars code blocks use, by theme pair, in this thread. A
+ * highlighter that failed to load is forgotten, so that the next document tries again and fails
+ * with the same error.
+ */
+const usedHighlighters = new Map();
+/**
+ * The `@shikijs/rehype` transformer, with the options of the plain plugin, over this thread's
+ * highlighter for the theme pair, after it has loaded the grammars of the tree's code blocks
+ * (`./shiki-grammars`).
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ */
+function withUsedGrammars(themes) {
+    const id = `${themes.light}\n${themes.dark}`;
+    return async (tree) => {
+        let highlighter = usedHighlighters.get(id);
+        if (!highlighter) {
+            highlighter = createGrammarlessHighlighter([
+                shikiTheme(themes.light),
+                shikiTheme(themes.dark),
+            ]);
+            usedHighlighters.set(id, highlighter);
+            const created = highlighter;
+            created.catch(() => {
+                if (usedHighlighters.get(id) === created)
+                    usedHighlighters.delete(id);
+            });
+        }
+        const [grammars, ready] = await Promise.all([shikiGrammars(), highlighter]);
+        grammars.load(ready, blockLanguages(tree, DEFAULT_LANGUAGE));
+        const transform = rehypeShikiFromHighlighter(ready, shikiOptions(themes));
+        await transform(tree);
+    };
+}
 
 /**
  *
@@ -447,6 +1462,14 @@ async function processHtml(html, config) {
  */
 function removeNotIndexableContentPlugin() {
     return (tree) => {
+        // The slugger wraps a heading's decorative leading emoji in an `aria-hidden` span. It is not
+        // part of the heading's name: indexed, it became a search record of its own, under the
+        // previous section.
+        visit(tree, 'element', (node) => {
+            if (isHeading(node) && isHiddenSpan(node.children[0])) {
+                node.children = node.children.slice(1);
+            }
+        });
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         // @ts-ignore
         return filter(tree, { cascade: true }, (node) => {
@@ -458,6 +1481,16 @@ function removeNotIndexableContentPlugin() {
         });
     };
 }
+/**
+ * Whether the node is a span hidden from assistive technology, as the slugger renders the leading
+ * emoji of a heading.
+ * @param node - The first child of a heading.
+ */
+function isHiddenSpan(node) {
+    return (node?.type === 'element' &&
+        node.tagName === 'span' &&
+        node.properties?.['ariaHidden'] === 'true');
+}
 
 /**
  *