@ng-doc/builder 22.0.0 → 22.1.0

package/generator/compiler/index.js

@@ -886,6 +886,329 @@ var init_helpers2 = __esm({
   }
 });
 
+// libs/utils/html/plugins/keyword-positions.ts
+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 void 0;
+  }
+  const scan = scanTypeScript(text);
+  return isProse(text, scan.masked) ? void 0 : scan;
+}
+function scanCodeBlock(text, mode) {
+  return mode === "html" ? scanHtml(text) : scanTypeScript(text);
+}
+function scanTypeScript(text) {
+  const masked = maskTypeScript(text);
+  const locals = localBindings(text, masked);
+  return {
+    whole: false,
+    masked,
+    position(start, end, key) {
+      if (masked[start] === TEMPLATE) {
+        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] !== ".") {
+        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;
+    }
+  };
+}
+function isDeclaredName(text, masked, previous, next) {
+  const after = text[next];
+  const afterNext = text[nextSignificant(text, next + 1, masked)];
+  if (after === ":" && text[next + 1] !== ":") {
+    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] !== ">") {
+    return !TYPE_CONTEXT.includes(text[previous] ?? "") && !TYPE_WORDS.includes(previousWord(text, previous));
+  }
+  return false;
+}
+function scanHtml(text) {
+  const masked = maskHtml(text);
+  return {
+    whole: false,
+    position: (start) => masked[start] === CODE ? REFERENCE : NOT_A_REFERENCE
+  };
+}
+function maskTypeScript(text) {
+  const masked = new Uint8Array(text.length);
+  const templates = [];
+  let depth = 0;
+  let index = 0;
+  const string2 = (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 === '"') {
+      string2(character);
+    } else if (character === "`") {
+      template();
+    } else if (character === "{") {
+      depth++;
+      index++;
+    } else if (character === "}") {
+      if (templates.length && templates[templates.length - 1] === depth) {
+        templates.pop();
+        template();
+      } else {
+        depth--;
+        index++;
+      }
+    } else {
+      index++;
+    }
+  }
+  return masked;
+}
+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;
+}
+function maskTag(text, index, masked) {
+  while (index < text.length && text[index] !== ">") {
+    if (text[index] !== "=") {
+      index++;
+      continue;
+    }
+    index++;
+    while (text[index] === " " || text[index] === "	" || 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;
+}
+function localBindings(text, masked) {
+  const names = /* @__PURE__ */ 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;
+}
+function isProse(text, masked) {
+  for (const match of text.matchAll(/[\p{L}_$][\p{L}\w$]*(?: [\p{L}_$][\p{L}\w$]*){2,}/gu)) {
+    const words2 = match[0].split(" ");
+    const plain = words2.filter((word) => !SYNTAX_WORDS.has(word) && !RESERVED_WORDS.has(word));
+    if (!masked[match.index] && plain.length >= 3) {
+      return true;
+    }
+  }
+  return false;
+}
+function previousSignificant(text, index, masked) {
+  let position = index - 1;
+  while (position >= 0 && insignificant(text, position, masked)) position--;
+  return position;
+}
+function nextSignificant(text, index, masked) {
+  let position = index;
+  while (position < text.length && insignificant(text, position, masked)) position++;
+  return position;
+}
+function insignificant(text, index, masked) {
+  return masked[index] === COMMENT || /\s/.test(text[index] ?? "");
+}
+function previousWord(text, index) {
+  let start = index;
+  while (start >= 0 && WORD_CHARACTER.test(text[start] ?? "")) start--;
+  return text.slice(start + 1, index + 1);
+}
+var WORD_CHARACTER, IDENTIFIER_BEFORE, WHOLE_KEYWORD, CODE_PUNCTUATION, DECLARATION_START, HTML_START, SYNTAX_WORDS, RESERVED_WORDS, TYPE_CONTEXT, TYPE_WORDS, CODE, STRING, COMMENT, TEMPLATE, CONTROL_FLOW, NOT_A_REFERENCE, REFERENCE;
+var init_keyword_positions = __esm({
+  "libs/utils/html/plugins/keyword-positions.ts"() {
+    "use strict";
+    WORD_CHARACTER = /[*\p{L}\w$@-]/u;
+    IDENTIFIER_BEFORE = /[\p{L}\w$@-]+$/u;
+    WHOLE_KEYWORD = /^\s*[*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?\s*$/u;
+    CODE_PUNCTUATION = /[(){}[\]<>|:=@]/;
+    DECLARATION_START = /^\s*(?:export|import|class|interface|type|const|let|var|function|enum|abstract|declare)\s/;
+    HTML_START = /^\s*<\/?[A-Za-z]/;
+    SYNTAX_WORDS = /* @__PURE__ */ 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"
+    ]);
+    RESERVED_WORDS = /* @__PURE__ */ 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"
+    ]);
+    TYPE_CONTEXT = [":", "|", "&", "<"];
+    TYPE_WORDS = ["type", "extends", "keyof", "typeof"];
+    CODE = 0;
+    STRING = 1;
+    COMMENT = 2;
+    TEMPLATE = 3;
+    CONTROL_FLOW = /^@[a-z]+$/;
+    NOT_A_REFERENCE = Object.freeze({ link: false });
+    REFERENCE = Object.freeze({ link: true });
+  }
+});
+
 // libs/utils/html/plugins/keywords.plugin.ts
 import { isElement as isElement5 } from "hast-util-is-element";
 import { toString } from "hast-util-to-string";
@@ -897,23 +1220,50 @@ function keywordsPlugin(config) {
     }
     const isInlineCode = !isElement5(ancestors[ancestors.length - 1], "pre");
     const lang = asArray(node.properties?.["className"] ?? []).find((className) => className.startsWith("language-"))?.replace("language-", "") ?? "";
-    if (isInlineCode || LANGUAGES.includes(lang)) {
-      visitParents(node, "text", (node2, ancestors2) => {
-        if (hasLinkAncestor(ancestors2)) {
-          return;
-        }
-        const parent = ancestors2[ancestors2.length - 1];
-        const index = parent.children.indexOf(node2);
-        const nodes = getNodes(node2, parent, isInlineCode, config, lang);
-        Array.prototype.splice.apply(parent.children, [index, 1].concat(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", (node2, ancestors2) => {
+      if (hasLinkAncestor(ancestors2)) {
+        return;
+      }
+      const parent = ancestors2[ancestors2.length - 1];
+      const index = parent.children.indexOf(node2);
+      const nodes = getNodes(
+        node2,
+        parent,
+        isInlineCode,
+        config,
+        lang,
+        scan,
+        offsets.get(node2) ?? 0
+      );
+      Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
+      return [SKIP, index + nodes.length];
+    });
+  });
+}
+function textOffsets(node) {
+  const offsets = /* @__PURE__ */ new Map();
+  let offset = 0;
+  visitParents(node, "text", (text) => {
+    offsets.set(text, offset);
+    offset += text.value.length;
   });
+  return offsets;
 }
-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 };
@@ -924,8 +1274,13 @@ function getNodes(node, parent, isInlineCode, config, language) {
       anchor = "",
       queryParams = ""
     } = match.groups;
-    const usedKeyword = `${key}${delimiter}${anchor?.toLowerCase()}`;
-    const rootKeyword2 = getKeyword?.(key);
+    const position = scan.position(wordStart, wordStart + word.length, key);
+    if (!position.link) {
+      return { type: "text", value: word };
+    }
+    const isMember = position.keyword !== void 0;
+    const usedKeyword = position.keyword ?? `${key}${delimiter}${anchor?.toLowerCase()}`;
+    const rootKeyword2 = isMember ? void 0 : getKeyword?.(key);
     const keyword = getKeyword?.(usedKeyword);
     const isGuideKeyword = key.startsWith("*");
     const isLanguageAllowed = !keyword?.languages && ALWAYS_ALLOWED_LANGUAGES.includes(language) || !!keyword?.languages?.includes(language);
@@ -938,7 +1293,7 @@ function getNodes(node, parent, isInlineCode, config, language) {
     addUsedKeyword?.(usedKeyword);
     const notFoundGuideKeyword = isGuideKeyword && !keyword;
     const notFoundApiAnchorKeyword = !!rootKeyword2 && !!anchor && !keyword;
-    if (getKeyword && isInlineCode && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
+    if (getKeyword && scan.whole && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
       throw new Error(`Route with keyword "${word}" is missing.`);
     }
     if (parent.properties) {
@@ -954,7 +1309,7 @@ function getNodes(node, parent, isInlineCode, config, language) {
       }
     }
     return keyword ? createLinkNode(
-      isInlineCode ? keyword.title : word,
+      isInlineCode && !isMember ? keyword.title : word,
       keyword.path,
       keyword.type,
       keyword.description
@@ -974,14 +1329,16 @@ function createLinkNode(text, href, type, description) {
     children: [{ type: "text", value: text }]
   };
 }
-var ALWAYS_ALLOWED_LANGUAGES, LANGUAGES, SPLIT_REGEXP, MATCH_KEYWORD_REGEXP;
+var ALWAYS_ALLOWED_LANGUAGES, HTML_LANGUAGES, LANGUAGES, SPLIT_REGEXP, MATCH_KEYWORD_REGEXP;
 var init_keywords_plugin = __esm({
   "libs/utils/html/plugins/keywords.plugin.ts"() {
     "use strict";
     init_core();
     init_helpers2();
+    init_keyword_positions();
     ALWAYS_ALLOWED_LANGUAGES = ["typescript", "ts", "angular-ts"];
-    LANGUAGES = ["typescript", "ts", "angular-ts", ...KEYWORD_ALLOWED_LANGUAGES];
+    HTML_LANGUAGES = [...KEYWORD_ALLOWED_LANGUAGES];
+    LANGUAGES = [...ALWAYS_ALLOWED_LANGUAGES, ...HTML_LANGUAGES];
     SPLIT_REGEXP = /([*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?)/u;
     MATCH_KEYWORD_REGEXP = /(?<key>[*\p{L}\w$@-]+)((?<delimiter>[.#])(?<anchor>[\p{L}\w-]+))?(?<queryParams>\?[\w=&]+)?/u;
   }
@@ -1039,13 +1396,14 @@ var init_add_heading_anchors_plugin = __esm({
 });
 
 // libs/utils/html/plugins/cached-shiki.plugin.ts
-import rehypeShiki from "@shikijs/rehype";
 import { toString as toString2 } from "hast-util-to-string";
 import { visit as visit2 } from "unist-util-visit";
 function cachedShikiPlugin(settings2) {
-  const { cache, themes, identity, defaultLanguage } = settings2;
+  const { cache, themes, languages, identity, defaultLanguage } = settings2;
   const id = `${themes.light}
-${themes.dark}`;
+${themes.dark}
+${languages ?? ""}
+${settings2.grammars ?? "all"}`;
   return async (tree2) => {
     const blocks = [];
     visit2(tree2, "element", (node, index, parent) => {
@@ -1062,11 +1420,18 @@ ${themes.dark}`;
       blocks.push({
         node,
         parent,
-        key: cache.key({ options: identity, themes, lang, meta, code })
+        key: cache.key({
+          options: identity,
+          themes,
+          ...languages === void 0 ? {} : { languages },
+          lang,
+          meta,
+          code
+        })
       });
     });
     let highlighter;
-    const load = async () => highlighter ??= await highlighterFor(id, settings2.options);
+    const load = async () => highlighter ??= await highlighterFor(id, settings2.transformer);
     if (cache.loads?.(themes) !== true) await load();
     const values = [];
     for (const block of blocks) {
@@ -1087,13 +1452,11 @@ ${themes.dark}`;
     });
   };
 }
-function highlighterFor(id, options) {
+function highlighterFor(id, transformer) {
   const known3 = highlighters.get(id);
   if (known3) return known3;
   const created = (async () => {
-    const transform = rehypeShiki(
-      options()
-    );
+    const transform = transformer();
     await transform({ type: "root", children: [] });
     return transform;
   })();
@@ -1111,11 +1474,18 @@ async function highlight(transform, node) {
 function fragment(value) {
   try {
     const parsed = JSON.parse(value);
-    return Array.isArray(parsed) && parsed.length > 0 && parsed.every((item) => isNode(item) && item.type === "element") ? parsed : void 0;
+    return Array.isArray(parsed) && parsed.length > 0 && parsed.every(isReplacement) ? parsed : void 0;
   } catch {
     return void 0;
   }
 }
+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;
@@ -1308,11 +1678,158 @@ var init_table_wrapper = __esm({
   }
 });
 
+// libs/utils/html/shiki-grammars.ts
+import {
+  bundledLanguages,
+  createHighlighter
+} from "shiki";
+import { visit as visit7 } from "unist-util-visit";
+function shikiGrammars() {
+  grammars ??= ShikiGrammars.create().catch((error) => {
+    grammars = void 0;
+    throw error;
+  });
+  return grammars;
+}
+function createGrammarlessHighlighter(themes) {
+  return createHighlighter({ themes, langs: [] });
+}
+function blockLanguages(tree2, defaultLanguage) {
+  const languages = /* @__PURE__ */ new Set();
+  visit7(tree2, "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(languagePrefix2)) : void 0;
+    languages.add(
+      typeof languageClass === "string" ? languageClass.slice(languagePrefix2.length) : defaultLanguage
+    );
+  });
+  return languages;
+}
+function includedScopes(registration) {
+  const scopes = /* @__PURE__ */ 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;
+}
+function prefixes(scope) {
+  const parts = scope.split(".");
+  return parts.map((_, index) => parts.slice(0, index + 1).join("."));
+}
+var ShikiGrammars, grammars, languagePrefix2;
+var init_shiki_grammars = __esm({
+  "libs/utils/html/shiki-grammars.ts"() {
+    "use strict";
+    ShikiGrammars = class _ShikiGrammars {
+      constructor(registrations) {
+        this.byName = /* @__PURE__ */ new Map();
+        this.byScope = /* @__PURE__ */ new Map();
+        this.injectors = /* @__PURE__ */ new Map();
+        this.order = /* @__PURE__ */ new Map();
+        this.closures = /* @__PURE__ */ new Map();
+        this.loaded = /* @__PURE__ */ 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 known3 = this.closures.get(language);
+        if (known3) return known3;
+        const set = /* @__PURE__ */ 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 = /* @__PURE__ */ new Set());
+        const missing = /* @__PURE__ */ 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);
+      }
+    };
+    languagePrefix2 = "language-";
+  }
+});
+
 // libs/utils/html/process-html.ts
-import rehypeShiki2 from "@shikijs/rehype";
+import rehypeShiki from "@shikijs/rehype";
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { createHash as createHash2 } from "node:crypto";
 import rehypeMinifyWhitespace2 from "rehype-minify-whitespace";
 import rehypeParse3 from "rehype-parse";
 import rehypeStringify3 from "rehype-stringify";
+import { bundledLanguages as bundledLanguages2, createHighlighter as createHighlighter2 } from "shiki";
 import { unified as unified3 } from "unified";
 async function processHtml(html, config) {
   const anchors = /* @__PURE__ */ new Set();
@@ -1320,6 +1837,8 @@ async function processHtml(html, config) {
     light: config.lightTheme ?? "github-light",
     dark: config.darkTheme ?? "ayu-dark"
   };
+  const langs = config.langs?.length ? config.langs : void 0;
+  const used = !langs && config.grammars === "used";
   try {
     const content = await unified3().use(rehypeParse3, { fragment: true }).use(rehypeStringify3).use(mermaidPlugin).use(
       config.highlight ? [
@@ -1328,12 +1847,16 @@ async function processHtml(html, config) {
           {
             cache: config.highlight,
             themes,
+            ...langs ? { languages: languagesId(langs) } : {},
+            ...used ? { grammars: "used" } : {},
             identity: HIGHLIGHT_IDENTITY,
             defaultLanguage: DEFAULT_LANGUAGE,
-            options: () => shikiOptions(themes)
+            transformer: () => langs ? withLanguages(themes, langs) : used ? withUsedGrammars(themes) : rehypeShiki(
+              shikiOptions(themes)
+            )
           }
         ]
-      ] : [[rehypeShiki2, shikiOptions(themes)]]
+      ] : langs ? [[() => withLanguages(themes, langs)]] : used ? [[() => withUsedGrammars(themes)]] : [[rehypeShiki, shikiOptions(themes)]]
     ).use(highlightCodeLines).use(table_wrapper_default).use(sluggerPlugin, anchors.add.bind(anchors), config.headings).use(rehypeMinifyWhitespace2).use(addHeadingAnchors, config.route).use(markElementsPlugin).process(html).then((file) => file.toString());
     return { content, anchors: Array.from(anchors) };
   } catch (error) {
@@ -1359,7 +1882,59 @@ function shikiOptions(themes) {
 function shikiTheme(name) {
   return name === NG_DOC_SYNTAX_THEME_NAME ? ngDocSyntaxTheme() : name;
 }
-var DEFAULT_LANGUAGE, HIGHLIGHT_IDENTITY;
+function languagesId(langs) {
+  let id = languageIds.get(langs);
+  if (id === void 0) {
+    id = createHash2("sha256").update(JSON.stringify(langs)).digest("hex");
+    languageIds.set(langs, id);
+  }
+  return id;
+}
+function withLanguages(themes, langs) {
+  const id = `${themes.light}
+${themes.dark}
+${languagesId(langs)}`;
+  return async (tree2) => {
+    let highlighter = languageHighlighters.get(id);
+    if (!highlighter) {
+      highlighter = createHighlighter2({
+        themes: [shikiTheme(themes.light), shikiTheme(themes.dark)],
+        // Later registrations of a name replace earlier ones, so the given languages win.
+        langs: [...Object.keys(bundledLanguages2), ...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(tree2);
+  };
+}
+function withUsedGrammars(themes) {
+  const id = `${themes.light}
+${themes.dark}`;
+  return async (tree2) => {
+    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 [grammars2, ready] = await Promise.all([shikiGrammars(), highlighter]);
+    grammars2.load(ready, blockLanguages(tree2, DEFAULT_LANGUAGE));
+    const transform = rehypeShikiFromHighlighter(ready, shikiOptions(themes));
+    await transform(tree2);
+  };
+}
+var DEFAULT_LANGUAGE, HIGHLIGHT_IDENTITY, languageHighlighters, languageIds, usedHighlighters;
 var init_process_html = __esm({
   "libs/utils/html/process-html.ts"() {
     "use strict";
@@ -1371,24 +1946,28 @@ var init_process_html = __esm({
     init_mermaid_plugin();
     init_slugger_plugin();
     init_table_wrapper();
+    init_shiki_grammars();
     DEFAULT_LANGUAGE = "ts";
     HIGHLIGHT_IDENTITY = {
-      format: 1,
+      format: 2,
       defaultLanguage: DEFAULT_LANGUAGE,
       fallbackLanguage: "text",
       addLanguageClass: true,
       parseMetaString: "json-without-backslashes",
       tokenizeTimeLimit: 0
     };
+    languageHighlighters = /* @__PURE__ */ new Map();
+    languageIds = /* @__PURE__ */ new WeakMap();
+    usedHighlighters = /* @__PURE__ */ new Map();
   }
 });
 
 // libs/utils/html/plugins/remove-not-indexable-content.plugin.ts
 import { filter } from "unist-util-filter";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 function removeNotIndexableContentPlugin() {
   return (tree2) => {
-    visit7(tree2, "element", (node) => {
+    visit8(tree2, "element", (node) => {
       if (isHeading(node) && isHiddenSpan(node.children[0])) {
         node.children = node.children.slice(1);
       }
@@ -1469,8 +2048,7 @@ var init_utils = __esm({
   }
 });
 
-// libs/builder/generator/content/highlight-cache.ts
-init_core();
+// libs/builder/generator/content/format-cache.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { readFileSync as readFileSync5 } from "node:fs";
 import { mkdir as mkdir3, rename as rename3, rm as rm3, writeFile as writeFile3 } from "node:fs/promises";
@@ -1525,24 +2103,24 @@ function sha256Hex(value) {
 function canonicalJson(value) {
   return canonical(value, /* @__PURE__ */ new Set()) ?? "null";
 }
-function canonical(value, path17) {
+function canonical(value, path18) {
   if (value !== null && typeof value === "object" && typeof value.toJSON === "function")
     value = value.toJSON();
   if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (path17.has(value)) throw new TypeError("Converting circular structure to canonical JSON");
-  path17.add(value);
+  if (path18.has(value)) throw new TypeError("Converting circular structure to canonical JSON");
+  path18.add(value);
   let text;
   if (Array.isArray(value)) {
-    text = `[${Array.from(value, (item) => canonical(item, path17) ?? "null").join(",")}]`;
+    text = `[${Array.from(value, (item) => canonical(item, path18) ?? "null").join(",")}]`;
   } else {
     const fields = [];
     for (const key of Object.keys(value).sort(compareCodeUnits)) {
-      const item = canonical(value[key], path17);
+      const item = canonical(value[key], path18);
       if (item !== void 0) fields.push(`${JSON.stringify(key)}:${item}`);
     }
     text = `{${fields.join(",")}}`;
   }
-  path17.delete(value);
+  path18.delete(value);
   return text;
 }
 function canonicalJsonStrict(value) {
@@ -1649,16 +2227,16 @@ var ObservationRecorder = class {
    * file does not exist; a read error propagates.
    */
   readFile(file) {
-    const path17 = this.normalize(file);
-    let bytes = this.bytes?.get(path17);
+    const path18 = this.normalize(file);
+    let bytes = this.bytes?.get(path18);
     const exists = bytes !== void 0 || existsSync(file);
-    this.add({ kind: "existence", path: path17, exists });
+    this.add({ kind: "existence", path: path18, exists });
     if (!exists) return void 0;
     if (!bytes) {
       bytes = readFileSync(file);
-      this.bytes?.set(path17, bytes);
+      this.bytes?.set(path18, bytes);
     }
-    this.add({ kind: "content", path: path17, digest: bytesDigest(bytes) });
+    this.add({ kind: "content", path: path18, digest: bytesDigest(bytes) });
     return bytes;
   }
   /** {@link readFile} decoded as UTF-8; a missing file throws like `readFileSync`. */
@@ -1673,12 +2251,12 @@ var ObservationRecorder = class {
     return this.ordered.map(cloneDependency);
   }
 };
-function readText(path17) {
-  const bytes = readFileSync(path17);
+function readText(path18) {
+  const bytes = readFileSync(path18);
   return { text: bytes.toString("utf8"), digest: bytesDigest(bytes) };
 }
-async function readTextFile(path17) {
-  const bytes = await readFile(path17);
+async function readTextFile(path18) {
+  const bytes = await readFile(path18);
   return { text: bytes.toString("utf8"), digest: bytesDigest(bytes) };
 }
 function cloneDependency(dependency) {
@@ -2134,9 +2712,9 @@ var ObservationStamps = class {
         result.changed = { path: dependency.path, kind: "content" };
         return result;
       }
-      const current = stampOf(dependency.path);
+      const current2 = stampOf(dependency.path);
       const recorded = this.stamps.get(dependency.path);
-      if (current && recorded && sameStamp(current, recorded)) {
+      if (current2 && recorded && sameStamp(current2, recorded)) {
         result.stamped += 1;
         continue;
       }
@@ -2144,7 +2722,7 @@ var ObservationStamps = class {
       this.stamps.delete(dependency.path);
       let digest3;
       try {
-        digest3 = current ? this.digestOf(dependency.path) : void 0;
+        digest3 = current2 ? this.digestOf(dependency.path) : void 0;
       } catch {
         digest3 = void 0;
       }
@@ -2153,7 +2731,7 @@ var ObservationStamps = class {
         return result;
       }
       const after = stampOf(dependency.path);
-      if (current && after && sameStamp(current, after) && stampSettledBefore(after, startedNs)) {
+      if (current2 && after && sameStamp(current2, after) && stampSettledBefore(after, startedNs)) {
         this.stamps.set(dependency.path, after);
       }
     }
@@ -2298,8 +2876,8 @@ var DirectoryListings = class _DirectoryListings {
         result.changed = listing.path;
         return result;
       }
-      const current = directoryStamp(listing.path);
-      if (current && listing.stamp && sameStamp(current, listing.stamp)) {
+      const current2 = directoryStamp(listing.path);
+      if (current2 && listing.stamp && sameStamp(current2, listing.stamp)) {
         result.stamped += 1;
         continue;
       }
@@ -2310,7 +2888,7 @@ var DirectoryListings = class _DirectoryListings {
         return result;
       }
       const after = directoryStamp(listing.path);
-      if (current && after && sameStamp(current, after) && stampSettledBefore(after, startedNs)) {
+      if (current2 && after && sameStamp(current2, after) && stampSettledBefore(after, startedNs)) {
         listing.stamp = after;
       }
     }
@@ -2612,9 +3190,9 @@ var ReasonCollector = class {
   }
   add(ownerId, reason, detail) {
     const key = `${ownerId}\0${reason}`;
-    const current = this.reasons.get(key) ?? { ownerId, reason, details: /* @__PURE__ */ new Set() };
-    current.details.add(detail);
-    this.reasons.set(key, current);
+    const current2 = this.reasons.get(key) ?? { ownerId, reason, details: /* @__PURE__ */ new Set() };
+    current2.details.add(detail);
+    this.reasons.set(key, current2);
   }
   values() {
     return [...this.reasons.values()].map(({ ownerId, reason, details }) => ({
@@ -3002,9 +3580,11 @@ function isRoute(value) {
       "metadata",
       "category",
       "modulePath",
-      "apiListSegment"
+      "apiListSegment",
+      "demoModulePath",
+      "demoNames"
     ]
-  ) && [value.id, value.path, value.title].every(string) && (value.parentId === void 0 || string(value.parentId)) && (value.order === void 0 || finite(value.order)) && (value.hidden === void 0 || typeof value.hidden === "boolean") && (value.icon === void 0 || string(value.icon)) && (value.modulePath === void 0 || string(value.modulePath)) && (value.apiListSegment === void 0 || string(value.apiListSegment)) && (value.metadata === void 0 || isRecord(value.metadata) && exact(value.metadata, ["description", "tags"]) && string(value.metadata.description) && isRecord(value.metadata.tags) && Object.values(value.metadata.tags).every(stringArray)) && (value.category === void 0 || isRecord(value.category) && exact(value.category, ["runtimeImport"], ["expandable", "expanded"]) && isRecord(value.category.runtimeImport) && exact(value.category.runtimeImport, ["source", "exportName"]) && string(value.category.runtimeImport.source) && string(value.category.runtimeImport.exportName) && (value.category.expandable === void 0 || typeof value.category.expandable === "boolean") && (value.category.expanded === void 0 || typeof value.category.expanded === "boolean"));
+  ) && [value.id, value.path, value.title].every(string) && (value.parentId === void 0 || string(value.parentId)) && (value.order === void 0 || finite(value.order)) && (value.hidden === void 0 || typeof value.hidden === "boolean") && (value.icon === void 0 || string(value.icon)) && (value.modulePath === void 0 || string(value.modulePath)) && (value.apiListSegment === void 0 || string(value.apiListSegment)) && (value.demoModulePath === void 0 || string(value.demoModulePath)) && (value.demoNames === void 0 || stringArray(value.demoNames)) && (value.metadata === void 0 || isRecord(value.metadata) && exact(value.metadata, ["description", "tags"]) && string(value.metadata.description) && isRecord(value.metadata.tags) && Object.values(value.metadata.tags).every(stringArray)) && (value.category === void 0 || isRecord(value.category) && exact(value.category, ["runtimeImport"], ["expandable", "expanded"]) && isRecord(value.category.runtimeImport) && exact(value.category.runtimeImport, ["source", "exportName"]) && string(value.category.runtimeImport.source) && string(value.category.runtimeImport.exportName) && (value.category.expandable === void 0 || typeof value.category.expandable === "boolean") && (value.category.expanded === void 0 || typeof value.category.expanded === "boolean"));
 }
 function isApiList(value) {
   return isRecord(value) && exact(
@@ -3100,18 +3680,18 @@ function validDescriptorPlan(artifact) {
   const closures = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor.closureIds]));
   const visiting = /* @__PURE__ */ new Set();
   const visited2 = /* @__PURE__ */ new Set();
-  const visit8 = (id) => {
+  const visit9 = (id) => {
     if (visiting.has(id)) return false;
     if (visited2.has(id)) return true;
     visiting.add(id);
     const valid = (closures.get(id) ?? []).every(
-      (dependency) => ids.has(dependency) && visit8(dependency)
+      (dependency) => ids.has(dependency) && visit9(dependency)
     );
     visiting.delete(id);
     visited2.add(id);
     return valid;
   };
-  return [...ids].every(visit8);
+  return [...ids].every(visit9);
 }
 function absoluteNormalizedPath(value) {
   if (!string(value) || value.includes("\0") || value.includes("\\")) return false;
@@ -3358,7 +3938,9 @@ var TRACKED_PROGRAM_REUSE_FLAG = "NGDOC_TRACKED_PROGRAM_REUSE";
 var FAST_START_FLAG = "NGDOC_FAST_START";
 var PARALLEL_WRITES_FLAG = "NGDOC_PARALLEL_WRITES";
 var HIGHLIGHT_CACHE_FLAG = "NGDOC_HIGHLIGHT_CACHE";
+var FORMAT_CACHE_FLAG = "NGDOC_FORMAT_CACHE";
 var PARALLEL_RENDER_FLAG = "NGDOC_PARALLEL_RENDER";
+var USED_GRAMMARS_FLAG = "NGDOC_USED_GRAMMARS";
 var FLAGS = Object.freeze(
   [
     {
@@ -3436,6 +4018,16 @@ var FLAGS = Object.freeze(
       description: "Code blocks are highlighted with one Shiki highlighter per runtime and cached by their text, language, meta, themes and Shiki version; development keeps the cache beside the artifact cache.",
       verify: true
     },
+    {
+      name: FORMAT_CACHE_FLAG,
+      description: "The Prettier configuration is resolved once per generation, and formatted signatures and snippets are cached by their code, parser, configuration and Prettier version; development keeps the cache beside the artifact cache.",
+      verify: true
+    },
+    {
+      name: USED_GRAMMARS_FLAG,
+      description: "Code blocks are highlighted by a highlighter that loads only the Shiki grammars their languages reach, instead of every bundled grammar; the HTML is the same.",
+      verify: false
+    },
     {
       name: PARALLEL_RENDER_FLAG,
       description: "A large generation runs the HTML processing of its pages (highlighting, anchors, keyword links, search records) on up to four worker threads, while the main thread prepares the next pages in order.",
@@ -3481,6 +4073,10 @@ var RUNTIME_PACKAGES = [
   ["@shikijs/rehype"],
   ["shiki", "@shikijs/rehype"],
   ["@shikijs/core", "shiki"],
+  ["@shikijs/langs", "shiki"],
+  ["@shikijs/themes", "shiki"],
+  ["@shikijs/engine-oniguruma", "shiki"],
+  ["@shikijs/vscode-textmate", "@shikijs/core"],
   ["marked"],
   ["gray-matter"],
   ["nunjucks"],
@@ -3519,10 +4115,10 @@ function packageVersions(list, from) {
   return versions;
 }
 function packageDirectory(name, directory) {
-  for (let current = directory; ; current = path4.dirname(current)) {
-    const candidate = path4.join(current, "node_modules", name);
+  for (let current2 = directory; ; current2 = path4.dirname(current2)) {
+    const candidate = path4.join(current2, "node_modules", name);
     if (existsSync3(path4.join(candidate, "package.json"))) return candidate;
-    if (path4.dirname(current) === current) return void 0;
+    if (path4.dirname(current2) === current2) return void 0;
   }
 }
 function packageVersion(directory) {
@@ -3535,15 +4131,28 @@ function packageVersion(directory) {
   }
 }
 
-// libs/builder/generator/content/highlight-cache.ts
-var HIGHLIGHT_CACHE_MISMATCH = "CONTENT_HIGHLIGHT_CACHE_MISMATCH";
+// libs/builder/generator/content/format-cache.ts
+var FORMAT_CACHE_MISMATCH = "CONTENT_FORMAT_CACHE_MISMATCH";
 var PACK_VERSION = 1;
-var HIGHLIGHT_CACHE_LIMIT = 64 * 1024 * 1024;
+var SYNTAX_ERROR = "!";
+function encode(format) {
+  try {
+    return `=${format()}`;
+  } catch (error) {
+    if (error instanceof Error && error.name === "SyntaxError" && "loc" in error)
+      return SYNTAX_ERROR;
+    throw error;
+  }
+}
+function decode(entry) {
+  if (entry === SYNTAX_ERROR)
+    throw new SyntaxError("Prettier rejected this code before (format cache).");
+  return entry.slice(1);
+}
+var PRETTIER_PACKAGES = ["prettier", "@prettier/sync"];
+var FORMAT_CACHE_LIMIT = 16 * 1024 * 1024;
 var memory = /* @__PURE__ */ new Map();
 var memoryBytes = 0;
-var journal = [];
-var epoch = 0;
-var proven = /* @__PURE__ */ new Set();
 var packs = /* @__PURE__ */ new Map();
 var sizeOf = (key, value) => key.length + value.length;
 function remember(key, value) {
@@ -3551,11 +4160,213 @@ function remember(key, value) {
   if (previous !== void 0) memoryBytes -= sizeOf(key, previous);
   memory.set(key, value);
   memoryBytes += sizeOf(key, value);
+}
+function formatCacheSwitch(options) {
+  if (options.formatCache === false) return "off";
+  const value = readFlag(FORMAT_CACHE_FLAG).value;
+  return value === "off" ? "off" : options.formatCache === "verify" ? "verify" : value;
+}
+function createFormatSession(options, request, configuration) {
+  const mode = formatCacheSwitch(options);
+  if (mode === "off" || options.incrementalReuse === false) return void 0;
+  const pack = request.mode === "development" && configuration.cacheEnabled ? path5.join(configuration.cacheRoot, `${digestOf(options.projectId)}.format.json`) : void 0;
+  return new FormatSession(mode === "verify", pack);
+}
+var FormatSession = class {
+  constructor(verify, pack) {
+    this.verify = verify;
+    this.pack = pack;
+    /** The keys this generation hit or formatted. */
+    this.used = /* @__PURE__ */ new Set();
+    /** The resolved configuration per directory (`''` for the process's working directory). */
+    this.configs = /* @__PURE__ */ new Map();
+    /** Each resolved configuration's identity in the keys; undefined: not cacheable. */
+    this.identities = /* @__PURE__ */ new Map();
+    this.loaded = false;
+    /** An entry was replaced (a `verify` repair): the pack must be written. */
+    this.replaced = false;
+    this.mismatchCount = 0;
+    const engine = runtimePackages();
+    this.context = digestOf({
+      version: PACK_VERSION,
+      engine: Object.fromEntries(PRETTIER_PACKAGES.map((name) => [name, engine[name] ?? null]))
+    });
+    if (memoryBytes > FORMAT_CACHE_LIMIT) {
+      memory.clear();
+      memoryBytes = 0;
+      packs.clear();
+    }
+  }
+  /** How many `verify` hits and configurations differed from the cached ones. */
+  get mismatches() {
+    return this.mismatchCount;
+  }
+  config(configDirectory, resolve10) {
+    const directory = configDirectory ?? "";
+    if (this.configs.has(directory)) {
+      const known3 = this.configs.get(directory);
+      if (!this.verify) return known3;
+      const fresh = resolve10();
+      if (canonicalJsonStrict(fresh) === canonicalJsonStrict(known3)) return known3;
+      this.mismatchCount += 1;
+      return this.remember(directory, configDirectory, fresh);
+    }
+    return this.remember(directory, configDirectory, resolve10());
+  }
+  format(input, format) {
+    const identity = this.identities.get(input.config);
+    if (identity === void 0) return format();
+    this.load();
+    const key = digestOf({
+      context: this.context,
+      parser: input.parser,
+      config: identity,
+      code: input.code
+    });
+    const known3 = memory.get(key);
+    const usable = known3 !== void 0 && (known3 === SYNTAX_ERROR || known3.startsWith("="));
+    if (usable && !this.verify) {
+      this.used.add(key);
+      return decode(known3);
+    }
+    const value = encode(format);
+    if (known3 !== void 0 && known3 !== value) {
+      if (usable) this.mismatchCount += 1;
+      this.replaced = true;
+    }
+    if (known3 !== value) remember(key, value);
+    this.used.add(key);
+    return decode(value);
+  }
+  /**
+   * Writes the pack after the artifact cache: the entries this generation hit or formatted, plus
+   * those the pack held before unless the generation rendered every content (`complete`), or the
+   * result would exceed {@link FORMAT_CACHE_LIMIT}. Best effort.
+   * @param complete
+   */
+  async save(complete) {
+    if (!this.pack) return;
+    if (!this.loaded) return;
+    const file = this.pack;
+    const last = packs.get(file);
+    const previous = !complete && last?.context === this.context ? last.keys : [];
+    let selected = new Set([...previous, ...this.used].filter((key) => memory.has(key)));
+    const size = (keys2) => {
+      let total = 0;
+      for (const key of keys2) total += sizeOf(key, memory.get(key));
+      return total;
+    };
+    if (size(selected) > FORMAT_CACHE_LIMIT)
+      selected = new Set([...this.used].filter((key) => memory.has(key)));
+    const keys = [...selected].sort(compareCodeUnits);
+    if (!this.replaced && last?.context === this.context && last.keys.length === keys.length && last.keys.every((key, index) => key === keys[index]) && last.content === currentContent2(file))
+      return;
+    const content = {
+      version: PACK_VERSION,
+      context: this.context,
+      entries: Object.fromEntries(keys.map((key) => [key, memory.get(key)]))
+    };
+    const text = JSON.stringify(content);
+    const temporary = `${file}.${randomUUID3()}.tmp`;
+    try {
+      await mkdir3(path5.dirname(file), { recursive: true });
+      await sweepTemporaries(file);
+      await writeFile3(temporary, text, { flag: "wx" });
+      await retryingRename(rename3)(temporary, file);
+      packs.set(file, { context: this.context, keys, content: contentDigest(text) });
+      this.replaced = false;
+    } catch {
+      packs.delete(file);
+    } finally {
+      await rm3(temporary, { force: true }).catch(() => void 0);
+    }
+  }
+  remember(directory, configDirectory, config) {
+    const frozen = config && Object.isFrozen(config) ? config : config && Object.freeze(config);
+    this.configs.set(directory, frozen);
+    if (!this.identities.has(frozen))
+      this.identities.set(frozen, identityOf(frozen, configDirectory));
+    return frozen;
+  }
+  /** Reads the pack once per runtime and context; an unusable pack is not read. */
+  load() {
+    if (this.loaded) return;
+    this.loaded = true;
+    if (!this.pack || packs.get(this.pack)?.context === this.context) return;
+    try {
+      const bytes = readFileSync5(this.pack);
+      const value = JSON.parse(bytes.toString("utf8"));
+      if (!isPackFile(value) || value.context !== this.context) return;
+      const keys = Object.keys(value.entries).sort(compareCodeUnits);
+      for (const key of keys) if (!memory.has(key)) remember(key, value.entries[key]);
+      packs.set(this.pack, { context: this.context, keys, content: bytesDigest(bytes) });
+    } catch {
+    }
+  }
+};
+function identityOf(config, configDirectory) {
+  const json = canonicalJsonStrict(config);
+  if (json === void 0) return void 0;
+  const plugins = Array.isArray(config?.plugins) ? config.plugins : [];
+  const versions = {};
+  for (const plugin of plugins) {
+    if (typeof plugin !== "string" || plugin.startsWith(".") || path5.isAbsolute(plugin))
+      return void 0;
+    const version = packageVersions([[plugin]], configDirectory ?? process.cwd())[plugin];
+    if (!version) return void 0;
+    versions[plugin] = version;
+  }
+  return digestOf({ config: json, plugins: versions });
+}
+function currentContent2(file) {
+  try {
+    return bytesDigest(readFileSync5(file));
+  } catch {
+    return void 0;
+  }
+}
+function isPackFile(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const file = value;
+  const entries = file["entries"];
+  return file["version"] === PACK_VERSION && typeof file["context"] === "string" && !!entries && typeof entries === "object" && !Array.isArray(entries) && Object.values(entries).every((entry) => typeof entry === "string");
+}
+
+// libs/builder/generator/content/highlight-cache.ts
+init_core();
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { mkdir as mkdir4, rename as rename4, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
+import path6 from "node:path";
+var SHIKI_PACKAGES = [
+  "shiki",
+  "@shikijs/core",
+  "@shikijs/langs",
+  "@shikijs/themes",
+  "@shikijs/engine-oniguruma",
+  "@shikijs/vscode-textmate",
+  "@shikijs/rehype"
+];
+var HIGHLIGHT_CACHE_MISMATCH = "CONTENT_HIGHLIGHT_CACHE_MISMATCH";
+var PACK_VERSION2 = 1;
+var HIGHLIGHT_CACHE_LIMIT = 64 * 1024 * 1024;
+var memory2 = /* @__PURE__ */ new Map();
+var memoryBytes2 = 0;
+var journal = [];
+var epoch = 0;
+var proven = /* @__PURE__ */ new Set();
+var packs2 = /* @__PURE__ */ new Map();
+var sizeOf2 = (key, value) => key.length + value.length;
+function remember2(key, value) {
+  const previous = memory2.get(key);
+  if (previous !== void 0) memoryBytes2 -= sizeOf2(key, previous);
+  memory2.set(key, value);
+  memoryBytes2 += sizeOf2(key, value);
   journal.push([key, value]);
 }
 function forget() {
-  memory.clear();
-  memoryBytes = 0;
+  memory2.clear();
+  memoryBytes2 = 0;
   journal.length = 0;
   epoch += 1;
 }
@@ -3567,14 +4378,22 @@ function highlightCacheSwitch(options) {
   const value = readFlag(HIGHLIGHT_CACHE_FLAG).value;
   return value === "off" ? "off" : options.highlightCache === "verify" ? "verify" : value;
 }
+function grammarsSwitch(options) {
+  return options.usedGrammars === false || readFlag(USED_GRAMMARS_FLAG).value === "off" ? "all" : "used";
+}
 function createHighlightSession(options, request, configuration) {
   const mode = highlightCacheSwitch(options);
   if (mode === "off" || options.incrementalReuse === false) return void 0;
-  const pack = request.mode === "development" && configuration.cacheEnabled ? path5.join(configuration.cacheRoot, `${digestOf(options.projectId)}.highlight.json`) : void 0;
-  return new HighlightSession(configuration.themes, mode === "verify", pack);
+  const pack = request.mode === "development" && configuration.cacheEnabled ? path6.join(configuration.cacheRoot, `${digestOf(options.projectId)}.highlight.json`) : void 0;
+  return new HighlightSession(
+    configuration.themes,
+    mode === "verify",
+    pack,
+    configuration.shikiLangs
+  );
 }
 var HighlightSession = class {
-  constructor(themes, verify, pack) {
+  constructor(themes, verify, pack, langs) {
     this.themes = themes;
     this.verify = verify;
     this.pack = pack;
@@ -3585,17 +4404,15 @@ var HighlightSession = class {
     this.replaced = false;
     const engine = runtimePackages();
     this.context = digestOf({
-      version: PACK_VERSION,
-      engine: {
-        shiki: engine["shiki"] ?? null,
-        "@shikijs/core": engine["@shikijs/core"] ?? null,
-        "@shikijs/rehype": engine["@shikijs/rehype"] ?? null
-      },
-      themes: { light: themeIdentity(themes.light), dark: themeIdentity(themes.dark) }
+      version: PACK_VERSION2,
+      engine: Object.fromEntries(SHIKI_PACKAGES.map((name) => [name, engine[name] ?? null])),
+      themes: { light: themeIdentity(themes.light), dark: themeIdentity(themes.dark) },
+      // The configured languages: a block highlights with them, and they must load.
+      ...langs?.length ? { langs: digestOf(langs) } : {}
     });
-    if (memoryBytes > HIGHLIGHT_CACHE_LIMIT) {
+    if (memoryBytes2 > HIGHLIGHT_CACHE_LIMIT) {
       forget();
-      packs.clear();
+      packs2.clear();
     }
   }
   /** The cache of one `processHtml` call. */
@@ -3606,13 +4423,13 @@ var HighlightSession = class {
     return {
       key: (block) => digestOf({ context, block }),
       get: (key) => {
-        const value = memory.get(key);
+        const value = memory2.get(key);
         if (value !== void 0) used.add(key);
         return value;
       },
       set: (key, value) => {
-        if (memory.has(key)) this.replaced = true;
-        remember(key, value);
+        if (memory2.has(key)) this.replaced = true;
+        remember2(key, value);
         used.add(key);
         proven.add(context);
       },
@@ -3633,7 +4450,7 @@ var HighlightSession = class {
   }
   /** The entry this runtime holds for `key`, without counting it as used. */
   peek(key) {
-    return memory.get(key);
+    return memory2.get(key);
   }
   /**
    * Takes in what one document's highlighting recorded out of plan order (a render thread, or the
@@ -3647,32 +4464,32 @@ var HighlightSession = class {
     const fresh = new Map(record.fresh);
     let mismatches = 0;
     for (const key of record.mismatched) {
-      const known3 = memory.get(key);
+      const known3 = memory2.get(key);
       if (known3 !== void 0 && known3 !== fresh.get(key)) mismatches += 1;
     }
     for (const [key, value] of record.fresh) {
-      const known3 = memory.get(key);
+      const known3 = memory2.get(key);
       if (known3 === value) continue;
       if (known3 !== void 0) this.replaced = true;
-      remember(key, value);
+      remember2(key, value);
       proven.add(this.context);
     }
-    for (const key of record.used) if (memory.has(key)) this.used.add(key);
+    for (const key of record.used) if (memory2.has(key)) this.used.add(key);
     return mismatches;
   }
   /** Reads the pack once per runtime and context; an unusable pack is not read. */
   load() {
     if (this.loaded || !this.pack) return;
     this.loaded = true;
-    if (packs.get(this.pack)?.context === this.context) return;
+    if (packs2.get(this.pack)?.context === this.context) return;
     try {
-      const bytes = readFileSync5(this.pack);
+      const bytes = readFileSync6(this.pack);
       const value = JSON.parse(bytes.toString("utf8"));
-      if (!isPackFile(value) || value.context !== this.context) return;
+      if (!isPackFile2(value) || value.context !== this.context) return;
       const keys = Object.keys(value.entries).sort(compareCodeUnits);
-      for (const key of keys) if (!memory.has(key)) remember(key, value.entries[key]);
+      for (const key of keys) if (!memory2.has(key)) remember2(key, value.entries[key]);
       if (keys.length) proven.add(this.context);
-      packs.set(this.pack, { context: this.context, keys, content: bytesDigest(bytes) });
+      packs2.set(this.pack, { context: this.context, keys, content: bytesDigest(bytes) });
     } catch {
     }
   }
@@ -3685,55 +4502,55 @@ var HighlightSession = class {
   async save(complete) {
     if (!this.pack) return;
     const file = this.pack;
-    const last = packs.get(file);
+    const last = packs2.get(file);
     const previous = !complete && last?.context === this.context ? last.keys : [];
-    let selected = new Set([...previous, ...this.used].filter((key) => memory.has(key)));
+    let selected = new Set([...previous, ...this.used].filter((key) => memory2.has(key)));
     const size = (keys2) => {
       let total = 0;
-      for (const key of keys2) total += sizeOf(key, memory.get(key));
+      for (const key of keys2) total += sizeOf2(key, memory2.get(key));
       return total;
     };
     if (size(selected) > HIGHLIGHT_CACHE_LIMIT)
-      selected = new Set([...this.used].filter((key) => memory.has(key)));
+      selected = new Set([...this.used].filter((key) => memory2.has(key)));
     const keys = [...selected].sort(compareCodeUnits);
-    if (!this.replaced && last?.context === this.context && last.keys.length === keys.length && last.keys.every((key, index) => key === keys[index]) && last.content === currentContent2(file))
+    if (!this.replaced && last?.context === this.context && last.keys.length === keys.length && last.keys.every((key, index) => key === keys[index]) && last.content === currentContent3(file))
       return;
     const content = {
-      version: PACK_VERSION,
+      version: PACK_VERSION2,
       context: this.context,
-      entries: Object.fromEntries(keys.map((key) => [key, memory.get(key)]))
+      entries: Object.fromEntries(keys.map((key) => [key, memory2.get(key)]))
     };
     const text = JSON.stringify(content);
-    const temporary = `${file}.${randomUUID3()}.tmp`;
+    const temporary = `${file}.${randomUUID4()}.tmp`;
     try {
-      await mkdir3(path5.dirname(file), { recursive: true });
+      await mkdir4(path6.dirname(file), { recursive: true });
       await sweepTemporaries(file);
-      await writeFile3(temporary, text, { flag: "wx" });
-      await retryingRename(rename3)(temporary, file);
-      packs.set(file, { context: this.context, keys, content: contentDigest(text) });
+      await writeFile4(temporary, text, { flag: "wx" });
+      await retryingRename(rename4)(temporary, file);
+      packs2.set(file, { context: this.context, keys, content: contentDigest(text) });
       this.replaced = false;
     } catch {
-      packs.delete(file);
+      packs2.delete(file);
     } finally {
-      await rm3(temporary, { force: true }).catch(() => void 0);
+      await rm4(temporary, { force: true }).catch(() => void 0);
     }
   }
 };
 function themeIdentity(name) {
   return name === NG_DOC_SYNTAX_THEME_NAME ? { ngDoc: digestOf(ngDocSyntaxTheme()) } : name;
 }
-function currentContent2(file) {
+function currentContent3(file) {
   try {
-    return bytesDigest(readFileSync5(file));
+    return bytesDigest(readFileSync6(file));
   } catch {
     return void 0;
   }
 }
-function isPackFile(value) {
+function isPackFile2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const file = value;
   const entries = file["entries"];
-  return file["version"] === PACK_VERSION && typeof file["context"] === "string" && !!entries && typeof entries === "object" && !Array.isArray(entries) && Object.values(entries).every((entry) => typeof entry === "string");
+  return file["version"] === PACK_VERSION2 && typeof file["context"] === "string" && !!entries && typeof entries === "object" && !Array.isArray(entries) && Object.values(entries).every((entry) => typeof entry === "string");
 }
 
 // libs/builder/generator/content/html-pool.ts
@@ -3743,7 +4560,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Worker } from "node:worker_threads";
 
 // libs/builder/generator/worker/protocol.ts
-function encode(value) {
+function encode2(value) {
   const result = JSON.stringify(
     value,
     function(key, item) {
@@ -3756,7 +4573,7 @@ function encode(value) {
   if (result === void 0) throw new Error("Worker transport requires a JSON value");
   return result;
 }
-function decode(value) {
+function decode2(value) {
   if (typeof value !== "string") throw new Error("Worker message must be JSON text");
   const parsed = JSON.parse(value);
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -3769,7 +4586,7 @@ function decode(value) {
 import matter from "gray-matter";
 import { Marked } from "marked";
 import { existsSync as existsSync4 } from "node:fs";
-import path7 from "node:path";
+import path8 from "node:path";
 
 // libs/builder/helpers/keyword-heading-title.ts
 var LEADING_EMOJI = new RegExp("^(?:\\p{Regional_Indicator}{2}|(?:\\p{Emoji_Presentation}|\\p{Extended_Pictographic}\uFE0F)(?:\\p{Emoji_Modifier}|\uFE0F|\u200D\\p{Extended_Pictographic}\uFE0F?)*)\\s*", "u");
@@ -3818,7 +4635,16 @@ function param(key, newKeyName) {
 
 // libs/builder/parsers/parse-code-block-params.ts
 var CODE_BLOCK_LANGUAGE = /[\p{L}\p{N}+#-]+/u;
-function parseCodeBlockParams(options) {
+var SNIPPET_ID = /[a-zA-Z0-9-]+/;
+var LINE_RANGE = /^L(\d+)(?:(-)(?:L(\d+))?)?$/;
+function fileFragment(fragment2) {
+  const range = LINE_RANGE.exec(fragment2);
+  if (!range) return { snippet: fragment2 };
+  const fileLineStart = Number(range[1]) - 1;
+  if (!range[2]) return { fileLineStart, fileLineEnd: fileLineStart + 1 };
+  return { fileLineStart, fileLineEnd: range[3] === void 0 ? void 0 : Number(range[3]) };
+}
+function parseCodeBlockParams(options, parserOptions = {}) {
   const parser2 = P4.createLanguage({
     language: () => P4.regexp(CODE_BLOCK_LANGUAGE).skip(P4.optWhitespace).map((language) => ({ language })),
     // File Parsers
@@ -3829,7 +4655,7 @@ function parseCodeBlockParams(options) {
       (fileLineStart, fileLineEnd) => ({ fileLineStart, fileLineEnd })
     ),
     fileLineStart: (p) => P4.string("#").then(p["fileLineNumber"]).map((num) => num - 1).map((fileLineStart) => ({ fileLineStart, fileLineEnd: fileLineStart + 1 })),
-    lineParams: (p) => p["fileLineRange"].or(p["fileLineStart"]).fallback({}),
+    lineParams: (p) => (parserOptions.snippets ? P4.string("#").then(P4.regexp(SNIPPET_ID)).map(fileFragment) : p["fileLineRange"].or(p["fileLineStart"])).fallback({}),
     highlightedLinesRange: () => P4.seqMap(
       number.skip(P4.string("-")),
       number,
@@ -3845,7 +4671,11 @@ function parseCodeBlockParams(options) {
     active: () => P4.string("active").map(() => ({ active: true })),
     file: (p) => P4.seq(
       p["filePath"],
-      p["lineParams"].map(({ fileLineStart, fileLineEnd }) => ({ fileLineStart, fileLineEnd }))
+      p["lineParams"].map(({ fileLineStart, fileLineEnd, snippet: snippet2 }) => ({
+        fileLineStart,
+        fileLineEnd,
+        ...snippet2 === void 0 ? {} : { snippet: snippet2 }
+      }))
     ).map(([file, lineParams]) => ({ ...file, ...lineParams })),
     highlightedLines: (p) => p["highlightedLinesRange"].or(number).sepBy(P4.string(",").then(P4.optWhitespace)).wrap(P4.string("{"), P4.string("}")).map((a) => Array.from(new Set(a.flat()))).map((highlightedLines) => ({ highlightedLines })),
     // Combined Parsers
@@ -3960,11 +4790,62 @@ function footprintOf(result) {
 }
 
 // libs/builder/generator/kernel/paths.ts
-import path6 from "node:path";
-function hostPath(file, rules = path6) {
+import path7 from "node:path";
+function hostPath(file, rules = path7) {
   return rules.resolve(file).replace(/\\/g, "/");
 }
 
+// libs/builder/parsers/parse-snippet.ts
+import P5 from "parsimmon";
+function parseSnippet(string2) {
+  const parser2 = P5.createLanguage({
+    keyword: () => P5.string("snippet"),
+    id: () => P5.string("#").then(P5.regexp(/[a-zA-Z0-9-]+/)).fallback(null).map((id) => ({ id })),
+    lang: () => P5.string(":").then(P5.regexp(/[a-zA-Z0-9-]+/)).fallback(void 0).map((lang) => ({ lang })),
+    icon: () => param("icon"),
+    title: () => paramValue().map((title) => ({ title })),
+    opened: () => P5.string("opened").result(true).fallback(void 0).map((opened) => ({ opened })),
+    snippet: ({ keyword, id, lang, icon, title, opened }) => keyword.then(
+      P5.seq(
+        id,
+        lang,
+        P5.whitespace.then(title.or(icon).or(opened).sepBy(P5.whitespace)).fallback([])
+      ).map(([id2, lang2, rest]) => ({ ...id2, ...lang2, ...Object.assign({}, ...rest) }))
+    ),
+    snippetFromFile: ({ lang, icon, title, opened }) => P5.seq(
+      param("snippet-from-file", "fromFile"),
+      lang,
+      P5.whitespace.then(title.or(icon).or(opened).sepBy(P5.whitespace)).fallback([])
+    ).map(([id, lang2, rest]) => ({ ...id, ...lang2, ...Object.assign({}, ...rest) })),
+    anySnippet: ({ snippet: snippet2, snippetFromFile }) => snippetFromFile.or(snippet2)
+  });
+  const result = parser2.anySnippet.parse(string2);
+  return result.status ? result.value : void 0;
+}
+
+// libs/builder/generator/content/code-snippet.ts
+var MARKER = /^.*((\/\/|<!--|\/\*)\s*)(snippet.*?(?=(-->|\*\/)?))\s*(-->|\*\/)?$/;
+function snippetRegion(text, id) {
+  const lines = text.split("\n").map((line) => line.replace(/\r$/, ""));
+  const markers = lines.map((line) => {
+    const match = MARKER.exec(line);
+    return match ? parseSnippet(match[3].trim())?.id ?? null : void 0;
+  });
+  const start = markers.indexOf(id);
+  if (start < 0) return { status: "unknown" };
+  const end = markers.indexOf(id, start + 1);
+  if (end < 0) return { status: "unclosed" };
+  const region = removeLinesFromCode(
+    lines.slice(start + 1, end).filter((_, index) => markers[start + 1 + index] === void 0).join("\n")
+  ).split("\n");
+  while (region.length && !region[0].trim()) region.shift();
+  while (region.length && !region[region.length - 1].trim()) region.pop();
+  const indent = Math.min(
+    ...region.filter((line) => line.trim()).map((line) => line.length - line.trimStart().length)
+  );
+  return { status: "found", code: region.map((line) => line.slice(indent)).join("\n") };
+}
+
 // libs/builder/generator/content/html-pipeline.ts
 import { parseFile } from "@orama/plugin-parsedoc";
 var htmlUtilities = () => Promise.resolve().then(() => (init_utils(), utils_exports));
@@ -3972,13 +4853,13 @@ var notAborted = () => false;
 async function renderDocuments(task, highlight2, aborted = notAborted) {
   const results = [];
   for (const document of task.documents) {
-    const result = await renderDocument(document, task.themes, highlight2, aborted);
+    const result = await renderDocument(document, task, highlight2, aborted);
     results.push(result);
     if (!("html" in result)) break;
   }
   return results;
 }
-async function renderDocument(document, themes, highlight2, aborted) {
+async function renderDocument(document, { themes, langs, grammars: grammars2 }, highlight2, aborted) {
   if (aborted()) return { aborted: true, mismatches: 0 };
   const utilities = await htmlUtilities();
   if (aborted()) return { aborted: true, mismatches: 0 };
@@ -3988,6 +4869,8 @@ async function renderDocument(document, themes, highlight2, aborted) {
     ...document.route === void 0 ? {} : { route: document.route },
     lightTheme: themes.light,
     darkTheme: themes.dark,
+    ...langs ? { langs } : {},
+    grammars: grammars2 ?? "used",
     ...call ? { highlight: call } : {}
   });
   const mismatches = call?.mismatches.length ?? 0;
@@ -4106,6 +4989,7 @@ function recordingHighlight(settings2, themes, store) {
     }
   };
 }
+var WARM_DOCUMENT = ["ts", "angular-ts", "angular-html"].map((language) => `<pre><code class="language-${language}">warm</code></pre>`).join("");
 
 // libs/builder/generator/content/content-compiler.ts
 var PARALLEL_RENDER_MISMATCH = "CONTENT_PARALLEL_MISMATCH";
@@ -4120,10 +5004,11 @@ var GeneratorContentCompiler = class {
    *   is highlighted (`./highlight-cache`).
    * @param back - Where the HTML pipeline runs; without it, in this thread, at once.
    */
-  constructor(services, highlight2, back) {
+  constructor(services, highlight2, back, grammars2 = "used") {
     this.services = services;
     this.highlight = highlight2;
     this.back = back;
+    this.grammars = grammars2;
   }
   /**
    * Whether this call records its footprint. The semantic service's effective recorder state
@@ -4222,8 +5107,8 @@ var GeneratorContentCompiler = class {
           );
           return { dependencies, diagnostics };
         }
-        const current = await this.descriptorFields(request, dependencies, diagnostics, signal);
-        if (!current) {
+        const current2 = await this.descriptorFields(request, dependencies, diagnostics, signal);
+        if (!current2) {
           if (!diagnostics.some((item) => item.code === "CONTENT_ABORTED")) {
             diagnostics.push(
               this.diag(
@@ -4235,7 +5120,7 @@ var GeneratorContentCompiler = class {
           }
           return { dependencies, diagnostics };
         }
-        if (!this.matchesDescriptor(request, descriptor, current)) {
+        if (!this.matchesDescriptor(request, descriptor, current2)) {
           diagnostics.push(
             this.diag(
               "CONTENT_DESCRIPTOR_STALE",
@@ -4365,11 +5250,11 @@ var GeneratorContentCompiler = class {
       return `Descriptor closure for "${request.id}" is invalid.`;
     return void 0;
   }
-  matchesDescriptor(request, descriptor, current) {
+  matchesDescriptor(request, descriptor, current2) {
     return /^[a-f0-9]{64}$/.test(descriptor.requestDigest) && expectedContentId(request, descriptor.ownerId) === request.id && Number.isSafeInteger(descriptor.ordinal) && descriptor.ordinal >= 0 && sameValue2(
       descriptor.closureIds,
       request.kind === "header" ? [] : [`${descriptor.ownerId}:header`]
-    ) && sameValue2(omitDescriptorPublication(descriptor), current);
+    ) && sameValue2(omitDescriptorPublication(descriptor), current2);
   }
   matchesCompiledDependencies(descriptor, dependencies) {
     return descriptor.dependencies.every((expected) => {
@@ -4405,7 +5290,7 @@ var GeneratorContentCompiler = class {
         entryId: request.entry.id,
         source: { path: request.markdown },
         text: parsed.content,
-        scope: path7.dirname(request.markdown),
+        scope: path8.dirname(request.markdown),
         kind: "guide",
         values: {
           title: request.entry.title,
@@ -4423,7 +5308,7 @@ var GeneratorContentCompiler = class {
     const processed = await this.process(
       this.markdownToHtml(
         rendered.value,
-        path7.dirname(request.markdown),
+        path8.dirname(request.markdown),
         dependencies,
         diagnostics
       ),
@@ -4704,7 +5589,13 @@ var GeneratorContentCompiler = class {
    * `compileStaged` that the front is done: everything after the pipeline is pure.
    */
   render(documents, signal, staged) {
-    const task = { documents, themes: this.services.configuration.themes };
+    const { themes, shikiLangs } = this.services.configuration;
+    const task = {
+      documents,
+      themes,
+      ...shikiLangs ? { langs: shikiLangs } : {},
+      ...this.grammars === "all" ? { grammars: "all" } : {}
+    };
     const rendered = this.back ? this.back.render(task, signal) : renderDocuments(
       task,
       () => this.highlight?.call(),
@@ -4954,16 +5845,27 @@ var GeneratorContentCompiler = class {
   markdownToHtml(markdown, context, dependencies, diagnostics) {
     const renderer = {
       code: (code, language) => {
-        const options = parseCodeBlockParams(language?.trim() || "typescript");
+        const options = parseCodeBlockParams(language?.trim() || "typescript", { snippets: true });
         if (options.file) {
-          const source = hostPath(path7.resolve(context, options.file));
+          const source = hostPath(path8.resolve(context, options.file));
           const fullSource = this.readPhysicalFile(
             source,
             dependencies,
             diagnostics,
             "CONTENT_SNIPPET_READ"
           );
-          if (fullSource !== void 0) {
+          if (fullSource !== void 0 && options.snippet !== void 0) {
+            const region = snippetRegion(fullSource, options.snippet);
+            if (region.status === "found") code = region.code;
+            else
+              diagnostics.push(
+                this.diag(
+                  "CONTENT_SNIPPET_UNKNOWN",
+                  region.status === "unknown" ? `Snippet "${options.snippet}" is not in ${options.file}: no "snippet#${options.snippet}" marker.` : `Snippet "${options.snippet}" in ${options.file} has no closing "snippet#${options.snippet}" marker.`,
+                  source
+                )
+              );
+          } else if (fullSource !== void 0) {
             try {
               const sourceCode = fullSource.split("\n").slice(options.fileLineStart, options.fileLineEnd).join("\n").trim();
               code = removeLinesFromCode(sourceCode);
@@ -5152,7 +6054,7 @@ var HtmlThread = class {
   receive(message2) {
     let reply;
     try {
-      reply = decode(message2);
+      reply = decode2(message2);
     } catch (error) {
       this.fail(error);
       return;
@@ -5202,7 +6104,7 @@ var HtmlPool = class {
     while (this.threads.length < this.size) {
       const thread = new HtmlThread(this.entry, () => this.changed());
       this.threads.push(thread);
-      if (warm) thread.post(encode({ type: "warm", ...warm }));
+      if (warm) thread.post(encode2({ type: "warm", ...warm }));
     }
     this.changed();
   }
@@ -5358,7 +6260,7 @@ var RenderBack = class {
       signal,
       (thread, id) => [
         ...this.highlightSync(thread, settings2),
-        encode({
+        encode2({
           type: "render",
           id,
           task,
@@ -5392,9 +6294,9 @@ var RenderBack = class {
       pool,
       signal,
       (thread, id) => {
-        const messages = [encode({ type: "link", id, task, keywords: set })];
+        const messages = [encode2({ type: "link", id, task, keywords: set })];
         if (thread.keywords !== keywords) {
-          messages.unshift(encode({ type: "keywords", id: set, keywords }));
+          messages.unshift(encode2({ type: "keywords", id: set, keywords }));
           thread.keywords = keywords;
         }
         return messages;
@@ -5508,7 +6410,7 @@ var RenderBack = class {
     const from = reset ? 0 : thread.highlight.cursor;
     thread.highlight = { epoch: epoch2, cursor: entries.length };
     return [
-      encode({
+      encode2({
         type: "highlight",
         reset,
         context: settings2.context,
@@ -5605,7 +6507,7 @@ import fg2 from "fast-glob";
 import matter2 from "gray-matter";
 import { existsSync as existsSync6, realpathSync as realpathSync2 } from "node:fs";
 import { createRequire } from "node:module";
-import path8 from "node:path";
+import path9 from "node:path";
 import { types as nodeTypes } from "node:util";
 import vm from "node:vm";
 import nunjucks from "nunjucks";
@@ -5936,7 +6838,7 @@ var TrackingLoader = class extends nunjucks.Loader {
    * error escapes later as an uncaught exception. Thrown from the loader, it fails this render
    * synchronously, and each including template prefixes its own path to the message.
    */
-  compile(path17, text) {
+  compile(path18, text) {
     const environment = this.environment();
     try {
       return {
@@ -5947,13 +6849,13 @@ var TrackingLoader = class extends nunjucks.Loader {
             text,
             environment.asyncFilters,
             environment.extensionsList,
-            path17,
+            path18,
             environment.opts
           )
         )()
       };
     } catch (error) {
-      throw nunjucksLib._prettifyError(path17, environment.opts.dev, error);
+      throw nunjucksLib._prettifyError(path18, environment.opts.dev, error);
     }
   }
 };
@@ -6083,8 +6985,8 @@ function locateConfig(request, workspaceRoot, dependencies) {
     dependencies.observeFile(explicit);
     return existsSync6(explicit) ? explicit : void 0;
   }
-  let directory = path8.dirname(normalizeAbsolute(request.defaults.docsRoot, workspaceRoot));
-  const root = path8.parse(directory).root;
+  let directory = path9.dirname(normalizeAbsolute(request.defaults.docsRoot, workspaceRoot));
+  const root = path9.parse(directory).root;
   while (true) {
     for (const name of [
       "ng-doc.config.ts",
@@ -6092,12 +6994,12 @@ function locateConfig(request, workspaceRoot, dependencies) {
       "ng-doc.config.mjs",
       "ng-doc.config.cjs"
     ]) {
-      const candidate = path8.join(directory, name);
+      const candidate = path9.join(directory, name);
       if (dependencies.observeFile(candidate)) return normalizePath2(candidate);
     }
     if (directory === workspaceRoot || directory === root || !isWithin(workspaceRoot, directory))
       break;
-    directory = path8.dirname(directory);
+    directory = path9.dirname(directory);
   }
   return void 0;
 }
@@ -6158,7 +7060,10 @@ async function evaluateModules(workspaceRoot, tsConfig, configFile, descriptions
       treeShaking: true,
       tsconfig: normalizeAbsolute(tsConfig, workspaceRoot),
       logLevel: "silent",
-      plugins: [descriptionSanitizer(modules, dependencies, probes)]
+      plugins: [
+        ...configFile ? [browserModuleImports(configFile, dependencies)] : [],
+        descriptionSanitizer(modules, dependencies, probes)
+      ]
     });
     throwIfAborted(signal);
     const inputs = result.metafile?.inputs ?? {};
@@ -6218,6 +7123,35 @@ async function evaluateModules(workspaceRoot, tsConfig, configFile, descriptions
     throw error;
   }
 }
+var BROWSER_MODULE = "ng-doc-browser-module:";
+function browserModuleImports(configFile, dependencies) {
+  const config = normalizePath2(path9.resolve(configFile));
+  return {
+    name: "ng-doc-browser-module-imports",
+    setup(build2) {
+      build2.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.kind !== "dynamic-import" || args.pluginData?.ngDocBrowserModule || !path9.isAbsolute(args.importer) || normalizePath2(path9.resolve(args.importer)) !== config) {
+          return void 0;
+        }
+        if (path9.isAbsolute(args.path) || /^\.{1,2}\//.test(args.path)) {
+          observeResolutionCandidates(path9.resolve(args.resolveDir, args.path), dependencies);
+        }
+        const resolved = await build2.resolve(args.path, {
+          kind: "dynamic-import",
+          importer: args.importer,
+          resolveDir: args.resolveDir,
+          pluginData: { ngDocBrowserModule: true }
+        });
+        if (resolved.errors.length || !resolved.path || resolved.external) {
+          return { path: args.path, external: true };
+        }
+        const file = normalizeAbsolute(resolved.path);
+        dependencies.add({ kind: "existence", path: file, exists: true });
+        return { path: `${BROWSER_MODULE}${encodeURIComponent(file)}`, external: true };
+      });
+    }
+  };
+}
 function descriptionSanitizer(modules, dependencies, probes) {
   const kinds = new Map(modules.map((item) => [normalizePath2(item.source), item.kind]));
   const importers = /* @__PURE__ */ new Map();
@@ -6225,10 +7159,10 @@ function descriptionSanitizer(modules, dependencies, probes) {
     name: "ng-doc-description-sanitizer",
     setup(build2) {
       build2.onResolve({ filter: /.*/ }, (args) => {
-        if (!path8.isAbsolute(args.path) && !/^\.{1,2}\//.test(args.path)) return void 0;
-        const target = path8.resolve(args.resolveDir, args.path);
+        if (!path9.isAbsolute(args.path) && !/^\.{1,2}\//.test(args.path)) return void 0;
+        const target = path9.resolve(args.resolveDir, args.path);
         const candidates = observeResolutionCandidates(target, dependencies);
-        if (path8.isAbsolute(args.importer)) {
+        if (path9.isAbsolute(args.importer)) {
           let importer = importers.get(args.importer);
           if (importer === void 0) {
             importer = normalizeAbsolute(args.importer);
@@ -6248,7 +7182,7 @@ function descriptionSanitizer(modules, dependencies, probes) {
             kinds.get(normalizePath2(args.path)) ?? kindFor(args.path)
           ),
           loader: "ts",
-          resolveDir: path8.dirname(args.path)
+          resolveDir: path9.dirname(args.path)
         };
       });
       build2.onLoad({ filter: /\.(?:[cm]?[jt]s|[jt]sx|json)$/, namespace: "file" }, (args) => {
@@ -6257,8 +7191,8 @@ function descriptionSanitizer(modules, dependencies, probes) {
         if (!contents) return void 0;
         return {
           contents,
-          loader: BUNDLE_LOADERS[path8.extname(args.path).toLowerCase()] ?? "js",
-          resolveDir: path8.dirname(args.path)
+          loader: BUNDLE_LOADERS[path9.extname(args.path).toLowerCase()] ?? "js",
+          resolveDir: path9.dirname(args.path)
         };
       });
     }
@@ -6289,7 +7223,7 @@ function sanitizeDescription(source, kind) {
     (declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === exportName
   )?.initializer : void 0;
   const transformer = (context) => {
-    const visit8 = (node) => {
+    const visit9 = (node) => {
       if (node === root && ts.isObjectLiteralExpression(node)) {
         const properties = node.properties.flatMap((property) => {
           const name = propertyName(property);
@@ -6337,9 +7271,9 @@ function sanitizeDescription(source, kind) {
         });
         return context.factory.updateObjectLiteralExpression(node, properties);
       }
-      return ts.visitEachChild(node, visit8, context);
+      return ts.visitEachChild(node, visit9, context);
     };
-    return (node) => ts.visitNode(node, visit8);
+    return (node) => ts.visitNode(node, visit9);
   };
   const transformed = ts.transform(sourceFile, [transformer]);
   try {
@@ -6381,7 +7315,7 @@ var EvaluationScope = class {
     this.timers = /* @__PURE__ */ new Set();
     this.disposed = false;
     this.networkAbort = new AbortController();
-    const filename = path8.join(workspaceRoot, ".ng-doc-discovery-evaluator.cjs");
+    const filename = path9.join(workspaceRoot, ".ng-doc-discovery-evaluator.cjs");
     const module = { exports: {} };
     const nativeRequire = createRequire(filename);
     const schedule = (callback, delay, ...args) => {
@@ -6464,7 +7398,7 @@ var EvaluationScope = class {
   evaluate(code, timeoutMs) {
     this.assertActive();
     new vm.Script(code, {
-      filename: path8.join(this.workspaceRoot, ".ng-doc-discovery-evaluator.cjs")
+      filename: path9.join(this.workspaceRoot, ".ng-doc-discovery-evaluator.cjs")
     }).runInContext(this.context, { timeout: timeoutMs });
     return this.context.module.exports;
   }
@@ -6497,6 +7431,7 @@ async function normalizeConfiguration(request, workspaceRoot, configFile, raw, d
   const globalKeywords = normalizeKeywords(
     validGlobalKeywords(raw.keywords?.keywords ?? {}, configFile ?? workspaceRoot, diagnostics)
   );
+  const shikiLangs = shikiLanguages(raw.shiki?.langs, configFile ?? workspaceRoot, diagnostics);
   const remoteKeywords = [];
   const executables = [];
   const loaders = raw.keywords?.loaders ?? [];
@@ -6543,12 +7478,16 @@ async function normalizeConfiguration(request, workspaceRoot, configFile, raw, d
   );
   const headerTemplate = raw.guide?.headerTemplate ? normalizeAbsolute(raw.guide.headerTemplate, workspaceRoot) : void 0;
   if (headerTemplate) dependencies.observeFile(headerTemplate);
+  const demoApplication = demoApplicationSettings(raw, configFile ?? workspaceRoot, diagnostics);
+  if (diagnostics.some((item) => item.severity === "error")) {
+    return { globalKeywords, remoteKeywords, diagnostics };
+  }
   const withoutDigest = {
     projectId: request.projectId,
     workspaceRoot,
     docsRoots,
     tsConfig: normalizeAbsolute(raw.tsConfig ?? request.defaults.tsConfig, workspaceRoot),
-    outputRoot: raw.outDir === void 0 ? normalizeAbsolute(request.defaults.outputRoot, workspaceRoot) : normalizeAbsolute(path8.join(workspaceRoot, raw.outDir, "ng-doc", request.projectId)),
+    outputRoot: raw.outDir === void 0 ? normalizeAbsolute(request.defaults.outputRoot, workspaceRoot) : normalizeAbsolute(path9.join(workspaceRoot, raw.outDir, "ng-doc", request.projectId)),
     cacheRoot: normalizeAbsolute(request.defaults.cacheRoot, workspaceRoot),
     routePrefix: normalizeRoute(raw.routePrefix ?? ""),
     guideDirectory: "guides",
@@ -6557,10 +7496,13 @@ async function normalizeConfiguration(request, workspaceRoot, configFile, raw, d
     inlineStyleLanguage: options.inlineStyleLanguage,
     anchorHeadings: raw.guide?.anchorHeadings ?? options.defaultAnchorHeadings,
     headerTemplate,
+    ...raw.api?.protectedMembers === false ? { apiProtectedMembers: false } : {},
+    ...demoApplication ? { demoApplication } : {},
     themes: {
       light: raw.shiki?.themes?.light ?? options.defaultThemes.light,
       dark: raw.shiki?.themes?.dark ?? options.defaultThemes.dark
     },
+    ...shikiLangs.length ? { shikiLangs } : {},
     repo: raw.repoConfig ? {
       url: raw.repoConfig.url,
       platform: raw.repoConfig.platform ?? "github",
@@ -6581,12 +7523,87 @@ async function normalizeConfiguration(request, workspaceRoot, configFile, raw, d
   };
   return { configuration, globalKeywords, remoteKeywords, diagnostics };
 }
+var DEFAULT_DEMO_PATH = "demo-preview";
+var DEMO_PATH_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function demoApplicationSettings(raw, source, diagnostics) {
+  const invalid = (code, message2) => {
+    diagnostics.push({
+      code,
+      severity: "error",
+      stage: "evaluation",
+      message: message2,
+      source: { path: source }
+    });
+    return void 0;
+  };
+  const { isolatedDemos, demoApplication, demoProviders } = raw;
+  if (isolatedDemos !== void 0 && typeof isolatedDemos !== "boolean") {
+    return invalid("DISCOVERY_DEMO_APPLICATION_INVALID", "isolatedDemos must be a boolean.");
+  }
+  const configured = demoApplication !== null && typeof demoApplication === "object";
+  if (demoApplication !== void 0 && typeof demoApplication !== "boolean" && !configured) {
+    return invalid(
+      "DISCOVERY_DEMO_APPLICATION_INVALID",
+      "demoApplication must be a boolean or an object."
+    );
+  }
+  let demoPath;
+  if (configured && demoApplication.path !== void 0) {
+    const value = demoApplication.path;
+    const segments = typeof value === "string" ? value.split("/").filter(Boolean) : [];
+    if (!segments.length || segments.some((segment) => !DEMO_PATH_SEGMENT.test(segment))) {
+      return invalid(
+        "DISCOVERY_DEMO_PATH_INVALID",
+        `demoApplication.path must be one or more URL segments of letters, digits, '-', '_' and '.', each starting with a letter or a digit; got ${JSON.stringify(value)}.`
+      );
+    }
+    demoPath = segments.join("/");
+  }
+  const providers = demoProviders === void 0 ? void 0 : demoProvidersModule(demoProviders, invalid);
+  if (demoProviders !== void 0 && !providers) return void 0;
+  if (demoApplication === false && isolatedDemos === true) {
+    diagnostics.push({
+      code: "DISCOVERY_DEMO_APPLICATION_OFF",
+      severity: "warning",
+      stage: "evaluation",
+      message: "isolatedDemos has no effect while demoApplication is false: demos render in the page.",
+      source: { path: source }
+    });
+  }
+  const pages = demoApplication === false ? "none" : isolatedDemos === true || demoApplication === true || configured ? "all" : void 0;
+  const settings2 = {
+    ...pages ? { pages } : {},
+    ...isolatedDemos === true && pages !== "none" ? { isolated: true } : {},
+    ...demoPath && demoPath !== DEFAULT_DEMO_PATH ? { path: demoPath } : {},
+    ...providers ? { providers } : {}
+  };
+  return Object.keys(settings2).length ? settings2 : void 0;
+}
+function demoProvidersModule(value, invalid) {
+  const usage = "write it as `demoProviders: () => import('./demo.providers')` in ng-doc.config.ts";
+  if (typeof value !== "function") {
+    return invalid(
+      "DISCOVERY_DEMO_PROVIDERS_INVALID",
+      `demoProviders must be a function: ${usage}.`
+    );
+  }
+  const compact = Function.prototype.toString.call(value).replace(/\s+/g, "");
+  const marker = `(["'\`])${BROWSER_MODULE}([^"'\`]+)\\1`;
+  const match = new RegExp(`^(?:async)?\\(\\)=>\\(?import\\(${marker}\\)\\)?$`).exec(compact) ?? new RegExp(`^(?:async)?\\(\\)=>\\{returnimport\\(${marker}\\);?\\}$`).exec(compact);
+  if (!match) {
+    return invalid(
+      "DISCOVERY_DEMO_PROVIDERS_IMPORT",
+      compact.includes(BROWSER_MODULE) ? `demoProviders must only import its module: ${usage}.` : `demoProviders must import a file by a literal path that resolves from ng-doc.config.ts: ${usage}.`
+    );
+  }
+  return decodeURIComponent(match[2]);
+}
 function describeEntries(projectId, workspaceRoot, routePrefix, modules, closures, allDependencies, diagnostics, tags) {
   const moduleByObject = /* @__PURE__ */ new Map();
   for (const item of modules) moduleByObject.set(item.value, item);
   const idBySource = /* @__PURE__ */ new Map();
   for (const item of modules) {
-    const relative3 = path8.relative(workspaceRoot, item.source);
+    const relative3 = path9.relative(workspaceRoot, item.source);
     if (!isWithin(workspaceRoot, item.source)) {
       diagnostics.push({
         code: "DISCOVERY_SOURCE_OUTSIDE_WORKSPACE",
@@ -6699,7 +7716,7 @@ function describeEntries(projectId, workspaceRoot, routePrefix, modules, closure
     liveEntries.set(id, entry);
     if (module.kind === "guide") {
       const markdown = asArray2(entry.mdFile).map(
-        (file) => normalizeAbsolute(String(file), path8.dirname(module.source))
+        (file) => normalizeAbsolute(String(file), path9.dirname(module.source))
       );
       for (const file of markdown) allDependencies.observeFile(file);
       return {
@@ -6772,7 +7789,7 @@ function guideKeywords(mdFile, source, dependencies) {
   const keywords = /* @__PURE__ */ new Set();
   for (const file of asArray2(mdFile)) {
     try {
-      const text = dependencies.readFile(normalizeAbsolute(String(file), path8.dirname(source)));
+      const text = dependencies.readFile(normalizeAbsolute(String(file), path9.dirname(source)));
       const keyword = text ? matter2(text.toString("utf8")).data.keyword : void 0;
       if (typeof keyword === "string" && keyword) keywords.add(`*${keyword}`);
     } catch {
@@ -6823,6 +7840,58 @@ function validGlobalKeywords(value, source, diagnostics) {
   }
   return valid;
 }
+function shikiLanguages(value, source, diagnostics) {
+  if (value === void 0) return [];
+  const invalid = (message2) => {
+    diagnostics.push({
+      code: "DISCOVERY_SHIKI_LANGUAGE_INVALID",
+      severity: "error",
+      stage: "evaluation",
+      message: message2,
+      source: { path: source }
+    });
+    return [];
+  };
+  if (!Array.isArray(value))
+    return invalid("shiki.langs must be an array of Shiki language registrations.");
+  const languages = [];
+  for (const [index, entry] of value.entries()) {
+    for (const item of Array.isArray(entry) ? entry : [entry]) {
+      const json = plainJson(item, 0);
+      if (!json || typeof json !== "object" || Array.isArray(json) || typeof json["name"] !== "string" || !json["name"] || typeof json["scopeName"] !== "string" || !json["scopeName"])
+        return invalid(
+          `shiki.langs[${index}] is not a Shiki language registration: plain JSON data with a name and a scopeName. Import the grammar instead of passing a function or a promise.`
+        );
+      languages.push(json);
+    }
+  }
+  return languages;
+}
+function plainJson(value, depth) {
+  if (depth > 256) return void 0;
+  if (value === null || typeof value === "boolean" || typeof value === "string") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (Array.isArray(value)) {
+    const copy2 = [];
+    for (const item of value) {
+      const json = plainJson(item, depth + 1);
+      if (json === void 0) return void 0;
+      copy2.push(json);
+    }
+    return copy2;
+  }
+  if (typeof value !== "object") return void 0;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && Object.getPrototypeOf(prototype) !== null || Object.prototype.toString.call(value) !== "[object Object]")
+    return void 0;
+  const copy = {};
+  for (const [key, item] of Object.entries(value)) {
+    const json = plainJson(item, depth + 1);
+    if (json === void 0) return void 0;
+    copy[key] = json;
+  }
+  return copy;
+}
 function normalizeKeywords(value) {
   return Object.entries(value).sort(([left], [right]) => compareCodeUnits(left, right)).map(([key, keyword]) => ({
     key,
@@ -6834,12 +7903,12 @@ function normalizeKeywords(value) {
   }));
 }
 function observeResolutionCandidates(target, dependencies) {
-  const extension = path8.extname(target);
+  const extension = path9.extname(target);
   const candidates = [".ts", ".tsx", ".js", ".mjs", ".cjs", ".json"].includes(extension) ? [target] : [
     target,
     ...[".ts", ".tsx", ".js", ".mjs", ".cjs", ".json"].map((suffix) => `${target}${suffix}`),
     ...[".ts", ".tsx", ".js", ".mjs", ".cjs"].map(
-      (suffix) => path8.join(target, `index${suffix}`)
+      (suffix) => path9.join(target, `index${suffix}`)
     )
   ];
   for (const candidate of candidates)
@@ -6851,7 +7920,7 @@ function observeResolutionCandidates(target, dependencies) {
   return candidates.map(normalizePath2);
 }
 function kindFor(file) {
-  const basename2 = path8.basename(file);
+  const basename2 = path9.basename(file);
   const kind = ENTRY_KIND.get(basename2);
   if (!kind) throw new Error(`Unsupported description filename: ${file}`);
   return kind;
@@ -6861,12 +7930,12 @@ function entryRoute(kind, entry, source) {
   if (kind === "guide") {
     if (typeof route === "object" && route !== null)
       return normalizeRoute(
-        String(route.path ?? path8.basename(path8.dirname(source)))
+        String(route.path ?? path9.basename(path9.dirname(source)))
       );
-    return normalizeRoute(String(route ?? path8.basename(path8.dirname(source))));
+    return normalizeRoute(String(route ?? path9.basename(path9.dirname(source))));
   }
   if (kind === "api") return normalizeRoute(String(route ?? "api"));
-  return normalizeRoute(String(route ?? path8.basename(path8.dirname(source))));
+  return normalizeRoute(String(route ?? path9.basename(path9.dirname(source))));
 }
 function stableId(projectId, kind, relativeSource) {
   return `${projectId}:${kind}:${sha256Hex(relativeSource).slice(0, 16)}`;
@@ -6879,23 +7948,23 @@ function digestDependencies(dependencies) {
   );
 }
 function normalizeAbsolute(value, base) {
-  const absolute = path8.isAbsolute(value) ? path8.resolve(value) : path8.resolve(base ?? process.cwd(), value);
+  const absolute = path9.isAbsolute(value) ? path9.resolve(value) : path9.resolve(base ?? process.cwd(), value);
   if (existsSync6(absolute)) return normalizePath2(realpathSync2.native(absolute));
-  const existingParent = nearestExistingParent(path8.dirname(absolute));
+  const existingParent = nearestExistingParent(path9.dirname(absolute));
   const canonicalParent = realpathSync2.native(existingParent);
-  return normalizePath2(path8.join(canonicalParent, path8.relative(existingParent, absolute)));
+  return normalizePath2(path9.join(canonicalParent, path9.relative(existingParent, absolute)));
 }
 function nearestExistingParent(value) {
-  let current = value;
-  while (!existsSync6(current)) {
-    const parent = path8.dirname(current);
-    if (parent === current) return current;
-    current = parent;
+  let current2 = value;
+  while (!existsSync6(current2)) {
+    const parent = path9.dirname(current2);
+    if (parent === current2) return current2;
+    current2 = parent;
   }
-  return current;
+  return current2;
 }
 function normalizePath2(value) {
-  return value.replaceAll(path8.sep, "/");
+  return value.replaceAll(path9.sep, "/");
 }
 function normalizeRoute(value) {
   return value.replaceAll("\\", "/").split("/").filter(Boolean).join("/");
@@ -6979,7 +8048,7 @@ var FUNCTION_KEYS = /* @__PURE__ */ new Set([
 function canonicalValue(root) {
   const seen = /* @__PURE__ */ new Map();
   let functions = false;
-  const visit8 = (value2, at) => {
+  const visit9 = (value2, at) => {
     if (value2 === null || typeof value2 === "string" || typeof value2 === "boolean") return value2;
     if (typeof value2 === "number")
       return Number.isFinite(value2) ? value2 : { $number: String(value2) };
@@ -7013,11 +8082,11 @@ function canonicalValue(root) {
       if (typeof key === "symbol" || skipped.has(key)) continue;
       const descriptor = Object.getOwnPropertyDescriptor(object, key);
       if (!("value" in descriptor)) throw new Unattested(`accessor at ${at}.${key}`);
-      result.push([key, visit8(descriptor.value, `${at}.${key}`)]);
+      result.push([key, visit9(descriptor.value, `${at}.${key}`)]);
     }
     return result.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
   };
-  const value = visit8(root, "$");
+  const value = visit9(root, "$");
   return { value, functions };
 }
 function sortDependencies(dependencies) {
@@ -7035,8 +8104,8 @@ function dependenciesForEntry(all, source, related = []) {
   return all.filter((item) => "path" in item && paths.has(item.path));
 }
 function isWithin(parent, child) {
-  const relative3 = path8.relative(parent, child);
-  return relative3 !== ".." && !relative3.startsWith(`..${path8.sep}`) && !path8.isAbsolute(relative3);
+  const relative3 = path9.relative(parent, child);
+  return relative3 !== ".." && !relative3.startsWith(`..${path9.sep}`) && !path9.isAbsolute(relative3);
 }
 function throwIfAborted(signal) {
   if (signal.aborted) throw signal.reason ?? new Error("Discovery was aborted.");
@@ -7065,27 +8134,27 @@ function awaitWithLimits(value, signal, timeoutMs) {
   });
 }
 function jsonData(value, omitOptional = true) {
-  const active = /* @__PURE__ */ new Set();
-  function visit8(input) {
+  const active2 = /* @__PURE__ */ new Set();
+  function visit9(input) {
     if (input === null || typeof input === "string" || typeof input === "boolean") return input;
     if (typeof input === "number" && Number.isFinite(input)) return input;
-    if (typeof input !== "object" || input === null || active.has(input)) {
+    if (typeof input !== "object" || input === null || active2.has(input)) {
       throw new TypeError("Discovery produced a non-JSON value.");
     }
-    active.add(input);
+    active2.add(input);
     try {
-      if (Array.isArray(input)) return Array.from(input, visit8);
+      if (Array.isArray(input)) return Array.from(input, visit9);
       if (Object.prototype.toString.call(input) !== "[object Object]") {
         throw new TypeError("Discovery produced a non-JSON object.");
       }
       return Object.fromEntries(
-        Object.entries(input).filter(([, item]) => !omitOptional || item !== void 0).map(([key, item]) => [key, visit8(item)])
+        Object.entries(input).filter(([, item]) => !omitOptional || item !== void 0).map(([key, item]) => [key, visit9(item)])
       );
     } finally {
-      active.delete(input);
+      active2.delete(input);
     }
   }
-  return visit8(value);
+  return visit9(value);
 }
 function failure(dependencies, diagnostics) {
   return { dependencies: dependencies.all(), diagnostics };
@@ -7107,7 +8176,7 @@ function isBuildFailure(error) {
 }
 
 // libs/builder/generator/outputs/index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
 import { dirname, isAbsolute, posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { Environment, Loader } from "nunjucks";
@@ -7142,8 +8211,43 @@ var STRUCTURAL_TEMPLATES = [
   "api-list.ts.nunj",
   "routes.ts.nunj",
   "context.ts.nunj",
-  "index.ts.nunj"
+  "index.ts.nunj",
+  "demo-routes.ts.nunj",
+  "demo-app.ts.nunj"
 ];
+var DEFAULT_DEMO_PATH2 = "demo-preview";
+var DEMO_NAME = /^[A-Za-z0-9_$-]+$/;
+var DEMO_ACTION = /<ng-doc-demo\b[^>]*>\s*<div\b[^>]*\bid="options"[^>]*>([^<]*)<\/div>/g;
+function demoSettings(configuration) {
+  const settings2 = configuration.demoApplication;
+  return {
+    pages: settings2?.pages ?? "isolated",
+    isolated: settings2?.isolated === true,
+    path: settings2?.path ?? DEFAULT_DEMO_PATH2,
+    ...settings2?.providers ? { providers: settings2.providers } : {}
+  };
+}
+function decodeHtmlText(value) {
+  return value.replace(
+    /&(?:#x([0-9a-f]+)|#([0-9]+)|(amp|lt|gt|quot|apos));/gi,
+    (all, hex, dec, name) => {
+      if (hex) return String.fromCodePoint(parseInt(hex, 16));
+      if (dec) return String.fromCodePoint(parseInt(dec, 10));
+      return { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" }[String(name).toLowerCase()] ?? all;
+    }
+  );
+}
+function hasIsolatedDemo(html) {
+  for (const match of html?.matchAll(DEMO_ACTION) ?? []) {
+    try {
+      if (JSON.parse(decodeHtmlText(match[1]))?.isolated === true) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
+}
 function pageAssemblyKey(request, templates) {
   const text = canonicalJsonStrict({
     schema: "page-assembly-key-v1",
@@ -7172,7 +8276,7 @@ function moduleSpecifier(fromDirectory, target) {
   return specifier.startsWith(".") ? specifier : `./${specifier}`;
 }
 function templateString(value) {
-  return String(value ?? "").replace(/`/g, "\\`").replace(/\$\{/g, "\\${").replace(/{/g, "\\{").replace(/}/g, "\\}");
+  return String(value ?? "").replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${").replace(/{/g, "\\{").replace(/}/g, "\\}");
 }
 function escapeAttribute2(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -7205,24 +8309,24 @@ function safeRelative(value) {
 function joinOutput(...parts) {
   return safeRelative(posix.join(...parts.map(normalize)));
 }
-function output(path17, role, content) {
-  return { path: path17, role, encoding: "utf8", content, digest: sha256Hex(content) };
+function output(path18, role, content) {
+  return { path: path18, role, encoding: "utf8", content, digest: sha256Hex(content) };
 }
 function addOutput(outputs, candidate, diagnostics, ownerId) {
-  const path17 = safeRelative(candidate.path);
-  if (!path17) {
+  const path18 = safeRelative(candidate.path);
+  if (!path18) {
     diagnostics.push(
       diagnostic2("OUTPUT_PATH_INVALID", `Unsafe generated output path: ${candidate.path}`, ownerId)
     );
     return;
   }
-  if (outputs.has(path17)) {
+  if (outputs.has(path18)) {
     diagnostics.push(
-      diagnostic2("OUTPUT_COLLISION", `Generated output collision: ${path17}`, ownerId)
+      diagnostic2("OUTPUT_COLLISION", `Generated output collision: ${path18}`, ownerId)
     );
     return;
   }
-  outputs.set(path17, { ...candidate, path: path17 });
+  outputs.set(path18, { ...candidate, path: path18 });
 }
 function isWithin2(parent, child) {
   const value = relative(resolve(parent), resolve(child));
@@ -7271,29 +8375,29 @@ function apiListType(declaration) {
   return kind ? `${kind[0].toUpperCase()}${kind.slice(1)}` : "";
 }
 function strictJson(value) {
-  const active = /* @__PURE__ */ new Set();
-  const visit8 = (item) => {
+  const active2 = /* @__PURE__ */ new Set();
+  const visit9 = (item) => {
     if (item === null || typeof item === "string" || typeof item === "boolean") return;
     if (typeof item === "number" && Number.isFinite(item) && !Object.is(item, -0)) return;
-    if (typeof item !== "object" || item === null || active.has(item)) {
+    if (typeof item !== "object" || item === null || active2.has(item)) {
       throw new TypeError("Aggregate JSON must be a finite, acyclic JSON tree.");
     }
-    active.add(item);
+    active2.add(item);
     try {
       if (Array.isArray(item)) {
         if (Object.keys(item).length !== item.length)
           throw new TypeError("Aggregate JSON arrays cannot be sparse.");
-        item.forEach(visit8);
+        item.forEach(visit9);
       } else {
         if (Object.prototype.toString.call(item) !== "[object Object]")
           throw new TypeError("Aggregate JSON contains an unsupported object.");
-        for (const child of Object.values(item)) visit8(child);
+        for (const child of Object.values(item)) visit9(child);
       }
     } finally {
-      active.delete(item);
+      active2.delete(item);
     }
   };
-  visit8(value);
+  visit9(value);
   return JSON.stringify(value);
 }
 function tree(values, diagnostics) {
@@ -7348,27 +8452,27 @@ function pruneEmptyCategories(nodes) {
 }
 function validateRoutePaths(nodes, diagnostics, parentPath = "", seen = /* @__PURE__ */ new Map()) {
   for (const node of nodes) {
-    const path17 = posix.join(parentPath, normalize(node.item.route)).replace(/^\/+|\/+$/g, "");
-    const owner = seen.get(path17);
+    const path18 = posix.join(parentPath, normalize(node.item.route)).replace(/^\/+|\/+$/g, "");
+    const owner = seen.get(path18);
     if (owner && owner !== node.item.id) {
       diagnostics.push(
         diagnostic2(
           "OUTPUT_ROUTE_PATH_COLLISION",
-          `Routes ${owner} and ${node.item.id} resolve to the same public path: ${path17}`,
+          `Routes ${owner} and ${node.item.id} resolve to the same public path: ${path18}`,
           node.item.id
         )
       );
     } else {
-      seen.set(path17, node.item.id);
+      seen.set(path18, node.item.id);
     }
-    validateRoutePaths(node.children, diagnostics, path17, seen);
+    validateRoutePaths(node.children, diagnostics, path18, seen);
   }
 }
 function validateOutputOwnership(artifacts, aggregate, diagnostics) {
   const owners = /* @__PURE__ */ new Map();
   const observe2 = (candidate, ownerId) => {
-    const path17 = safeRelative(candidate.path);
-    if (!path17) {
+    const path18 = safeRelative(candidate.path);
+    if (!path18) {
       diagnostics.push(
         diagnostic2(
           "OUTPUT_PATH_INVALID",
@@ -7378,18 +8482,18 @@ function validateOutputOwnership(artifacts, aggregate, diagnostics) {
       );
       return;
     }
-    const previous = owners.get(path17);
+    const previous = owners.get(path18);
     if (previous) {
       diagnostics.push(
         diagnostic2(
           "OUTPUT_CANDIDATE_COLLISION",
-          `Artifacts ${previous} and ${ownerId} both own generated output ${path17}.`,
+          `Artifacts ${previous} and ${ownerId} both own generated output ${path18}.`,
           ownerId
         )
       );
       return;
     }
-    owners.set(path17, ownerId);
+    owners.set(path18, ownerId);
   };
   for (const artifact of artifacts) {
     for (const candidate of artifact.outputs) observe2(candidate, artifact.id);
@@ -7398,11 +8502,11 @@ function validateOutputOwnership(artifacts, aggregate, diagnostics) {
 }
 function keywordMap(keywords) {
   return Object.fromEntries(
-    keywords.map(({ key, title, path: path17, type, languages, description }) => [
+    keywords.map(({ key, title, path: path18, type, languages, description }) => [
       key,
       {
         title,
-        path: path17,
+        path: path18,
         ...type === void 0 ? {} : { type },
         ...languages === void 0 ? {} : { languages },
         ...description === void 0 ? {} : { description }
@@ -7420,7 +8524,7 @@ var StructuralLoader = class extends Loader {
     if (!isWithin2(this.root, source) || !existsSync7(source)) {
       throw new Error(`Structural template not found: ${source}`);
     }
-    return { src: readFileSync6(source, "utf8"), path: source, noCache: true };
+    return { src: readFileSync7(source, "utf8"), path: source, noCache: true };
   }
 };
 function render2(root, name, context) {
@@ -7431,7 +8535,7 @@ function render2(root, name, context) {
   environment.addFilter("toTemplateString", templateString);
   environment.addFilter(
     "createImportPath",
-    (current, target) => relativeImport(current, target)
+    (current2, target) => relativeImport(current2, target)
   );
   environment.addFilter("dump", (value) => strictJson(value));
   environment.addFilter(
@@ -7628,7 +8732,7 @@ function validateDescriptorPartition(request, diagnostics) {
     const markdown = descriptors.filter((descriptor) => descriptor.role === "guide-tab").map(
       (descriptor) => descriptor.locator.kind === "guide-tab" ? descriptor.locator.markdown : ""
     );
-    if (markdown.length !== guide.markdown.length || new Set(markdown).size !== markdown.length || markdown.some((path17, index) => path17 !== guide.markdown[index]) || descriptors.some((descriptor) => descriptor.role === "api-tab"))
+    if (markdown.length !== guide.markdown.length || new Set(markdown).size !== markdown.length || markdown.some((path18, index) => path18 !== guide.markdown[index]) || descriptors.some((descriptor) => descriptor.role === "api-tab"))
       diagnostics.push(
         diagnostic2(
           "OUTPUT_DESCRIPTOR_MEMBERSHIP",
@@ -7640,18 +8744,18 @@ function validateDescriptorPartition(request, diagnostics) {
   const closures = new Map(descriptors.map((descriptor) => [descriptor.id, descriptor.closureIds]));
   const visiting = /* @__PURE__ */ new Set();
   const visited2 = /* @__PURE__ */ new Set();
-  const visit8 = (id) => {
+  const visit9 = (id) => {
     if (visiting.has(id)) return false;
     if (visited2.has(id)) return true;
     visiting.add(id);
     const ok = (closures.get(id) ?? []).every(
-      (dependency) => ids.has(dependency) && visit8(dependency)
+      (dependency) => ids.has(dependency) && visit9(dependency)
     );
     visiting.delete(id);
     visited2.add(id);
     return ok;
   };
-  if (![...ids].every(visit8))
+  if (![...ids].every(visit9))
     diagnostics.push(
       diagnostic2(
         "OUTPUT_DESCRIPTOR_CLOSURE",
@@ -7706,15 +8810,15 @@ var OutputAssemblerImpl = class {
     const dependencies = [];
     const diagnostics = [];
     for (const name of STRUCTURAL_TEMPLATES) {
-      const path17 = hostPath(resolve(this.templateRoot, name));
+      const path18 = hostPath(resolve(this.templateRoot, name));
       try {
-        dependencies.push({ kind: "content", path: path17, digest: (await readTextFile(path17)).digest });
+        dependencies.push({ kind: "content", path: path18, digest: (await readTextFile(path18)).digest });
       } catch (error) {
-        dependencies.push({ kind: "existence", path: path17, exists: false });
+        dependencies.push({ kind: "existence", path: path18, exists: false });
         diagnostics.push(
           diagnostic2(
             "OUTPUT_TEMPLATE_READ",
-            `Cannot read structural template ${path17}: ${String(error)}`
+            `Cannot read structural template ${path18}: ${String(error)}`
           )
         );
       }
@@ -7791,7 +8895,9 @@ var OutputAssemblerImpl = class {
         // Every API list the site has, so the search palette requests no other one.
         apiLists: request.entries.filter((entry) => entry.kind === "api").map((entry) => apiAssetRoute(entry, request.configuration))
       });
-      this.renderOutput(outputs, diagnostics, "index.ts", "angular", "index.ts.nunj", {});
+      this.renderOutput(outputs, diagnostics, "index.ts", "angular", "index.ts.nunj", {
+        demoApplication: this.demoApplication(request, records, outputs, diagnostics)
+      });
       const searchPath = joinOutput(request.configuration.assetDirectory, "indexes.json");
       const keywordPath = joinOutput(request.configuration.assetDirectory, "keywords.json");
       if (!searchPath || !keywordPath) {
@@ -7855,6 +8961,8 @@ var OutputAssemblerImpl = class {
     const wrapperPath = joinOutput(directory, "page.ts");
     const demoPath = joinOutput(directory, "demo-assets.ts");
     const playgroundPath = joinOutput(directory, "playgrounds.ts");
+    const demoPages = this.demoRoutes(request, directory, [header2, ...tabs], outputs, diagnostics);
+    const demoSettingsOfPage = demoSettings(request.configuration);
     const tabEntries = {};
     for (const tab of tabs) {
       const tabPath = joinOutput(directory, tab.route || "index", "page.ts");
@@ -7884,6 +8992,10 @@ var OutputAssemblerImpl = class {
           pageType: "guide",
           entryPath: request.entry.runtimeImport.source,
           entryHasImports: request.entry.hasImports,
+          ...demoPages ? {
+            demoRoute: `${demoSettingsOfPage.path}/${request.entry.absoluteRoute}`,
+            isolatedDemos: demoSettingsOfPage.isolated
+          } : {},
           demoAssetsPath: resolve(request.configuration.outputRoot, demoPath),
           playgroundsPath: resolve(request.configuration.outputRoot, playgroundPath)
         },
@@ -7979,8 +9091,55 @@ var OutputAssemblerImpl = class {
       ...request.entry.order === void 0 ? {} : { order: request.entry.order },
       ...request.entry.hidden === void 0 ? {} : { hidden: request.entry.hidden },
       ...request.metadata ? { metadata: request.metadata } : {},
-      modulePath: wrapperPath
+      modulePath: wrapperPath,
+      ...demoPages ? { demoModulePath: demoPages.path, demoNames: demoPages.names } : {}
+    });
+  }
+  /**
+   * Writes the guide's demo routes module (one route per demo, under the page's own providers)
+   * when the guide gets demo pages: with `pages: 'all'`, or by default when its content has a demo
+   * with `isolated: true`. Returns its path and the names of the demos that got a page, or
+   * undefined.
+   */
+  demoRoutes(request, directory, slots, outputs, diagnostics) {
+    const settings2 = demoSettings(request.configuration);
+    const names = Object.keys(request.semantics?.demos ?? {});
+    if (settings2.pages === "none" || !names.length || settings2.pages === "isolated" && !slots.some((slot) => hasIsolatedDemo(slot.linked?.html))) {
+      return void 0;
+    }
+    const demos = names.filter((name) => {
+      if (DEMO_NAME.test(name)) return true;
+      diagnostics.push({
+        ...diagnostic2(
+          "OUTPUT_DEMO_NAME_INVALID",
+          `Demo ${JSON.stringify(name)} has no demo page: a demo name must be letters, digits, '_', '$' or '-' to be its page's URL segment.`,
+          request.entry.id
+        ),
+        severity: "warning"
+      });
+      return false;
     });
+    const path18 = joinOutput(directory, "demo-routes.ts");
+    if (!path18 || !demos.length) return void 0;
+    this.renderOutput(
+      outputs,
+      diagnostics,
+      path18,
+      "angular",
+      "demo-routes.ts.nunj",
+      {
+        entryImport: moduleSpecifier(
+          dirname(resolve(request.configuration.outputRoot, path18)),
+          request.entry.runtimeImport.source
+        ),
+        demos: demos.map((name) => ({
+          name,
+          title: `${request.entry.title}: ${name}`
+        }))
+      },
+      request.entry.id
+    );
+    return outputs.has(path18) ? { path: path18, names: demos } : void 0;
   }
   apiEntry(request, outputs, routes, diagnostics) {
     const assetRoute = apiAssetRoute(request.entry, request.configuration);
@@ -8146,18 +9305,18 @@ var OutputAssemblerImpl = class {
           ...record.signature ? { signature: record.signature } : {}
         }))
       }));
-      const path17 = joinOutput(
+      const path18 = joinOutput(
         request.configuration.assetDirectory,
         apiAssetRoute(entry, request.configuration),
         "api-list.json"
       );
-      if (!path17) {
+      if (!path18) {
         diagnostics.push(
           diagnostic2("OUTPUT_PATH_INVALID", `Unsafe API asset route: ${entry.route}`)
         );
         continue;
       }
-      addOutput(outputs, output(path17, "api-list", strictJson(lists)), diagnostics, entry.id);
+      addOutput(outputs, output(path18, "api-list", strictJson(lists)), diagnostics, entry.id);
     }
   }
   addContentSource(outputs, diagnostics, componentPath, slot, configuration, ownerId) {
@@ -8210,11 +9369,48 @@ export default source;
       ownerId
     );
   }
-  renderOutput(outputs, diagnostics, path17, role, template, context, ownerId) {
-    const safe = safeRelative(path17);
+  /**
+   * Writes `demo-app.ts`, the routes of the demo application (one lazy route per guide with demo
+   * pages, under its categories' providers) and its `demoProviders` import, when a guide has demo
+   * pages. Returns whether it did.
+   */
+  demoApplication(request, records, outputs, diagnostics) {
+    const settings2 = demoSettings(request.configuration);
+    const outputRoot = resolve(request.configuration.outputRoot);
+    const entries = new Map(request.entries.map((entry) => [entry.id, entry]));
+    const categories = /* @__PURE__ */ new Map();
+    const pages = records.filter((record) => record.demoModulePath && entries.get(record.id)?.kind === "guide").map((record) => {
+      const chain = [];
+      for (let parent = entries.get(record.id)?.parentId; parent !== void 0; parent = entries.get(parent)?.parentId) {
+        const category = entries.get(parent);
+        if (category?.kind !== "category") break;
+        const identifier = categoryIdentifier(request.configuration.projectId, category.id);
+        categories.set(identifier, moduleSpecifier(outputRoot, category.runtimeImport.source));
+        chain.unshift(identifier);
+      }
+      const route = `${settings2.path}/${entries.get(record.id).absoluteRoute}`;
+      return {
+        path: route,
+        demos: (record.demoNames ?? []).map((name) => `${route}/${name}`),
+        categories: chain,
+        importPath: moduleSpecifier(outputRoot, resolve(outputRoot, record.demoModulePath))
+      };
+    }).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    if (!pages.length) return false;
+    this.renderOutput(outputs, diagnostics, "demo-app.ts", "routes", "demo-app.ts.nunj", {
+      demoPath: settings2.path,
+      demoPages: pages.flatMap((page) => page.demos),
+      pages,
+      categories: [...categories].sort(([left], [right]) => left < right ? -1 : 1),
+      ...settings2.providers ? { providersImport: moduleSpecifier(outputRoot, settings2.providers) } : {}
+    });
+    return true;
+  }
+  renderOutput(outputs, diagnostics, path18, role, template, context, ownerId) {
+    const safe = safeRelative(path18);
     if (!safe) {
       diagnostics.push(
-        diagnostic2("OUTPUT_PATH_INVALID", `Unsafe generated output path: ${path17}`, ownerId)
+        diagnostic2("OUTPUT_PATH_INVALID", `Unsafe generated output path: ${path18}`, ownerId)
       );
       return;
     }
@@ -8240,6 +9436,30 @@ function createOutputAssembler(options = {}) {
   return new OutputAssemblerImpl(options);
 }
 
+// libs/builder/helpers/format-cache.ts
+var active;
+function withFormatCodeCache(cache, run) {
+  const previous = active;
+  active = cache;
+  try {
+    return run();
+  } finally {
+    active = previous;
+  }
+}
+function activeFormatCodeCache() {
+  return active;
+}
+
+// libs/builder/generator/semantic/formatting.ts
+var current;
+function useFormatCache(cache) {
+  current = cache;
+}
+function formatting(run) {
+  return withFormatCodeCache(current, run);
+}
+
 // libs/builder/generator/semantic/semantic-service.ts
 import { dirname as dirname9, resolve as resolve9 } from "node:path";
 import { setImmediate as setImmediate2 } from "node:timers";
@@ -8306,7 +9526,7 @@ function getComponentInputs(cls) {
 
 // libs/builder/helpers/angular/get-component-source-files.ts
 init_core();
-import path9 from "path";
+import path10 from "path";
 
 // libs/builder/helpers/angular/get-component-decorator.ts
 import { Node as Node4 } from "ts-morph";
@@ -8348,12 +9568,12 @@ function getComponentSourceFiles(cls) {
   const decoratorData = getComponentDecorator(cls);
   if (decoratorData) {
     const filePath = cls.getSourceFile().getFilePath();
-    const fileDir = path9.dirname(filePath);
+    const fileDir = path10.dirname(filePath);
     return asArray(
       filePath,
-      decoratorData.templateUrl ? path9.join(fileDir, decoratorData.templateUrl) : [],
+      decoratorData.templateUrl ? path10.join(fileDir, decoratorData.templateUrl) : [],
       asArray(decoratorData.styleUrls, decoratorData.styleUrl).map(
-        (styleUrl) => path9.join(fileDir, styleUrl)
+        (styleUrl) => path10.join(fileDir, styleUrl)
       )
     );
   }
@@ -8626,15 +9846,18 @@ function collect(node, into, seen) {
       }
     }
     if (Node13.isEnumDeclaration(declaration)) {
-      declaration.getMembers().forEach((member) => into.push(member.getType().compilerType));
+      declaration.getMembers().forEach((member) => into.push(regularType(member.getType().compilerType)));
       return;
     }
   }
   into.push(node.getType().compilerType);
 }
+function regularType(type) {
+  return type.regularType ?? type;
+}
 
 // libs/builder/helpers/snippets-from-asset.ts
-import path11 from "path";
+import path12 from "path";
 
 // libs/builder/helpers/process-legacy-snippets.ts
 init_core();
@@ -8687,35 +9910,7 @@ function removeSnippetsInCode(code) {
 // libs/builder/helpers/process-snippets.ts
 init_core();
 import * as fs from "fs";
-import path10 from "path";
-
-// libs/builder/parsers/parse-snippet.ts
-import P5 from "parsimmon";
-function parseSnippet(string2) {
-  const parser2 = P5.createLanguage({
-    keyword: () => P5.string("snippet"),
-    id: () => P5.string("#").then(P5.regexp(/[a-zA-Z0-9-]+/)).fallback(null).map((id) => ({ id })),
-    lang: () => P5.string(":").then(P5.regexp(/[a-zA-Z0-9-]+/)).fallback(void 0).map((lang) => ({ lang })),
-    icon: () => param("icon"),
-    title: () => paramValue().map((title) => ({ title })),
-    opened: () => P5.string("opened").result(true).fallback(void 0).map((opened) => ({ opened })),
-    snippet: ({ keyword, id, lang, icon, title, opened }) => keyword.then(
-      P5.seq(
-        id,
-        lang,
-        P5.whitespace.then(title.or(icon).or(opened).sepBy(P5.whitespace)).fallback([])
-      ).map(([id2, lang2, rest]) => ({ ...id2, ...lang2, ...Object.assign({}, ...rest) }))
-    ),
-    snippetFromFile: ({ lang, icon, title, opened }) => P5.seq(
-      param("snippet-from-file", "fromFile"),
-      lang,
-      P5.whitespace.then(title.or(icon).or(opened).sepBy(P5.whitespace)).fallback([])
-    ).map(([id, lang2, rest]) => ({ ...id, ...lang2, ...Object.assign({}, ...rest) })),
-    anySnippet: ({ snippet: snippet2, snippetFromFile }) => snippetFromFile.or(snippet2)
-  });
-  const result = parser2.anySnippet.parse(string2);
-  return result.status ? result.value : void 0;
-}
+import path11 from "path";
 
 // libs/builder/helpers/format-code.ts
 import prettierSync from "@prettier/sync";
@@ -8724,16 +9919,19 @@ function formatCode(code, codeType = "TypeScript", configDirectory) {
   try {
     if (codeType) {
       const parser2 = getPrettierParserFromCodeType(codeType);
-      const config = prettierSync.resolveConfig(
+      const cache = activeFormatCodeCache();
+      const resolve10 = () => prettierSync.resolveConfig(
         // Prettier searches from a file's parent, so use a synthetic path inside the directory.
         configDirectory ? join(configDirectory, "__ng_doc_format__.ts") : process.cwd(),
         { editorconfig: true, useCache: false }
       );
-      return prettierSync.format(code, {
+      const config = cache ? cache.config(configDirectory, resolve10) : resolve10();
+      const format = () => prettierSync.format(code, {
         ...config,
         parser: parser2,
         embeddedLanguageFormatting: "auto"
       }).trim();
+      return cache && typeof parser2 === "string" ? cache.format({ code, parser: parser2, config }, format) : format();
     }
     return code.trim();
   } catch (e) {
@@ -8806,9 +10004,9 @@ function processSnippets(code, basePath, configDirectory) {
         const { title, lang, icon, opened, fromFile } = config;
         const language = lang || (isHTMLComment ? "angular-html" : "angular-ts");
         if (fromFile) {
-          const snippetCode = fs.readFileSync(path10.join(basePath, fromFile), "utf-8");
+          const snippetCode = fs.readFileSync(path11.join(basePath, fromFile), "utf-8");
           result.push({
-            title: title ?? path10.basename(fromFile),
+            title: title ?? path11.basename(fromFile),
             lang: language,
             icon,
             opened,
@@ -8857,7 +10055,7 @@ function removeSnippets(code) {
 // libs/builder/helpers/snippets-from-asset.ts
 function snippetsFromAsset(asset, inlineStylesType, configDirectory) {
   const snippets = processLegacySnippets(asset.code).concat(
-    processSnippets(asset.code, path11.dirname(asset.filePath), configDirectory)
+    processSnippets(asset.code, path12.dirname(asset.filePath), configDirectory)
   );
   const codeType = codeTypeFromExt(asset.filePath);
   const isStylesFile = ["CSS", "SCSS", "LESS", "SASS"].includes(codeType.toUpperCase());
@@ -8915,17 +10113,17 @@ var TrackedFiles = class extends ObservationRecorder {
     super(initial, { normalize: normalize2, observer });
   }
   read(file) {
-    const path17 = normalize2(file);
-    this.add({ kind: "existence", path: path17, exists: existsSync8(path17) });
+    const path18 = normalize2(file);
+    this.add({ kind: "existence", path: path18, exists: existsSync8(path18) });
     try {
-      const { text, digest: digest3 } = readText(path17);
-      this.add({ kind: "content", path: path17, digest: digest3 });
+      const { text, digest: digest3 } = readText(path18);
+      this.add({ kind: "content", path: path18, digest: digest3 });
       return text;
     } catch (error) {
       throw new SemanticFailure(
         "SEMANTIC_INPUT_READ",
         error instanceof Error ? error.message : String(error),
-        { path: path17 }
+        { path: path18 }
       );
     }
   }
@@ -8964,8 +10162,8 @@ function recordDerivedQuery(identity, query) {
   top()?.recordDerived(identity);
   return suspendRecording(query);
 }
-function recordLookup(path17) {
-  top()?.record(path17, "lookup");
+function recordLookup(path18) {
+  top()?.record(path18, "lookup");
 }
 var allocator = ts3.objectAllocator;
 var SymbolObject = allocator.getSymbolConstructor();
@@ -8973,9 +10171,9 @@ var TypeObject = allocator.getTypeConstructor();
 var SignatureObject = allocator.getSignatureConstructor();
 var visited = /* @__PURE__ */ new WeakMap();
 function fileOf(node) {
-  let current = node;
-  while (current && current.kind !== ts3.SyntaxKind.SourceFile) current = current.parent;
-  return current?.fileName;
+  let current2 = node;
+  while (current2 && current2.kind !== ts3.SyntaxKind.SourceFile) current2 = current2.parent;
+  return current2?.fileName;
 }
 function moduleSourceFile(specifier, context) {
   const declaration = context.getSymbolAtLocation(specifier)?.declarations?.find((item) => ts3.isSourceFile(item));
@@ -8987,17 +10185,17 @@ function starClosure(source, context) {
   const cached = context.stars.get(source.fileName);
   if (cached) return cached;
   const files = /* @__PURE__ */ new Set();
-  const visit8 = (file) => {
+  const visit9 = (file) => {
     for (const statement of file.statements) {
       if (!ts3.isExportDeclaration(statement) || statement.exportClause || !statement.moduleSpecifier)
         continue;
       const target = moduleSourceFile(statement.moduleSpecifier, context);
       if (!target || files.has(target.fileName)) continue;
       files.add(target.fileName);
-      visit8(target);
+      visit9(target);
     }
   };
-  visit8(source);
+  visit9(source);
   const closure = [...files];
   context.stars.set(source.fileName, closure);
   return closure;
@@ -9523,7 +10721,7 @@ function structural(type) {
 }
 function reorder(root, print, checker, restore) {
   const seen = /* @__PURE__ */ new Set();
-  const visit8 = (type, level) => {
+  const visit9 = (type, level) => {
     if (!type || seen.has(type)) return;
     seen.add(type);
     const parts = type;
@@ -9533,16 +10731,16 @@ function reorder(root, print, checker, restore) {
       ...parts.resolvedTypeArguments ?? [],
       ...parts.aliasTypeArguments ?? []
     ])
-      visit8(inner, level);
+      visit9(inner, level);
     if (level < DEPTH && structural(type))
       suspendRecording(() => {
         for (const property of checker.getPropertiesOfType(type))
-          visit8(checker.getTypeOfSymbol(property), level + 1);
+          visit9(checker.getTypeOfSymbol(property), level + 1);
         for (const kind of [ts4.SignatureKind.Call, ts4.SignatureKind.Construct])
           for (const signature2 of checker.getSignaturesOfType(type, kind)) {
             for (const parameter2 of signature2.getParameters())
-              visit8(checker.getTypeOfSymbol(parameter2), level + 1);
-            visit8(checker.getReturnTypeOfSignature(signature2), level + 1);
+              visit9(checker.getTypeOfSymbol(parameter2), level + 1);
+            visit9(checker.getReturnTypeOfSignature(signature2), level + 1);
           }
       });
     if (type.flags & (ts4.TypeFlags.Union | ts4.TypeFlags.Intersection) && parts.types) {
@@ -9553,7 +10751,7 @@ function reorder(root, print, checker, restore) {
       }
     }
   };
-  visit8(root, 0);
+  visit9(root, 0);
 }
 
 // libs/builder/generator/semantic/angular.ts
@@ -9568,6 +10766,18 @@ function canonicalMembers(type) {
     )
   ).map((member) => wrappers.get(member));
 }
+function playgroundOption(member) {
+  if (member.isEnumLiteral()) {
+    const value = member.getLiteralValue();
+    const name = member.getSymbol()?.getName();
+    if (name && (typeof value === "string" || typeof value === "number"))
+      return { label: name, value };
+  }
+  return member.getText(
+    void 0,
+    TypeFormatFlags2.NoTruncation | TypeFormatFlags2.UseSingleQuotesForStringLiteralType
+  );
+}
 function unwrap(node, seen = /* @__PURE__ */ new Set()) {
   if (!node || seen.has(node)) return void 0;
   seen.add(node);
@@ -9616,31 +10826,49 @@ function literal(node) {
     "Computed controls require the evaluated readGuideValues factory port"
   );
 }
-function controlsToProperties(controls) {
-  return Object.fromEntries(
-    Object.entries(controls).map(([name, value]) => {
-      if (typeof value === "string") {
-        return [name, { inputName: name, type: value, isManual: true }];
-      }
-      if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new SemanticFailure("SEMANTIC_CONTROLS_SHAPE", `Invalid control ${name}`);
-      }
-      const type = value.type;
-      if (typeof type !== "string") {
-        throw new SemanticFailure("SEMANTIC_CONTROLS_SHAPE", `Invalid control ${name}`);
-      }
-      return [
-        name,
-        {
-          inputName: typeof value.alias === "string" ? value.alias : name,
-          type,
-          ...typeof value.description === "string" ? { description: value.description } : {},
-          ...Array.isArray(value.options) && value.options.every((item) => typeof item === "string") ? { options: value.options } : {},
-          isManual: true
-        }
-      ];
-    })
-  );
+function displayFields(value) {
+  return {
+    ...typeof value.label === "string" ? { label: value.label } : {},
+    ...typeof value.group === "string" ? { group: value.group } : {},
+    ...typeof value.order === "number" && Number.isFinite(value.order) ? { order: value.order } : {}
+  };
+}
+function applyControls(properties, controls) {
+  for (const [name, value] of Object.entries(controls)) {
+    if (typeof value === "string") {
+      properties[name] = { inputName: name, type: value, isManual: true };
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new SemanticFailure("SEMANTIC_CONTROLS_SHAPE", `Invalid control ${name}`);
+    }
+    const type = value.type;
+    if (type === void 0) {
+      const detected = properties[name];
+      if (!detected)
+        throw new SemanticFailure(
+          "SEMANTIC_CONTROLS_SHAPE",
+          `Control ${name} has no type, and the target has no input ${name} to keep the control of`
+        );
+      properties[name] = {
+        ...detected,
+        ...typeof value.description === "string" ? { description: value.description } : {},
+        ...displayFields(value)
+      };
+      continue;
+    }
+    if (typeof type !== "string") {
+      throw new SemanticFailure("SEMANTIC_CONTROLS_SHAPE", `Invalid control ${name}`);
+    }
+    properties[name] = {
+      inputName: typeof value.alias === "string" ? value.alias : name,
+      type,
+      ...typeof value.description === "string" ? { description: value.description } : {},
+      ...Array.isArray(value.options) && value.options.every((item) => typeof item === "string") ? { options: value.options } : {},
+      isManual: true,
+      ...displayFields(value)
+    };
+  }
 }
 function assets(target, files, config) {
   return getComponentSourceFiles(target).flatMap((file) => {
@@ -9663,7 +10891,9 @@ function assets(target, files, config) {
       isEmpty: !code,
       lang: title.replace("TypeScript", "angular-ts").replace("HTML", "angular-html")
     };
-    const snippets = snippetsFromAsset(asset, config.inlineStyleLanguage, config.workspaceRoot);
+    const snippets = formatting(
+      () => snippetsFromAsset(asset, config.inlineStyleLanguage, config.workspaceRoot)
+    );
     return (snippets.length ? snippets : [asset]).map((item) => ({
       title: item.title,
       source,
@@ -9750,12 +10980,7 @@ function guideSemantics(source, files, config, docs, values) {
           ),
           description: Node16.isParameterDeclaration(input) ? docs.getJsDocParam(target.getMethodOrThrow("transform"), input.getName()) : docs.getJsDocDescription(input),
           // In the written order: the checker's (stable) order sorts literals by value.
-          options: writtenUnionOrder(input, type, canonicalMembers(type)).map(
-            (part) => part.getText(
-              void 0,
-              TypeFormatFlags2.NoTruncation | TypeFormatFlags2.UseSingleQuotesForStringLiteralType
-            )
-          )
+          options: writtenUnionOrder(input, type, canonicalMembers(type)).map(playgroundOption)
         };
       }
       const controls = evaluated?.playgrounds?.[id]?.controls ?? (expression.getProperty("controls") ? literal(expression.getProperty("controls")) : {});
@@ -9764,7 +10989,7 @@ function guideSemantics(source, files, config, docs, values) {
           "SEMANTIC_CONTROLS_SHAPE",
           `Controls for ${id} must be a JSON object`
         );
-      Object.assign(properties, controlsToProperties(controls));
+      applyControls(properties, controls);
       for (const [key, value] of Object.entries(properties)) {
         if (!value || typeof value !== "object" || typeof value.type !== "string")
           throw new SemanticFailure("SEMANTIC_CONTROLS_SHAPE", `Invalid control ${id}.${key}`);
@@ -10056,9 +11281,9 @@ function enumerateApi(state, entryId, files, diagnostics, context) {
   const result = [];
   const seen = /* @__PURE__ */ new Set();
   for (const scope of entry.scopes)
-    for (const path17 of state.scopes.get(`${entry.id}:${scope.id}`) ?? []) {
-      recordLookup(path17);
-      const source = state.project.getSourceFileOrThrow(path17);
+    for (const path18 of state.scopes.get(`${entry.id}:${scope.id}`) ?? []) {
+      recordLookup(path18);
+      const source = state.project.getSourceFileOrThrow(path18);
       for (const [name, nodes] of source.getExportedDeclarations()) {
         const candidates = nodes.filter(supported);
         if (!candidates.length) {
@@ -10067,7 +11292,7 @@ function enumerateApi(state, entryId, files, diagnostics, context) {
             severity: "info",
             stage: "semantic",
             message: `Skipped unsupported exported declaration ${name}`,
-            source: { path: path17 }
+            source: { path: path18 }
           });
           continue;
         }
@@ -10173,16 +11398,16 @@ var DerivedClassIndex = class {
         referenceNames(expression.expression);
       }
     };
-    const visit8 = (node) => {
+    const visit9 = (node) => {
       if (ts6.isClassDeclaration(node)) {
         for (const clause of node.heritageClauses ?? [])
           if (clause.token === ts6.SyntaxKind.ExtendsKeyword)
             clause.types.forEach((type) => referenceNames(type.expression));
       }
-      ts6.forEachChild(node, visit8);
+      ts6.forEachChild(node, visit9);
     };
     for (const source of program.getSourceFiles())
-      if (source.text.includes("extends")) visit8(source);
+      if (source.text.includes("extends")) visit9(source);
   }
   /** False only when no reference search can find a class deriving from `declaration`. */
   mayHaveDerivedClasses(declaration) {
@@ -10275,7 +11500,7 @@ import { Project as Project3, ts as ts9 } from "ts-morph";
 
 // libs/builder/generator/semantic/owned-roots.ts
 import { minimatch as minimatch2 } from "minimatch";
-import { randomUUID as randomUUID4 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 import { realpathSync as realpathSync3 } from "node:fs";
 import { basename, dirname as dirname3, isAbsolute as isAbsolute2, join as join2, parse as parse3, posix as posix3 } from "node:path";
 import { Project as Project2 } from "ts-morph";
@@ -10291,23 +11516,23 @@ var OwnedRoots = class {
   }
   /** The owned root containing a path, if any. */
   describe(file) {
-    const path17 = normalize2(file);
-    return this.roots.find((root) => path17 === root || path17.startsWith(`${root}/`));
+    const path18 = normalize2(file);
+    return this.roots.find((root) => path18 === root || path18.startsWith(`${root}/`));
   }
   /**
    * A non-owned path that is a symlink into an owned root stays unresolved: it is read through
    * its own path like any other input instead of resolving to a hidden owned file.
    */
-  realpath(path17, resolve10) {
-    const real2 = resolve10(path17);
-    return this.has(real2) && !this.has(path17) ? path17 : real2;
+  realpath(path18, resolve10) {
+    const real2 = resolve10(path18);
+    return this.has(real2) && !this.has(path18) ? path18 : real2;
   }
   /** Notes a raw text read of the program's file system (see {@link contentDigest}). */
   recordRead(file, text) {
-    const path17 = normalize2(file);
+    const path18 = normalize2(file);
     if (text.charCodeAt(0) === 65279)
-      this.marked.set(path17, { text: text.slice(1), digest: contentDigest(text) });
-    else this.marked.delete(path17);
+      this.marked.set(path18, { text: text.slice(1), digest: contentDigest(text) });
+    else this.marked.delete(path18);
   }
   /**
    * The content digest of a program file whose text is `text`. TypeScript drops a leading byte
@@ -10326,8 +11551,8 @@ var OwnedRoots = class {
       fileExists: (file) => !this.has(file) && host.fileExists(file),
       readFile: (file) => this.has(file) ? void 0 : host.readFile(file),
       directoryExists: (directory) => !this.has(directory) && (host.directoryExists?.(directory) ?? true),
-      getDirectories: (path17) => this.has(path17) ? [] : (host.getDirectories?.(path17) ?? []).filter((name) => !this.has(join2(path17, name))),
-      ...host.realpath ? { realpath: (path17) => this.realpath(path17, (value) => host.realpath(value)) } : {}
+      getDirectories: (path18) => this.has(path18) ? [] : (host.getDirectories?.(path18) ?? []).filter((name) => !this.has(join2(path18, name))),
+      ...host.realpath ? { realpath: (path18) => this.realpath(path18, (value) => host.realpath(value)) } : {}
     };
   }
   /** The real ts-morph file system with owned paths absent. Writes are never issued by semantic. */
@@ -10336,13 +11561,13 @@ var OwnedRoots = class {
     return new OwnedRootsFileSystem(realFileSystem(), this);
   }
 };
-function canonical2(path17) {
+function canonical2(path18) {
   const missing = [];
-  for (let cursor = normalize2(path17); ; cursor = dirname3(cursor)) {
+  for (let cursor = normalize2(path18); ; cursor = dirname3(cursor)) {
     try {
       return normalize2(join2(realpathSync3(cursor), ...missing));
     } catch {
-      if (dirname3(cursor) === cursor) return normalize2(path17);
+      if (dirname3(cursor) === cursor) return normalize2(path18);
       missing.unshift(basename(cursor));
     }
   }
@@ -10352,7 +11577,7 @@ var notFound;
 function missingFileError(fileSystem) {
   const probe2 = join2(
     parse3(process.cwd()).root,
-    `ngdoc-owned-root-probe-${randomUUID4()}`,
+    `ngdoc-owned-root-probe-${randomUUID5()}`,
     "missing.ts"
   );
   let observed;
@@ -10370,8 +11595,8 @@ function missingFileError(fileSystem) {
   }
   return type;
 }
-function fileNotFound(path17) {
-  return new notFound(path17);
+function fileNotFound(path18) {
+  return new notFound(path18);
 }
 function realFileSystem() {
   return real ??= new Project2({ useInMemoryFileSystem: false }).getFileSystem();
@@ -10384,11 +11609,11 @@ var OwnedRootsFileSystem = class {
   isCaseSensitive() {
     return this.real.isCaseSensitive();
   }
-  delete(path17) {
-    return this.real.delete(path17);
+  delete(path18) {
+    return this.real.delete(path18);
   }
-  deleteSync(path17) {
-    this.real.deleteSync(path17);
+  deleteSync(path18) {
+    this.real.deleteSync(path18);
   }
   readDirSync(dirPath) {
     if (this.owned.has(dirPath)) return [];
@@ -10444,8 +11669,8 @@ var OwnedRootsFileSystem = class {
   directoryExistsSync(dirPath) {
     return !this.owned.has(dirPath) && this.real.directoryExistsSync(dirPath);
   }
-  realpathSync(path17) {
-    return this.owned.realpath(path17, (value) => this.real.realpathSync(value));
+  realpathSync(path18) {
+    return this.owned.realpath(path18, (value) => this.real.realpathSync(value));
   }
   getCurrentDirectory() {
     return this.real.getCurrentDirectory();
@@ -10483,8 +11708,8 @@ function ownedRootReach(workspaceRoot, include, exclude, roots) {
   const base = normalize2(workspaceRoot);
   const relative3 = (pattern) => posix3.normalize(isAbsolute2(pattern) ? posix3.relative(base, normalize2(pattern)) : pattern);
   const excludes = exclude.map(relative3);
-  const excluded = (path17) => {
-    const parts = path17.split("/");
+  const excluded = (path18) => {
+    const parts = path18.split("/");
     return parts.some((_, index) => {
       const prefix = parts.slice(0, index + 1).join("/");
       return excludes.some((pattern) => minimatch2(prefix, pattern, { dot: true }));
@@ -10537,8 +11762,8 @@ function staticBase(spec) {
   if (index < 0) return { base: spec, rest: [] };
   return { base: parts.slice(0, index).join("/") || "/", rest: parts.slice(index) };
 }
-function inside(root, path17) {
-  return path17 === root || path17.startsWith(root === "/" ? "/" : `${root}/`);
+function inside(root, path18) {
+  return path18 === root || path18.startsWith(root === "/" ? "/" : `${root}/`);
 }
 function literal2(character) {
   if (character === "!" || character === "\\") return "?";
@@ -10582,7 +11807,7 @@ function segmentPattern(segment, caseInsensitive) {
 async function tsconfigMembershipDependencies(parsed, configFile, owned, specs = tsconfigSpecs(parsed, configFile)) {
   const directory = normalize2(dirname4(configFile));
   const caseInsensitive = !ts8.sys.useCaseSensitiveFileNames;
-  const key = (path17) => caseInsensitive ? path17.toLowerCase() : path17;
+  const key = (path18) => caseInsensitive ? path18.toLowerCase() : path18;
   const extensions = [
     "ts",
     "tsx",
@@ -10594,10 +11819,10 @@ async function tsconfigMembershipDependencies(parsed, configFile, owned, specs =
   const dependencies = [];
   const reproduced = /* @__PURE__ */ new Set();
   for (const file of specs.files) {
-    const path17 = normalize2(resolve4(directory, file));
-    if (owned.has(path17)) continue;
-    dependencies.push({ kind: "existence", path: path17, exists: existsSync9(path17) });
-    reproduced.add(key(path17));
+    const path18 = normalize2(resolve4(directory, file));
+    if (owned.has(path18)) continue;
+    dependencies.push({ kind: "existence", path: path18, exists: existsSync9(path18) });
+    reproduced.add(key(path18));
   }
   const globs = /* @__PURE__ */ new Map();
   for (const spec of specs.include) {
@@ -10685,11 +11910,11 @@ async function tsconfigMembershipDependencies(parsed, configFile, owned, specs =
 }
 
 // libs/builder/generator/semantic/program-builder.ts
-function ownedOverlap(kind, path17, owned) {
+function ownedOverlap(kind, path18, owned) {
   return new SemanticFailure(
     "SEMANTIC_OWNED_ROOT_OVERLAP",
-    `${kind} ${path17} lies under a generator-owned output or cache root (${owned.describe(path17)}). Generated output is never documented; configure outputRoot/cacheRoot outside documented sources.`,
-    { path: path17 }
+    `${kind} ${path18} lies under a generator-owned output or cache root (${owned.describe(path18)}). Generated output is never documented; configure outputRoot/cacheRoot outside documented sources.`,
+    { path: path18 }
   );
 }
 var FORMATTER_CONFIGURATION_FILES = [
@@ -10717,9 +11942,9 @@ var FORMATTER_CONFIGURATION_FILES = [
 function trackFormatterConfiguration(workspaceRoot, files) {
   for (let directory = workspaceRoot; ; directory = dirname5(directory)) {
     for (const name of FORMATTER_CONFIGURATION_FILES) {
-      const path17 = normalize2(resolve5(directory, name));
-      files.add({ kind: "existence", path: path17, exists: existsSync10(path17) });
-      if (existsSync10(path17)) files.read(path17);
+      const path18 = normalize2(resolve5(directory, name));
+      files.add({ kind: "existence", path: path18, exists: existsSync10(path18) });
+      if (existsSync10(path18)) files.read(path18);
     }
     if (dirname5(directory) === directory) break;
   }
@@ -10831,9 +12056,9 @@ function syntaxFailure(program) {
 import { existsSync as existsSync11 } from "node:fs";
 import { dirname as dirname6, resolve as resolve6 } from "node:path";
 import { ts as ts10 } from "ts-morph";
-function realpathOf(path17) {
+function realpathOf(path18) {
   try {
-    return ts10.sys.realpath ? ts10.sys.realpath(path17) : path17;
+    return ts10.sys.realpath ? ts10.sys.realpath(path18) : path18;
   } catch {
     return void 0;
   }
@@ -10842,9 +12067,9 @@ function trackingHost(files, owned, probes) {
   return owned.resolutionHost({
     ...ts10.sys,
     fileExists: (file) => {
-      const path17 = normalize2(file);
-      const exists = existsSync11(path17);
-      files.add({ kind: "existence", path: path17, exists });
+      const path18 = normalize2(file);
+      const exists = existsSync11(path18);
+      files.add({ kind: "existence", path: path18, exists });
       return exists;
     },
     readFile: (file) => {
@@ -10859,9 +12084,9 @@ function trackingHost(files, owned, probes) {
       if (!exists) probes?.missing(normalize2(directory));
       return exists;
     },
-    realpath: (path17) => {
-      const real2 = realpathOf(path17) ?? path17;
-      const from = normalize2(path17);
+    realpath: (path18) => {
+      const real2 = realpathOf(path18) ?? path18;
+      const from = normalize2(path18);
       const to = normalize2(real2);
       if (probes && from !== to) probes.realpath(from, to);
       return real2;
@@ -10869,29 +12094,29 @@ function trackingHost(files, owned, probes) {
   });
 }
 function trackSourceFile(source, options, host, files, owned, imports) {
-  const path17 = normalize2(source.fileName);
-  files.add({ kind: "existence", path: path17, exists: true });
-  files.add({ kind: "content", path: path17, digest: owned.contentDigest(path17, source.text) });
+  const path18 = normalize2(source.fileName);
+  files.add({ kind: "existence", path: path18, exists: true });
+  files.add({ kind: "content", path: path18, digest: owned.contentDigest(path18, source.text) });
   const references2 = ts10.preProcessFile(source.text);
   for (const item of references2.importedFiles) {
-    const resolved = ts10.resolveModuleName(item.fileName, path17, options, host).resolvedModule;
+    const resolved = ts10.resolveModuleName(item.fileName, path18, options, host).resolvedModule;
     imports?.push(resolution("module", item.fileName, resolved?.resolvedFileName));
   }
   for (const item of references2.typeReferenceDirectives) {
     const resolved = ts10.resolveTypeReferenceDirective(
       item.fileName,
-      path17,
+      path18,
       options,
       host
     ).resolvedTypeReferenceDirective;
     imports?.push(resolution("type-reference", item.fileName, resolved?.resolvedFileName));
   }
   for (const item of references2.referencedFiles) {
-    const path18 = normalize2(resolve6(dirname6(source.fileName), item.fileName));
-    if (owned.has(path18)) continue;
-    const exists = existsSync11(path18);
-    files.add({ kind: "existence", path: path18, exists });
-    imports?.push(resolution("reference", item.fileName, exists ? path18 : void 0));
+    const path19 = normalize2(resolve6(dirname6(source.fileName), item.fileName));
+    if (owned.has(path19)) continue;
+    const exists = existsSync11(path19);
+    files.add({ kind: "existence", path: path19, exists });
+    imports?.push(resolution("reference", item.fileName, exists ? path19 : void 0));
   }
 }
 function resolution(kind, specifier, resolved) {
@@ -10914,14 +12139,14 @@ function semanticDefinition(configuration, files, project) {
     reason: "Whole TypeScript program, configuration, resolution libraries and source membership conservatively invalidate semantic consumers"
   };
 }
-function rawDigest(path17) {
+function rawDigest(path18) {
   try {
-    return readText(path17).digest;
+    return readText(path18).digest;
   } catch (error) {
     throw new SemanticFailure(
       "SEMANTIC_RETRACK",
-      `${path17} cannot be read again: ${error instanceof Error ? error.message : String(error)}`,
-      { path: path17 }
+      `${path18} cannot be read again: ${error instanceof Error ? error.message : String(error)}`,
+      { path: path18 }
     );
   }
 }
@@ -10961,9 +12186,9 @@ var ProgramObservations = class {
     const options = project.getCompilerOptions();
     const host = trackingHost(this.aggregate, owned, this.probeSink);
     for (const source of project.getProgram().compilerObject.getSourceFiles()) {
-      const path17 = normalize2(source.fileName);
-      if (owned.has(path17)) continue;
-      const segment = this.open(path17);
+      const path18 = normalize2(source.fileName);
+      if (owned.has(path18)) continue;
+      const segment = this.open(path18);
       try {
         trackSourceFile(source, options, host, this.aggregate, owned, segment.imports);
       } finally {
@@ -10990,8 +12215,8 @@ var ProgramObservations = class {
     return [...this.importerSegments.keys()];
   }
   /** What tracking one program file observed, or undefined when it is not a tracked importer. */
-  importer(path17) {
-    const segment = this.importerSegments.get(normalize2(path17));
+  importer(path18) {
+    const segment = this.importerSegments.get(normalize2(path18));
     return segment ? {
       path: segment.owner,
       dependencies: segment.dependencies,
@@ -11001,7 +12226,7 @@ var ProgramObservations = class {
     } : void 0;
   }
   /** The tracked program files with a reference that resolved to this file, in program order. */
-  importersOf(path17) {
+  importersOf(path18) {
     if (!this.reverse) {
       this.reverse = /* @__PURE__ */ new Map();
       for (const [importer, segment] of this.importerSegments)
@@ -11012,7 +12237,7 @@ var ProgramObservations = class {
           this.reverse.set(item, list);
         }
     }
-    return [...this.reverse.get(normalize2(path17)) ?? []];
+    return [...this.reverse.get(normalize2(path18)) ?? []];
   }
   /**
    * The aggregate replayed from the attribution log: every observation (without the definition),
@@ -11062,14 +12287,14 @@ var ProgramObservations = class {
     const options = project.getCompilerOptions();
     const retracked = [];
     const targets = new Set([...paths].map(normalize2));
-    for (const path17 of targets) {
-      const segment = this.importerSegments.get(path17);
-      const source = segment ? program.getSourceFile(path17) : void 0;
+    for (const path18 of targets) {
+      const segment = this.importerSegments.get(path18);
+      const source = segment ? program.getSourceFile(path18) : void 0;
       if (!segment || !source)
         throw new SemanticFailure(
           "SEMANTIC_RETRACK",
-          `${path17} is not a tracked file of the current program`,
-          { path: path17 }
+          `${path18} is not a tracked file of the current program`,
+          { path: path18 }
         );
       segment.dependencies = [];
       segment.missing = [];
@@ -11139,16 +12364,16 @@ var ProgramObservations = class {
     this.importerSegments.clear();
     const tracked = [];
     for (const source of program.getSourceFiles()) {
-      const path17 = normalize2(source.fileName);
-      if (owned.has(path17)) continue;
-      const kept2 = previous.get(path17);
-      if (kept2 && keep(path17)) {
+      const path18 = normalize2(source.fileName);
+      if (owned.has(path18)) continue;
+      const kept2 = previous.get(path18);
+      if (kept2 && keep(path18)) {
         segments.push(kept2);
-        this.importerSegments.set(path17, kept2);
+        this.importerSegments.set(path18, kept2);
         continue;
       }
       const segment = {
-        owner: path17,
+        owner: path18,
         dependencies: [],
         missing: [],
         realpaths: [],
@@ -11162,7 +12387,7 @@ var ProgramObservations = class {
       trackSourceFile(source, options, host, files2, owned, segment.imports);
       tracked.push(...segment.dependencies);
       segments.push(segment);
-      this.importerSegments.set(path17, segment);
+      this.importerSegments.set(path18, segment);
     }
     segments.push(...tail);
     this.segments.splice(0, this.segments.length, ...segments);
@@ -11183,16 +12408,16 @@ var ProgramObservations = class {
         this.segment().dependencies.push(dependency);
     });
   }
-  open(path17) {
+  open(path18) {
     const segment = {
-      owner: path17,
+      owner: path18,
       dependencies: [],
       missing: [],
       realpaths: [],
       imports: []
     };
     this.segments.push(segment);
-    this.importerSegments.set(path17, segment);
+    this.importerSegments.set(path18, segment);
     this.current = segment;
     return segment;
   }
@@ -11283,7 +12508,7 @@ function watchProgram(project, observations, owned, tsConfig, observedAtNs) {
   const published = observations.files.all();
   for (const dependency of published)
     if (dependency.kind === "glob")
-      listings.recordGlob(dependency, observedAtNs, (path17) => owned.has(path17));
+      listings.recordGlob(dependency, observedAtNs, (path18) => owned.has(path18));
   const stamps = new ObservationStamps((file) => readText(file).digest);
   stamps.record([...published, ...hidden.all()], observedAtNs);
   const probes = observations.probes;
@@ -11301,16 +12526,16 @@ function watchFacts(watch) {
   return {
     hidden: watch.hidden.all(),
     missingDirectories: [...watch.missingDirectories],
-    realpaths: watch.realpaths.map(([path17, real2]) => [path17, real2]),
+    realpaths: watch.realpaths.map(([path18, real2]) => [path18, real2]),
     directories
   };
 }
 function watchFactsChange(facts) {
   for (const directory of facts.missingDirectories)
     if (ts12.sys.directoryExists(directory)) return `directory appeared: ${directory}`;
-  for (const [path17, real2] of facts.realpaths) {
-    const current = realpathOf(path17);
-    if (current === void 0 || normalize2(current) !== real2) return `symlink retargeted: ${path17}`;
+  for (const [path18, real2] of facts.realpaths) {
+    const current2 = realpathOf(path18);
+    if (current2 === void 0 || normalize2(current2) !== real2) return `symlink retargeted: ${path18}`;
   }
   for (const directory of facts.directories)
     if (!directoryListed(directory)) return `directory listing changed: ${directory.path}`;
@@ -11361,9 +12586,9 @@ function assessPatch(previous, changes) {
     rehashed += sweep2.rehashed;
     if (sweep2.changed) edited.add(dependency.path);
   }
-  for (const path17 of edited)
-    if (!importers.has(path17))
-      return { kind: "full", reason: `patched path is not a program file: ${path17}` };
+  for (const path18 of edited)
+    if (!importers.has(path18))
+      return { kind: "full", reason: `patched path is not a program file: ${path18}` };
   if (edited.size > MAX_PATCHED_FILES)
     return {
       kind: "full",
@@ -11373,8 +12598,8 @@ function assessPatch(previous, changes) {
     (dependency) => !(dependency.kind === "content" && importers.has(dependency.path))
   );
   const unexplained = changes.filter((change) => {
-    const path17 = normalize2(change.path);
-    return !importers.has(path17) || !existsSync12(path17);
+    const path18 = normalize2(change.path);
+    return !importers.has(path18) || !existsSync12(path18);
   });
   const verified = holds2(watch, rest, unexplained);
   if (typeof verified === "string") return { kind: "full", reason: verified };
@@ -11383,7 +12608,7 @@ function assessPatch(previous, changes) {
     stamped: verified.stamped + stamped,
     rehashed: verified.rehashed + rehashed
   };
-  return edited.size ? { kind: "patch", files: order.filter((path17) => edited.has(path17)), counters: counters2 } : { kind: "reuse", counters: counters2 };
+  return edited.size ? { kind: "patch", files: order.filter((path18) => edited.has(path18)), counters: counters2 } : { kind: "reuse", counters: counters2 };
 }
 function assessRestructure(previous, changes, discovery) {
   const { watch, mirror } = previous;
@@ -11398,42 +12623,42 @@ function assessRestructure(previous, changes, discovery) {
   const deleted = /* @__PURE__ */ new Set();
   let stamped = 0;
   let rehashed = 0;
-  for (const path17 of layout.importers) {
-    const own = observations.importer(path17).dependencies.filter(
-      (dependency) => dependency.kind === "content" && dependency.path === path17
+  for (const path18 of layout.importers) {
+    const own = observations.importer(path18).dependencies.filter(
+      (dependency) => dependency.kind === "content" && dependency.path === path18
     );
     const sweep2 = watch.stamps.sweep(own);
     stamped += sweep2.stamped;
     rehashed += sweep2.rehashed;
     if (!sweep2.changed) continue;
-    if (existsSync12(path17)) edited.add(path17);
-    else deleted.add(path17);
+    if (existsSync12(path18)) edited.add(path18);
+    else deleted.add(path18);
   }
-  for (const path17 of edited)
-    if (!importers.has(path17))
-      return { kind: "full", reason: `patched path is not a program file: ${path17}` };
+  for (const path18 of edited)
+    if (!importers.has(path18))
+      return { kind: "full", reason: `patched path is not a program file: ${path18}` };
   if (edited.size + deleted.size > MAX_PATCHED_FILES)
     return {
       kind: "full",
       reason: `${edited.size + deleted.size} program files changed (at most ${MAX_PATCHED_FILES} are patched)`
     };
   const retracked = /* @__PURE__ */ new Set([...edited, ...deleted]);
-  const kept2 = layout.importers.filter((path17) => !retracked.has(path17));
+  const kept2 = layout.importers.filter((path18) => !retracked.has(path18));
   const rest = [
     // The program configuration (entry modules are read again with the membership).
     ...layout.membership.filter(
       (dependency) => (dependency.kind === "content" || dependency.kind === "existence") && !entries.has(normalize2(dependency.path))
     ),
-    ...kept2.flatMap((path17) => observations.importer(path17).dependencies),
+    ...kept2.flatMap((path18) => observations.importer(path18).dependencies),
     ...layout.tail,
     ...watch.hidden.all()
   ];
   const missing = [
-    ...kept2.flatMap((path17) => observations.importer(path17).missing),
+    ...kept2.flatMap((path18) => observations.importer(path18).missing),
     ...layout.tailMissing
   ];
   const realpaths = [
-    ...kept2.flatMap((path17) => observations.importer(path17).realpaths),
+    ...kept2.flatMap((path18) => observations.importer(path18).realpaths),
     ...layout.tailRealpaths
   ];
   const unexplained = changes.filter((change) => !edited.has(normalize2(change.path)));
@@ -11445,7 +12670,7 @@ function assessRestructure(previous, changes, discovery) {
   if (typeof verified === "string") return { kind: "full", reason: verified };
   return {
     kind: "patch",
-    files: layout.importers.filter((path17) => edited.has(path17)),
+    files: layout.importers.filter((path18) => edited.has(path18)),
     counters: {
       ...verified,
       stamped: verified.stamped + stamped,
@@ -11464,7 +12689,7 @@ function keyConfiguration(key) {
 function entryPaths(key) {
   try {
     const [, entries] = JSON.parse(key);
-    return entries.map(([, , path17]) => normalize2(path17));
+    return entries.map(([, , path18]) => normalize2(path18));
   } catch {
     return [];
   }
@@ -11484,9 +12709,9 @@ function holds2(watch, observations, changes, probes = {
   if (sweep2.changed) return `${sweep2.changed.kind} observation changed: ${sweep2.changed.path}`;
   for (const directory of probes.missing)
     if (ts12.sys.directoryExists(directory)) return `directory appeared: ${directory}`;
-  for (const [path17, real2] of probes.realpaths) {
-    const current = realpathOf(path17);
-    if (current === void 0 || normalize2(current) !== real2) return `symlink retargeted: ${path17}`;
+  for (const [path18, real2] of probes.realpaths) {
+    const current2 = realpathOf(path18);
+    if (current2 === void 0 || normalize2(current2) !== real2) return `symlink retargeted: ${path18}`;
   }
   const directories = probes.listings.sweep();
   if (directories.changed) return `directory listing changed: ${directories.changed}`;
@@ -11514,29 +12739,29 @@ async function patchProgram(previous, assessment, discovery) {
   const order = before.getSourceFiles().map((source) => source.fileName);
   const observedAtNs = observationClockNs();
   const plans = [];
-  for (const path17 of files) {
-    const source = project.getSourceFile(path17);
-    const importer = mirror.observations.importer(path17);
+  for (const path18 of files) {
+    const source = project.getSourceFile(path18);
+    const importer = mirror.observations.importer(path18);
     if (!source || !importer)
-      return { kind: "refused", reason: `${path17} is not a file of the retained program` };
+      return { kind: "refused", reason: `${path18} is not a file of the retained program` };
     const compiled = source.compilerNode;
     if (compiled.isDeclarationFile || before.isSourceFileDefaultLibrary(compiled) || before.isSourceFileFromExternalLibrary(compiled))
-      return { kind: "refused", reason: `${path17} is a declaration or library file` };
+      return { kind: "refused", reason: `${path18} is a declaration or library file` };
     let raw;
     try {
-      raw = readText(path17);
+      raw = readText(path18);
     } catch (error) {
       return {
         kind: "refused",
-        reason: `${path17} cannot be read: ${error instanceof Error ? error.message : String(error)}`
+        reason: `${path18} cannot be read: ${error instanceof Error ? error.message : String(error)}`
       };
     }
     const text = raw.text.charCodeAt(0) === 65279 ? raw.text.slice(1) : raw.text;
-    const reason = patchable(path17, compiled.text, "before") ?? patchable(path17, text, "after");
-    if (reason) return { kind: "refused", reason: `${path17}: ${reason}` };
-    if (references(path17, compiled.text) !== references(path17, text))
-      return discovery ? restructureProgram(previous, files, discovery) : { kind: "refused", reason: `${path17}: its imports, directives or pragmas changed` };
-    plans.push({ path: path17, source, raw, text, before: comparable(importer) });
+    const reason = patchable(path18, compiled.text, "before") ?? patchable(path18, text, "after");
+    if (reason) return { kind: "refused", reason: `${path18}: ${reason}` };
+    if (references(path18, compiled.text) !== references(path18, text))
+      return discovery ? restructureProgram(previous, files, discovery) : { kind: "refused", reason: `${path18}: its imports, directives or pragmas changed` };
+    plans.push({ path: path18, source, raw, text, before: comparable(importer) });
   }
   for (const plan of plans) mirror.appliedSinceBase.set(plan.path, plan.raw.digest);
   mirror.version += 1;
@@ -11602,7 +12827,7 @@ async function restructureProgram(previous, edited, discovery) {
   if (!sameList(parentMost(roots), parentMost(mirror.roots)))
     return { kind: "refused", reason: "the members' parent-most folders changed" };
   const importers = new Set(mirror.observations.importers());
-  const deleted = [...importers].filter((path17) => !existsSync12(path17));
+  const deleted = [...importers].filter((path18) => !existsSync12(path18));
   const added = roots.filter((root) => !importers.has(normalize2(root)));
   if (edited.length + deleted.length + added.length > MAX_PATCHED_FILES)
     return {
@@ -11611,50 +12836,50 @@ async function restructureProgram(previous, edited, discovery) {
     };
   const compiled = project.getProgram().compilerObject;
   const plans = [];
-  for (const path17 of edited) {
-    const source = project.getSourceFile(path17);
-    const importer = mirror.observations.importer(path17);
+  for (const path18 of edited) {
+    const source = project.getSourceFile(path18);
+    const importer = mirror.observations.importer(path18);
     if (!source || !importer)
-      return { kind: "refused", reason: `${path17} is not a file of the retained program` };
+      return { kind: "refused", reason: `${path18} is not a file of the retained program` };
     if (source.compilerNode.isDeclarationFile || compiled.isSourceFileDefaultLibrary(source.compilerNode) || compiled.isSourceFileFromExternalLibrary(source.compilerNode))
-      return { kind: "refused", reason: `${path17} is a declaration or library file` };
+      return { kind: "refused", reason: `${path18} is a declaration or library file` };
     let raw;
     try {
-      raw = readText(path17);
+      raw = readText(path18);
     } catch (error) {
       return {
         kind: "refused",
-        reason: `${path17} cannot be read: ${error instanceof Error ? error.message : String(error)}`
+        reason: `${path18} cannot be read: ${error instanceof Error ? error.message : String(error)}`
       };
     }
     const text = raw.text.charCodeAt(0) === 65279 ? raw.text.slice(1) : raw.text;
-    const reason = patchable(path17, source.compilerNode.text, "before") ?? patchable(path17, text, "after");
-    if (reason) return { kind: "refused", reason: `${path17}: ${reason}` };
-    plans.push({ path: path17, source, raw, text, before: comparable(importer) });
+    const reason = patchable(path18, source.compilerNode.text, "before") ?? patchable(path18, text, "after");
+    if (reason) return { kind: "refused", reason: `${path18}: ${reason}` };
+    plans.push({ path: path18, source, raw, text, before: comparable(importer) });
   }
-  for (const path17 of deleted) {
-    const source = project.getSourceFile(path17);
-    const reason = source ? patchable(path17, source.compilerNode.text, "before") : void 0;
-    if (reason) return { kind: "refused", reason: `deleted ${path17}: ${reason}` };
+  for (const path18 of deleted) {
+    const source = project.getSourceFile(path18);
+    const reason = source ? patchable(path18, source.compilerNode.text, "before") : void 0;
+    if (reason) return { kind: "refused", reason: `deleted ${path18}: ${reason}` };
   }
-  for (const path17 of added) {
+  for (const path18 of added) {
     let text;
     try {
-      text = readText(path17).text;
+      text = readText(path18).text;
     } catch (error) {
       return {
         kind: "refused",
-        reason: `${path17} cannot be read: ${error instanceof Error ? error.message : String(error)}`
+        reason: `${path18} cannot be read: ${error instanceof Error ? error.message : String(error)}`
       };
     }
-    const reason = patchable(path17, text.charCodeAt(0) === 65279 ? text.slice(1) : text, "after");
-    if (reason) return { kind: "refused", reason: `new ${path17}: ${reason}` };
+    const reason = patchable(path18, text.charCodeAt(0) === 65279 ? text.slice(1) : text, "after");
+    if (reason) return { kind: "refused", reason: `new ${path18}: ${reason}` };
   }
   for (const plan of plans) mirror.appliedSinceBase.set(plan.path, plan.raw.digest);
   mirror.version += 1;
   let after;
   const unchanged = new Set(
-    [...importers].filter((path17) => !plans.some((plan) => plan.path === path17) && existsSync12(path17))
+    [...importers].filter((path18) => !plans.some((plan) => plan.path === path18) && existsSync12(path18))
   );
   withPinnedRoots(
     wrapper,
@@ -11664,13 +12889,13 @@ async function restructureProgram(previous, edited, discovery) {
         owned.recordRead(plan.path, plan.raw.text);
         if (plan.source.getFullText() !== plan.text) replaceSource(factory, plan.source, plan.text);
       }
-      for (const path17 of deleted) cache.get(path17)?.forget();
+      for (const path18 of deleted) cache.get(path18)?.forget();
       for (const root of added) project.addSourceFileAtPath(root);
       project.resolveSourceFileDependencies();
       const files2 = new Set(
         project.getProgram().compilerObject.getSourceFiles().map((source) => source.fileName)
       );
-      for (const path17 of [...cache.paths()]) if (!files2.has(path17)) cache.get(path17)?.forget();
+      for (const path18 of [...cache.paths()]) if (!files2.has(path18)) cache.get(path18)?.forget();
       after = project.getProgram().compilerObject;
     },
     (host) => reusingResolutions(host, compiled, unchanged, project.getCompilerOptions())
@@ -11678,7 +12903,7 @@ async function restructureProgram(previous, edited, discovery) {
   if (!sameList(after.getRootFileNames(), roots))
     return { kind: "refused", reason: "the restructured program has other root files" };
   const files = new Set(after.getSourceFiles().map((source) => normalize2(source.fileName)));
-  const gone = deleted.find((path17) => files.has(path17));
+  const gone = deleted.find((path18) => files.has(path18));
   if (gone) return { kind: "refused", reason: `the deleted ${gone} is still a program file` };
   const failure2 = syntaxFailure(after);
   if (failure2) return { kind: "refused", reason: `syntax errors: ${failure2.message}` };
@@ -11687,7 +12912,7 @@ async function restructureProgram(previous, edited, discovery) {
     project,
     owned,
     membership,
-    (path17) => !retracked.has(path17) && existsSync12(path17)
+    (path18) => !retracked.has(path18) && existsSync12(path18)
   );
   const watch = mirror.watch;
   watch.stamps.record(tracked, observedAtNs);
@@ -11697,7 +12922,7 @@ async function restructureProgram(previous, edited, discovery) {
   const listings = watch.listings.withoutGlobs();
   for (const dependency of mirror.observations.files.all())
     if (dependency.kind === "glob")
-      listings.recordGlob(dependency, observedAtNs, (path17) => owned.has(path17));
+      listings.recordGlob(dependency, observedAtNs, (path18) => owned.has(path18));
   watch.listings = listings;
   mirror.roots = roots;
   previous.scopes.clear();
@@ -11759,7 +12984,7 @@ function sourceCache(project) {
     return void 0;
   return {
     paths: () => [...factory.getSourceFilePaths()],
-    get: (path17) => factory.getSourceFileFromCacheFromFilePath(fileSystem.getStandardizedAbsolutePath(path17)),
+    get: (path18) => factory.getSourceFileFromCacheFromFilePath(fileSystem.getStandardizedAbsolutePath(path18)),
     fileSystem: { globSync: (patterns) => fileSystem.globSync(patterns) }
   };
 }
@@ -11789,11 +13014,11 @@ function withPinnedRoots(program, roots, action, hostFor = (host) => host) {
 }
 var TYPESCRIPT_SOURCE = /\.(?:[cm]?ts|tsx)$/;
 var DECLARATION = /\.d\.(?:[^/]*\.)?[cm]?ts$/;
-function patchable(path17, text, when) {
-  if (!TYPESCRIPT_SOURCE.test(path17) || DECLARATION.test(path17))
+function patchable(path18, text, when) {
+  if (!TYPESCRIPT_SOURCE.test(path18) || DECLARATION.test(path18))
     return "not a TypeScript source file";
-  if (path17.includes("/node_modules/")) return "a library file";
-  const source = ts12.createSourceFile(path17, text, ts12.ScriptTarget.Latest, false);
+  if (path18.includes("/node_modules/")) return "a library file";
+  const source = ts12.createSourceFile(path18, text, ts12.ScriptTarget.Latest, false);
   if (!ts12.isExternalModule(source)) return `a script ${when} the edit`;
   for (const statement of source.statements) {
     if (ts12.isModuleDeclaration(statement) && (ts12.isStringLiteral(statement.name) || (statement.flags & ts12.NodeFlags.GlobalAugmentation) !== 0))
@@ -11802,9 +13027,9 @@ function patchable(path17, text, when) {
   }
   return void 0;
 }
-function references(path17, text) {
+function references(path18, text) {
   const info = ts12.preProcessFile(text, true, true);
-  const pragmas = ts12.createSourceFile(path17, text, ts12.ScriptTarget.Latest, false).pragmas;
+  const pragmas = ts12.createSourceFile(path18, text, ts12.ScriptTarget.Latest, false).pragmas;
   const argumentsOf = (value) => Array.isArray(value) ? value.map(argumentsOf) : value?.arguments ?? null;
   return JSON.stringify([
     [...pragmas ?? /* @__PURE__ */ new Map()].map(([name, value]) => [name, argumentsOf(value)]),
@@ -12585,12 +13810,12 @@ function createJsDoc(markdown) {
     const original = comment?.getStructure().tags ?? [];
     if (!comment || !comment.getText().includes("```")) return original;
     const ranges = [];
-    const visit8 = (node2) => {
+    const visit9 = (node2) => {
       if (node2 instanceof DocExcerpt && node2.excerptKind === ExcerptKind.FencedCode_Code)
         ranges.push(node2.content.getContainingTextRange());
-      node2.getChildNodes().forEach(visit8);
+      node2.getChildNodes().forEach(visit9);
     };
-    visit8(new TSDocParser().parseString(comment.getText().replace(/@/g, "a")).docComment);
+    visit9(new TSDocParser().parseString(comment.getText().replace(/@/g, "a")).docComment);
     const nativeTags = comment.getTags();
     const validTags = nativeTags.filter((tag) => {
       const start = tag.getStart() - comment.getStart();
@@ -12631,10 +13856,10 @@ function createJsDoc(markdown) {
 }
 var { compiler: nunjucksCompiler2, lib: nunjucksLib2 } = nunjucks2;
 var compiledTemplates = /* @__PURE__ */ new Map();
-function compiledSource(path17, text, environment) {
+function compiledSource(path18, text, environment) {
   const cacheable = !environment.extensionsList.length;
   const key = JSON.stringify([text, environment.asyncFilters, environment.opts]);
-  const cached = compiledTemplates.get(path17);
+  const cached = compiledTemplates.get(path18);
   if (cacheable && cached?.key === key) return { type: "code", obj: cached.code };
   let code;
   try {
@@ -12644,15 +13869,15 @@ function compiledSource(path17, text, environment) {
         text,
         environment.asyncFilters,
         environment.extensionsList,
-        path17,
+        path18,
         environment.opts
       )
     )();
   } catch (error) {
-    compiledTemplates.delete(path17);
-    throw nunjucksLib2._prettifyError(path17, environment.opts.dev, error);
+    compiledTemplates.delete(path18);
+    throw nunjucksLib2._prettifyError(path18, environment.opts.dev, error);
   }
-  if (cacheable) compiledTemplates.set(path17, { key, code });
+  if (cacheable) compiledTemplates.set(path18, { key, code });
   return { type: "code", obj: code };
 }
 function signalMember(node) {
@@ -12666,10 +13891,10 @@ function signalMember(node) {
 function renderApiTemplate(template, context, root, files, markdown, configDirectory) {
   class TrackedLoader extends Loader2 {
     getSource(name) {
-      const path17 = hostPath(resolve7(root, name));
-      const text = files.read(path17);
-      const src = compiledSource(path17, text, environment);
-      return { src, path: path17, noCache: true };
+      const path18 = hostPath(resolve7(root, name));
+      const text = files.read(path18);
+      const src = compiledSource(path18, text, environment);
+      return { src, path: path18, noCache: true };
     }
   }
   const docs = createJsDoc(markdown);
@@ -12736,17 +13961,17 @@ function requestedDeclaration(state, request, files, context) {
   const [file, name, extra] = request.declarationPath.split("#");
   if (!file || !name || extra)
     throw new SemanticFailure("SEMANTIC_DECLARATION_PATH", "Expected path/to/file.ts#exportName");
-  const path17 = normalize2(resolve8(state.discovery.configuration.workspaceRoot, file));
-  if (state.owned.has(path17)) throw ownedOverlap("API declaration path", path17, state.owned);
-  files.read(path17);
-  recordLookup(path17);
-  let source = state.project.getSourceFile(path17);
+  const path18 = normalize2(resolve8(state.discovery.configuration.workspaceRoot, file));
+  if (state.owned.has(path18)) throw ownedOverlap("API declaration path", path18, state.owned);
+  files.read(path18);
+  recordLookup(path18);
+  let source = state.project.getSourceFile(path18);
   const added = !source;
   if (!source) {
     state.mutated = true;
     const project = state.project;
-    source = withRootsAppended(project, path17, () => {
-      const added2 = project.addSourceFileAtPath(path17);
+    source = withRootsAppended(project, path18, () => {
+      const added2 = project.addSourceFileAtPath(path18);
       project.resolveSourceFileDependencies();
       return added2;
     });
@@ -12759,7 +13984,7 @@ function requestedDeclaration(state, request, files, context) {
     throw new SemanticFailure(
       "SEMANTIC_DECLARATION_MISSING",
       `Cannot resolve exported declaration ${request.declarationPath}`,
-      { path: path17 }
+      { path: path18 }
     );
   return { node: declaration };
 }
@@ -12793,25 +14018,29 @@ function renderFragment(state, request, files, context) {
   const html = withIndexedDerivedClasses(
     node,
     state.project,
-    () => renderApiTemplate(
-      template,
-      {
-        declaration: node,
-        docNode: documented,
-        templateName: kind,
-        scope,
-        ...request.kind === "api" ? {
-          hideDescription: true,
-          hideSeeAlso: true,
-          hideUsageNotes: true,
-          hideRemarks: true,
-          hideExamples: true
-        } : {}
-      },
-      context.templateRoot(),
-      files,
-      (text) => context.markdown(text, source, files),
-      state.discovery.configuration.workspaceRoot
+    () => formatting(
+      () => renderApiTemplate(
+        template,
+        {
+          declaration: node,
+          docNode: documented,
+          templateName: kind,
+          scope,
+          // The legacy engine passes no such flag, so the shared templates keep protected members.
+          hideProtectedMembers: state.discovery.configuration.apiProtectedMembers === false,
+          ...request.kind === "api" ? {
+            hideDescription: true,
+            hideSeeAlso: true,
+            hideUsageNotes: true,
+            hideRemarks: true,
+            hideExamples: true
+          } : {}
+        },
+        context.templateRoot(),
+        files,
+        (text) => context.markdown(text, source, files),
+        state.discovery.configuration.workspaceRoot
+      )
     )
   );
   return {
@@ -12834,10 +14063,10 @@ function trackWholeProgram(state, files, context) {
   }
   for (const dependency of state.tracked.dependencies) files.add(dependency);
 }
-function withRootsAppended(project, path17, add) {
+function withRootsAppended(project, path18, add) {
   const program = project.getProgram();
   if (typeof program._reset !== "function") return add();
-  const roots = [...project.getProgram().compilerObject.getRootFileNames(), path17];
+  const roots = [...project.getProgram().compilerObject.getRootFileNames(), path18];
   let added;
   withPinnedRoots(program, roots, () => {
     added = add();
@@ -13036,8 +14265,8 @@ var ProgramIndex = class {
     let value = this.stars.get(file);
     if (value === void 0) {
       const found = /* @__PURE__ */ new Set();
-      const visit8 = (current) => {
-        const source = this.program.getSourceFile(current);
+      const visit9 = (current2) => {
+        const source = this.program.getSourceFile(current2);
         if (!source) return;
         for (const statement of source.statements) {
           if (!ts13.isExportDeclaration(statement) || statement.exportClause || !statement.moduleSpecifier || !ts13.isStringLiteralLike(statement.moduleSpecifier))
@@ -13045,11 +14274,11 @@ var ProgramIndex = class {
           for (const target of this.moduleFiles(statement.moduleSpecifier, source)) {
             if (found.has(target)) continue;
             found.add(target);
-            visit8(target);
+            visit9(target);
           }
         }
       };
-      visit8(file);
+      visit9(file);
       value = [...found].sort(compare);
       this.stars.set(file, value);
     }
@@ -13347,12 +14576,12 @@ function isolatedShape(source, options) {
   });
   if (emitted.diagnostics?.length) return void 0;
   const enums = [];
-  const visit8 = (node) => {
+  const visit9 = (node) => {
     if (ts13.isEnumDeclaration(node))
       enums.push(printer.printNode(ts13.EmitHint.Unspecified, node, source));
-    else ts13.forEachChild(node, visit8);
+    else ts13.forEachChild(node, visit9);
   };
-  visit8(source);
+  visit9(source);
   return hash2("dts-shape-v1", "dts", emitted.outputText, enums);
 }
 function printedToken(source) {
@@ -14099,19 +15328,19 @@ async function patchMismatch(patched, result, discovery, signal) {
 
 // libs/builder/generator/compiler/assemble.ts
 import { existsSync as existsSync16 } from "node:fs";
-import path16 from "node:path";
+import path17 from "node:path";
 
 // libs/builder/generator/compiler/plan.ts
-import { randomUUID as randomUUID7 } from "node:crypto";
+import { randomUUID as randomUUID8 } from "node:crypto";
 import { existsSync as existsSync13 } from "node:fs";
-import { mkdir as mkdir5, readFile as readFile4, rename as rename6, rm as rm6, writeFile as writeFile6 } from "node:fs/promises";
-import path14 from "node:path";
+import { mkdir as mkdir6, readFile as readFile4, rename as rename7, rm as rm7, writeFile as writeFile7 } from "node:fs/promises";
+import path15 from "node:path";
 
 // libs/builder/generator/compiler/fast-start.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
-import { readFileSync as readFileSync8 } from "node:fs";
-import { mkdir as mkdir4, rename as rename4, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
-import path12 from "node:path";
+import { randomUUID as randomUUID6 } from "node:crypto";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { mkdir as mkdir5, rename as rename5, rm as rm5, writeFile as writeFile5 } from "node:fs/promises";
+import path13 from "node:path";
 import { ts as ts15 } from "ts-morph";
 var FAST_START_MISMATCH = "COMPILATION_FAST_START_MISMATCH";
 var RECORD_VERSION = 1;
@@ -14133,7 +15362,7 @@ function fastStartMode(options, request) {
 function fastStartPath(options, request, configuration) {
   if (request.mode !== "development" || options.incrementalReuse === false || fastStartSwitch(options) === "off" || !configuration.cacheEnabled)
     return void 0;
-  return path12.join(configuration.cacheRoot, `${hash(options.projectId)}.fast-start.json`);
+  return path13.join(configuration.cacheRoot, `${hash(options.projectId)}.fast-start.json`);
 }
 function engineSwitches() {
   return FLAGS.filter((flag) => flag.name !== FAST_START_FLAG).map((flag) => [
@@ -14183,22 +15412,22 @@ async function saveFastStart(file, input) {
   const text = JSON.stringify(record);
   const digest3 = contentDigest(text);
   if (known2.get(file) === digest3 && currentDigest(file) === digest3) return;
-  const temporary = `${file}.${randomUUID5()}.tmp`;
+  const temporary = `${file}.${randomUUID6()}.tmp`;
   try {
-    await mkdir4(path12.dirname(file), { recursive: true });
+    await mkdir5(path13.dirname(file), { recursive: true });
     await sweepTemporaries(file);
-    await writeFile4(temporary, text, { flag: "wx" });
-    await retryingRename(rename4)(temporary, file);
+    await writeFile5(temporary, text, { flag: "wx" });
+    await retryingRename(rename5)(temporary, file);
     known2.set(file, digest3);
   } catch {
     known2.delete(file);
   } finally {
-    await rm4(temporary, { force: true }).catch(() => void 0);
+    await rm5(temporary, { force: true }).catch(() => void 0);
   }
 }
 function currentDigest(file) {
   try {
-    return bytesDigest(readFileSync8(file));
+    return bytesDigest(readFileSync9(file));
   } catch {
     return void 0;
   }
@@ -14207,7 +15436,7 @@ async function restoreFastStart(input) {
   const { file, options, found, signal } = input;
   let record;
   try {
-    const bytes = readFileSync8(file);
+    const bytes = readFileSync9(file);
     const value = JSON.parse(bytes.toString("utf8"));
     if (!isRecord2(value)) return { reason: "the start record is invalid" };
     record = value;
@@ -14265,7 +15494,7 @@ function physical(dependencies) {
   );
 }
 function normalize3(value) {
-  return path12.resolve(value).replace(/\\/g, "/");
+  return path13.resolve(value).replace(/\\/g, "/");
 }
 function members(values, roots) {
   return JSON.stringify(
@@ -14281,8 +15510,8 @@ async function firstChange(inputs, ownedRoots) {
     for (let index2 = next++; index2 < inputs.length && !found; index2 = next++) {
       const input2 = inputs[index2];
       const refreshed = await refresher.refresh([input2], []);
-      const current = refreshed.dependencies[0];
-      const same = !refreshed.diagnostics.some((item) => item.severity === "error") && (input2.kind === "content" ? current?.kind === "content" && current.digest === input2.digest : input2.kind === "existence" ? current?.kind === "existence" && current.exists === input2.exists : current?.kind === "glob" && members(current.members, ownedRoots) === members(input2.members, ownedRoots));
+      const current2 = refreshed.dependencies[0];
+      const same = !refreshed.diagnostics.some((item) => item.severity === "error") && (input2.kind === "content" ? current2?.kind === "content" && current2.digest === input2.digest : input2.kind === "existence" ? current2?.kind === "existence" && current2.exists === input2.exists : current2?.kind === "glob" && members(current2.members, ownedRoots) === members(input2.members, ownedRoots));
       if (!same) {
         changed[index2] = true;
         found = true;
@@ -14323,12 +15552,12 @@ function isDependency2(value) {
 }
 
 // libs/builder/generator/compiler/memo.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
-import { readFileSync as readFileSync9 } from "node:fs";
-import { rename as rename5, rm as rm5, writeFile as writeFile5 } from "node:fs/promises";
-import path13 from "node:path";
+import { randomUUID as randomUUID7 } from "node:crypto";
+import { readFileSync as readFileSync10 } from "node:fs";
+import { rename as rename6, rm as rm6, writeFile as writeFile6 } from "node:fs/promises";
+import path14 from "node:path";
 var MEMO_SCHEMA_VERSION = 2;
-var memoPath = (root, projectId) => path13.join(root, `${hash(projectId)}.compiler-memo.json`);
+var memoPath = (root, projectId) => path14.join(root, `${hash(projectId)}.compiler-memo.json`);
 function createMemoState(enabled, root, options) {
   let loaded;
   const empty2 = () => ({
@@ -14345,7 +15574,7 @@ function createMemoState(enabled, root, options) {
     loaded = empty2();
     if (!enabled) return loaded;
     try {
-      const value = JSON.parse(readFileSync9(memoPath(root, options.projectId), "utf8"));
+      const value = JSON.parse(readFileSync10(memoPath(root, options.projectId), "utf8"));
       if (isMemoFile(value) && value.compilerVersion === options.compilerVersion && value.toolchainDigest === options.toolchainDigest)
         loaded = value;
     } catch {
@@ -14382,13 +15611,13 @@ function createMemoState(enabled, root, options) {
     async save(projectId) {
       if (!enabled) return;
       const file = memoPath(root, projectId);
-      const temporary = `${file}.${randomUUID6()}.tmp`;
+      const temporary = `${file}.${randomUUID7()}.tmp`;
       try {
-        await writeFile5(temporary, JSON.stringify(next), { flag: "wx" });
-        await retryingRename(rename5)(temporary, file);
+        await writeFile6(temporary, JSON.stringify(next), { flag: "wx" });
+        await retryingRename(rename6)(temporary, file);
       } catch {
       } finally {
-        await rm5(temporary, { force: true }).catch(() => void 0);
+        await rm6(temporary, { force: true }).catch(() => void 0);
       }
     }
   };
@@ -14478,14 +15707,20 @@ async function planGeneration(services, input) {
   setup(outputDependencyResult.diagnostics, outputDependencyResult.dependencies);
   const outputDependencies = outputDependencyResult.dependencies;
   const highlight2 = createHighlightSession(options, request, configuration);
+  const format = createFormatSession(options, request, configuration);
+  useFormatCache(format);
+  const grammars2 = grammarsSwitch(options);
   const back = createRenderBack(options, highlight2, {
     themes: configuration.themes,
+    ...configuration.shikiLangs ? { langs: configuration.shikiLangs } : {},
+    ...grammars2 === "all" ? { grammars: grammars2 } : {},
     cache: highlight2 !== void 0
   });
   const compiler = new GeneratorContentCompiler(
     { configuration, semantic, templates: discovery.templates },
     highlight2,
-    back
+    back,
+    grammars2
   );
   return {
     ...services,
@@ -14508,6 +15743,7 @@ async function planGeneration(services, input) {
     memo,
     compiler,
     ...highlight2 ? { highlight: highlight2 } : {},
+    ...format ? { format } : {},
     ...back ? { back } : {},
     scopedSemantic
   };
@@ -14529,7 +15765,7 @@ function planContent(plan, units) {
   plan.records.global("plan", { diagnostics, dependencies: [] });
 }
 var RESTORE_CONCURRENCY = 32;
-var indexPath = (root, projectId) => path14.join(root, `${hash(projectId)}.compilation-index.json`);
+var indexPath = (root, projectId) => path15.join(root, `${hash(projectId)}.compilation-index.json`);
 async function restoreIndex(root, projectId, diagnostics) {
   try {
     const keys = JSON.parse(await readFile4(indexPath(root, projectId), "utf8"));
@@ -14572,18 +15808,18 @@ async function restoreIndex(root, projectId, diagnostics) {
   }
 }
 async function saveIndex(root, projectId, artifacts) {
-  await mkdir5(root, { recursive: true });
+  await mkdir6(root, { recursive: true });
   const file = indexPath(root, projectId);
-  const temporary = `${file}.${randomUUID7()}.tmp`;
+  const temporary = `${file}.${randomUUID8()}.tmp`;
   try {
-    await writeFile6(
+    await writeFile7(
       temporary,
       JSON.stringify(artifacts.map(({ identity, fingerprint }) => ({ identity, fingerprint }))),
       { flag: "wx" }
     );
-    await retryingRename(rename6)(temporary, file);
+    await retryingRename(rename7)(temporary, file);
   } finally {
-    await rm6(temporary, { force: true });
+    await rm7(temporary, { force: true });
   }
 }
 
@@ -14595,9 +15831,9 @@ import { existsSync as existsSync15, statSync as statSync3 } from "node:fs";
 
 // libs/builder/generator/graph/unit-index.ts
 import { existsSync as existsSync14, realpathSync as realpathSync4 } from "node:fs";
-import path15 from "node:path";
+import path16 from "node:path";
 function normalizePath3(file) {
-  return file.charCodeAt(0) === 47 && !file.includes("/.") && !file.includes("//") && !file.includes("\\") && !file.endsWith("/") ? file : path15.resolve(file).replace(/\\/g, "/");
+  return file.charCodeAt(0) === 47 && !file.includes("/.") && !file.includes("//") && !file.includes("\\") && !file.endsWith("/") ? file : path16.resolve(file).replace(/\\/g, "/");
 }
 function rootKeyword(used) {
   const match = /^[^.#]+/.exec(used);
@@ -14613,7 +15849,7 @@ var WINDOWS_DRIVE = /^[A-Za-z]:$/;
 var WINDOWS_DRIVE_ROOT = /^[A-Za-z]:\/$/;
 function parentDirectory(file) {
   if (WINDOWS_DRIVE_ROOT.test(file)) return file;
-  const parent = path15.posix.dirname(file);
+  const parent = path16.posix.dirname(file);
   return WINDOWS_DRIVE.test(parent) ? `${parent}/` : parent;
 }
 function createCanonicalAliases(ports = {}) {
@@ -14635,7 +15871,7 @@ function createCanonicalAliases(ports = {}) {
       }
     } else {
       const parent = parentDirectory(directory);
-      resolved = parent === directory ? directory : path15.posix.join(physicalDirectory(parent), path15.posix.basename(directory));
+      resolved = parent === directory ? directory : path16.posix.join(physicalDirectory(parent), path16.posix.basename(directory));
     }
     directories.set(directory, resolved);
     return resolved;
@@ -14646,7 +15882,7 @@ function createCanonicalAliases(ports = {}) {
     if (cached) return cached;
     const normalized = normalize4(file);
     const directory = parentDirectory(normalized);
-    const physical2 = directory === normalized ? normalized : `${physicalDirectory(directory).replace(/\/$/, "")}/${path15.posix.basename(normalized)}`;
+    const physical2 = directory === normalized ? normalized : `${physicalDirectory(directory).replace(/\/$/, "")}/${path16.posix.basename(normalized)}`;
     const aliases = physical2 === normalized ? [normalized] : [normalized, physical2];
     files.set(file, aliases);
     return aliases;
@@ -15171,8 +16407,8 @@ function discoveryChanges(index, fresh, structural2 = false) {
       entries.add(entry.id);
       continue;
     }
-    const current = indexEntry(entry);
-    if (current.masked !== retained.masked || current.evaluated !== retained.evaluated || current.markdown.size !== retained.markdown.size || [...current.markdown].some(([file, digest3]) => retained.markdown.get(file) !== digest3))
+    const current2 = indexEntry(entry);
+    if (current2.masked !== retained.masked || current2.evaluated !== retained.evaluated || current2.markdown.size !== retained.markdown.size || [...current2.markdown].some(([file, digest3]) => retained.markdown.get(file) !== digest3))
       entries.add(entry.id);
   }
   const ids = new Set(fresh.entries.map((entry) => entry.id));
@@ -15201,9 +16437,9 @@ var discoveryFacts = (found, templates) => ({
   remoteKeywords: JSON.stringify(found.remoteKeywords),
   templates: JSON.stringify(templates)
 });
-function explained(path17, read) {
-  if (read.has(path17)) return true;
-  const prefix = `${path17}/`;
+function explained(path18, read) {
+  if (read.has(path18)) return true;
+  const prefix = `${path18}/`;
   for (const item of read) if (item.startsWith(prefix)) return true;
   return false;
 }
@@ -15216,8 +16452,8 @@ function sweep(build2, index) {
     else if (observed === "present") {
       same = existsSync15(file) && stampOf(file) === void 0;
     } else {
-      const current = stampOf(file);
-      same = current !== void 0 && sameStamp(current, observed);
+      const current2 = stampOf(file);
+      same = current2 !== void 0 && sameStamp(current2, observed);
     }
     if (!same && index.hits(file).length) changed.push({ kind: "update", path: file });
   }
@@ -15518,7 +16754,7 @@ var TargetedGeneration = class _TargetedGeneration {
     for (const phase of ["discovery", "semantic"])
       for (const contribution of plan.records.globalContributions(phase))
         add(contribution.dependencies);
-    return paths.filter((path17) => !explained(path17, read));
+    return paths.filter((path18) => !explained(path18, read));
   }
   /**
    * Compares an API entry's fresh enumeration with its retained units: the entry's own unit holds
@@ -15578,11 +16814,11 @@ var TargetedGeneration = class _TargetedGeneration {
     if (!recorded.size) return false;
     const refreshed = await refresher.refresh([...recorded.values()], []);
     if (refreshed.diagnostics.some((item) => item.severity === "error")) return true;
-    const current = new Map(
+    const current2 = new Map(
       refreshed.dependencies.map((dependency) => [dependencyIdentity(dependency), dependency])
     );
     for (const [identity, dependency] of recorded) {
-      const now = current.get(identity);
+      const now = current2.get(identity);
       if (!now || !("digest" in now) || !("digest" in dependency) || now.digest !== dependency.digest)
         return true;
     }
@@ -15698,8 +16934,8 @@ var TargetedGeneration = class _TargetedGeneration {
   closure(units, keywords) {
     const index = this.committed.index;
     const started = performance.now();
-    const current = new Set(units.map((unit) => unit.id));
-    this.removedOwners = [...index.owners.keys()].filter((id) => !current.has(id)).sort();
+    const current2 = new Set(units.map((unit) => unit.id));
+    this.removedOwners = [...index.owners.keys()].filter((id) => !current2.has(id)).sort();
     if (this.keywordFacts) {
       const keys = /* @__PURE__ */ new Set();
       for (const id of [...this.candidates, ...this.removedOwners])
@@ -15719,7 +16955,7 @@ var TargetedGeneration = class _TargetedGeneration {
       this.facts.keysFrom = "all";
     }
     const consumers = [...index.consumersOf(this.keys)].filter(
-      (id) => !this.candidates.has(id) && current.has(id)
+      (id) => !this.candidates.has(id) && current2.has(id)
     );
     this.linked = /* @__PURE__ */ new Set([...this.candidates, ...consumers]);
     this.facts.keys = this.keys;
@@ -15747,7 +16983,7 @@ var TargetedGeneration = class _TargetedGeneration {
         if (dependency.kind === "content" || dependency.kind === "existence")
           read.add(normalizePath3(dependency.path));
     }
-    const missing = this.unknown.find((path17) => !explained(path17, read));
+    const missing = this.unknown.find((path18) => !explained(path18, read));
     if (missing) throw new TargetedFallback(`unknown path not read by this generation: ${missing}`);
   }
   /** The units a targeted generation linked and assembled (for the report). */
@@ -15960,7 +17196,7 @@ function scopedSemanticSwitch(options) {
 function scopedSemanticMode(options, request) {
   return request.mode === "development" ? scopedSemanticSwitch(options) : "off";
 }
-function closureRebuildReason(previous, current) {
+function closureRebuildReason(previous, current2) {
   const closures = (artifact) => {
     const values = /* @__PURE__ */ new Map();
     for (const dependency of [
@@ -15971,9 +17207,9 @@ function closureRebuildReason(previous, current) {
     return values;
   };
   const before = closures(previous);
-  const after = closures(current);
+  const after = closures(current2);
   const key = [.../* @__PURE__ */ new Set([...before.keys(), ...after.keys()])].sort().find((item) => before.get(item) !== after.get(item));
-  return key === void 0 ? void 0 : { ownerId: current.id, reason: "semantic", detail: `semantic closure changed: ${key}` };
+  return key === void 0 ? void 0 : { ownerId: current2.id, reason: "semantic", detail: `semantic closure changed: ${key}` };
 }
 async function verifyClosureReuse(plan, unit, descriptor, reused) {
   if (plan.scopedSemantic === "off") return void 0;
@@ -16003,12 +17239,12 @@ async function verifyClosureReuse(plan, unit, descriptor, reused) {
   };
 }
 function valueAt(value, at) {
-  let current = value;
+  let current2 = value;
   for (const [, key, index] of at.matchAll(/\.([^.[]+)|\[(\d+)\]/g)) {
-    if (current === null || typeof current !== "object") return void 0;
-    current = current[key ?? Number(index)];
+    if (current2 === null || typeof current2 !== "object") return void 0;
+    current2 = current2[key ?? Number(index)];
   }
-  return current !== null && typeof current === "object" ? JSON.stringify(current) : current;
+  return current2 !== null && typeof current2 === "object" ? JSON.stringify(current2) : current2;
 }
 
 // libs/builder/generator/compiler/assemble.ts
@@ -16223,7 +17459,7 @@ function candidateSnapshot(plan, artifacts, keywordPlan, site) {
       for (const output2 of artifact.outputs) {
         if (plan.previousById.get(artifact.id)?.outputs.some(
           (previousOutput) => previousOutput.path === output2.path && previousOutput.role === output2.role
-        ) && !existsSync16(path16.resolve(configuration.outputRoot, output2.path))) {
+        ) && !existsSync16(path17.resolve(configuration.outputRoot, output2.path))) {
           records.reason({
             ownerId: artifact.id,
             reason: "output-missing",
@@ -17083,8 +18319,8 @@ async function renderFront(plan, unit, scope, rendered) {
 function matchesDescriptorContent(descriptor, ir) {
   return ir.schemaVersion === GENERATOR_SCHEMA_VERSION && ir.id === descriptor.id && ir.role === descriptor.role && ir.title === descriptor.title && ir.route === descriptor.route && ir.absoluteRoute === descriptor.absoluteRoute && sameValue(ir.searchBreadcrumbs ?? [], descriptor.searchBreadcrumbs) && ir.icon === descriptor.icon;
 }
-function sameDescriptorPlan(previous, current) {
-  return !!previous && sameValue(previous, current);
+function sameDescriptorPlan(previous, current2) {
+  return !!previous && sameValue(previous, current2);
 }
 
 // libs/builder/generator/compiler/retention.ts
@@ -17329,7 +18565,7 @@ function createCompilationService(options) {
   };
   const targetedResults = /* @__PURE__ */ new WeakSet();
   let disposed = false;
-  let active = false;
+  let active2 = false;
   let activeController;
   let activeSettlement;
   return {
@@ -17337,7 +18573,7 @@ function createCompilationService(options) {
     async compile(request, signal, context) {
       let records = new GenerationRecords();
       const result = (candidate) => fold(records, candidate);
-      if (disposed || signal.aborted || active) {
+      if (disposed || signal.aborted || active2) {
         records.global("failure", {
           diagnostics: [
             diagnostic(
@@ -17349,7 +18585,7 @@ function createCompilationService(options) {
         });
         return result();
       }
-      active = true;
+      active2 = true;
       const releaseThreads = holdHtmlPool();
       guideValues = /* @__PURE__ */ new Map();
       const startedNs = BigInt(Date.now()) * 1000000n;
@@ -17478,6 +18714,8 @@ function createCompilationService(options) {
         if (!scratch)
           prestartRenderThreads(options, request, found.entries.length, {
             themes: found.configuration.themes,
+            ...found.configuration.shikiLangs ? { langs: found.configuration.shikiLangs } : {},
+            ...grammarsSwitch(options) === "all" ? { grammars: "all" } : {},
             cache: highlightCacheSwitch(options) !== "off"
           });
         await synchronize(true);
@@ -17663,8 +18901,9 @@ function createCompilationService(options) {
             ...reportError !== void 0 ? { error: reportError } : {}
           });
         signal.removeEventListener("abort", abort);
+        useFormatCache(void 0);
         releaseThreads();
-        active = false;
+        active2 = false;
         activeController = void 0;
         settle();
         activeSettlement = void 0;
@@ -17726,6 +18965,17 @@ async function runPhases(plan, found, scope, cache = true, progress) {
   scope?.explain(artifacts, units);
   progress?.phase("aggregate");
   const site = aggregateUnits(plan, artifacts, keywordPlan);
+  if (plan.format?.mismatches)
+    records.global("aggregate", {
+      diagnostics: [
+        diagnostic(
+          FORMAT_CACHE_MISMATCH,
+          `${plan.format.mismatches} cached formatted signature(s), snippet(s) or formatter configuration(s) differ from formatting them again; the fresh formatting is used.`,
+          "warning"
+        )
+      ],
+      dependencies: []
+    });
   if (signal.aborted || records.failed()) return done();
   const candidate = candidateSnapshot(plan, artifacts, keywordPlan, site);
   if (records.failed()) return done();
@@ -17736,9 +18986,9 @@ async function runPhases(plan, found, scope, cache = true, progress) {
       artifacts,
       scope ? (artifact) => artifact === plan.previousById.get(artifact.id) : void 0
     );
-    await plan.highlight?.save(
-      !scope && units.every((unit) => unit.record.render.every((step) => step.projection !== "reuse"))
-    );
+    const complete = !scope && units.every((unit) => unit.record.render.every((step) => step.projection !== "reuse"));
+    await plan.highlight?.save(complete);
+    await plan.format?.save(complete);
   }
   progress?.end();
   if (signal.aborted) return done();