@ng-doc/builder 22.0.0 → 22.1.0

package/generator/vite/index.js

@@ -1,5 +1,5 @@
 // libs/builder/generator/vite/plugin.ts
-import path19 from "node:path";
+import path20 from "node:path";
 
 // libs/builder/generator/artifacts/index.ts
 import { randomUUID } from "node:crypto";
@@ -49,24 +49,24 @@ function sha256Hex(value) {
 function canonicalJson(value) {
   return canonical(value, /* @__PURE__ */ new Set()) ?? "null";
 }
-function canonical(value, path24) {
+function canonical(value, path25) {
   if (value !== null && typeof value === "object" && typeof value.toJSON === "function")
     value = value.toJSON();
   if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (path24.has(value)) throw new TypeError("Converting circular structure to canonical JSON");
-  path24.add(value);
+  if (path25.has(value)) throw new TypeError("Converting circular structure to canonical JSON");
+  path25.add(value);
   let text5;
   if (Array.isArray(value)) {
-    text5 = `[${Array.from(value, (item) => canonical(item, path24) ?? "null").join(",")}]`;
+    text5 = `[${Array.from(value, (item) => canonical(item, path25) ?? "null").join(",")}]`;
   } else {
     const fields = [];
     for (const key of Object.keys(value).sort(compareCodeUnits)) {
-      const item = canonical(value[key], path24);
+      const item = canonical(value[key], path25);
       if (item !== void 0) fields.push(`${JSON.stringify(key)}:${item}`);
     }
     text5 = `{${fields.join(",")}}`;
   }
-  path24.delete(value);
+  path25.delete(value);
   return text5;
 }
 function digestOf(value) {
@@ -1927,9 +1927,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(
@@ -2174,7 +2176,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(
   [
     {
@@ -2252,6 +2256,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.",
@@ -2333,11 +2347,11 @@ async function changedInputs(inputs, ownedRoots) {
   const refresher = createDependencyRefresher();
   const changes = /* @__PURE__ */ new Map();
   const add = (kind, file) => {
-    const path24 = normalize(file);
-    if (owned(path24, roots)) return;
-    const existing = changes.get(path24);
+    const path25 = normalize(file);
+    if (owned(path25, roots)) return;
+    const existing = changes.get(path25);
     if (!existing || CHANGE_RANK[kind] > CHANGE_RANK[existing.kind])
-      changes.set(path24, { kind, path: path24 });
+      changes.set(path25, { kind, path: path25 });
   };
   for (let offset = 0; offset < inputs.length; offset += CONCURRENCY) {
     await Promise.all(
@@ -3270,7 +3284,7 @@ var GeneratorBuildSession = class {
     const pending = state.pending;
     if (queued) {
       const changes = new Map(queued.changes.map((change) => [change.path, change]));
-      pending.changes.forEach((change, path24) => changes.set(path24, change));
+      pending.changes.forEach((change, path25) => changes.set(path25, change));
       queued.changes = [...changes.values()];
       queued.origin = queued.changes.length ? "filesystem" : "reconcile";
       queued.waiters.push(...pending.waiters);
@@ -4911,7 +4925,7 @@ function createCandidateOutputCommitter(options = {}, host = {}) {
 
 // libs/builder/generator/bootstrap/constants.ts
 var GENERATOR_COMPILER_VERSION = "0.0.1";
-var GENERATOR_TOOLCHAIN_DIGEST = "a837a4b43736f6b95b5565f442aa62d2f2175fb549d7a44138d2955d465c9ac3";
+var GENERATOR_TOOLCHAIN_DIGEST = "d3b66d41f47865fb003a881897f703f6b49568eefa8f301d410768b97f5647e2";
 
 // libs/builder/generator/bootstrap/index.ts
 var PERSISTENT_WORKER_ENV = PERSISTENT_WORKER_FLAG;
@@ -5062,6 +5076,9 @@ var COMPILER_TYPESCRIPT = /\.[cm]?ts(?![a-z])/;
 var JAVASCRIPT_MODULE = /\.[cm]?jsx?$/;
 var COMPILER_RESOURCE = /\.(?:html?|css|less|sass|scss)$/;
 var HOST_COMPLETION_TIMEOUT_MS = 3e4;
+var HOST_BURST_EVENTS = 1e3;
+var HOST_BURST_WINDOW_MS = 1e3;
+var HOST_BURST_QUIET_MS = 2e3;
 function deferred2(resolved = false) {
   let settled = false;
   let settle = () => {
@@ -5130,9 +5147,10 @@ function observePhysicalVersion(file) {
   }
 }
 var HostUpdateCoordinator = class {
-  constructor(notify, fail) {
+  constructor(notify, fail, recovery) {
     this.notify = notify;
     this.fail = fail;
+    this.recovery = recovery;
     this.attempts = /* @__PURE__ */ new Map();
     this.pendingSources = /* @__PURE__ */ new Map();
     this.claimedSources = /* @__PURE__ */ new Map();
@@ -5147,6 +5165,8 @@ var HostUpdateCoordinator = class {
     this.hostDrain = deferred2(true);
     this.sequence = 0;
     this.disposed = false;
+    /** The start and the hot updates of the current burst-detection window. */
+    this.window = { start: 0, events: 0 };
   }
   seed(outputRoot, manifest) {
     this.outputRoot = normalize3(outputRoot);
@@ -5239,6 +5259,7 @@ var HostUpdateCoordinator = class {
     }
     const filePath = normalize3(file);
     const generated = !!this.outputRoot && relativeWithin(this.outputRoot, filePath) !== void 0;
+    if (this.outputRoot && !generated) this.hotUpdate();
     const token = {
       id: ++this.sequence,
       path: filePath,
@@ -5427,6 +5448,8 @@ var HostUpdateCoordinator = class {
   }
   dispose() {
     this.disposed = true;
+    if (this.burst?.timer) clearTimeout(this.burst.timer);
+    this.burst = void 0;
     this.pendingGeneration = void 0;
     this.pendingManifest = void 0;
     for (const attempt of this.attempts.values()) {
@@ -5713,13 +5736,109 @@ var HostUpdateCoordinator = class {
         })
       ]).catch((error2) => {
         const failure3 = error2 instanceof Error ? error2 : new Error(String(error2));
-        this.fail(failure3);
+        this.timedOut(failure3);
         throw failure3;
       });
     } finally {
       if (timeout) clearTimeout(timeout);
     }
   }
+  /** Counts a hot update towards a burst of file events (see the class description). */
+  hotUpdate() {
+    const now = Date.now();
+    if (this.burst) {
+      this.burst.last = now;
+      this.burst.events = true;
+      return;
+    }
+    if (now - this.window.start >= HOST_BURST_WINDOW_MS) this.window = { start: now, events: 0 };
+    if (++this.window.events >= HOST_BURST_EVENTS) this.openBurst(now).events = true;
+  }
+  /**
+   * A host update did not settle in time. The first of a burst is reported as it happens (as
+   * every timeout was before); the others only count towards the burst's summary, so a flood of
+   * file events logs two lines instead of one per event.
+   * @param failure The timeout, thrown to its waiter as well.
+   */
+  timedOut(failure3) {
+    const burst = this.burst ?? this.openBurst(Date.now());
+    burst.last = Date.now();
+    if (burst.timeouts++ === 0) this.fail(failure3);
+  }
+  openBurst(now) {
+    const burst = { events: false, timeouts: 0, last: now };
+    this.burst = burst;
+    this.armBurst(burst, HOST_BURST_QUIET_MS);
+    return burst;
+  }
+  /**
+   * One timer per burst, re-armed for the rest of the quiet period when activity moved `last`.
+   * @param burst The open burst.
+   * @param delay When to check it next.
+   */
+  armBurst(burst, delay) {
+    burst.timer = setTimeout(() => {
+      if (this.burst !== burst || this.disposed) return;
+      const quiet = Date.now() - burst.last;
+      if (quiet < HOST_BURST_QUIET_MS) {
+        this.armBurst(burst, HOST_BURST_QUIET_MS - quiet);
+        return;
+      }
+      this.burst = void 0;
+      this.window = { start: 0, events: 0 };
+      void this.recover(burst);
+    }, delay);
+    burst.timer.unref?.();
+  }
+  /**
+   * The pass after a burst: the summary of its held-back timeouts, then every open output
+   * obligation whose file is still what its generation wrote is reported again, in path order,
+   * and every recorded input is re-observed once no generation is in flight. An output a newer generation rewrote since is left
+   * to that generation's own report, which supersedes the older expectation.
+   * @param burst The burst that ended.
+   */
+  async recover(burst) {
+    if (burst.timeouts > 1) {
+      this.recovery?.warn(
+        `[NGDOC_VITE_HOST_TIMEOUT] ${burst.timeouts - 1} more host update(s) did not settle within ${HOST_COMPLETION_TIMEOUT_MS / 1e3} s while files kept changing. NgDoc checks the generated files and the documentation inputs again.`
+      );
+    }
+    const open2 = /* @__PURE__ */ new Map();
+    for (const attempt of [...this.attempts.values()].sort(
+      (left, right) => right.generation - left.generation
+    )) {
+      if (!attempt.resultSeen) continue;
+      for (const expected of attempt.expected.values()) {
+        if (!expected.completed && !open2.has(expected.path)) open2.set(expected.path, expected);
+      }
+    }
+    for (const [file, expected] of [...open2].sort(([left], [right]) => left < right ? -1 : 1)) {
+      let current;
+      let written;
+      try {
+        [current, written] = await Promise.all([observePhysicalState(file), expected.state]);
+      } catch {
+        continue;
+      }
+      if (this.disposed) return;
+      const unchanged = expected.digest === void 0 ? current.version === "missing" : current.digest === expected.digest && current.version === written.version;
+      if (expected.completed || !unchanged) continue;
+      try {
+        this.recovery?.replay(
+          file,
+          expected.kind === "update" ? "update" : expected.digest === void 0 ? "delete" : "create"
+        );
+      } catch {
+      }
+    }
+    for (let latest = this.latestAttempt; latest && !latest.resultSeen && !this.disposed; latest = this.latestAttempt)
+      await latest.result.promise;
+    if (this.disposed) return;
+    try {
+      this.recovery?.rescan();
+    } catch {
+    }
+  }
 };
 
 // libs/builder/generator/vite/angular-composition.ts
@@ -6335,6 +6454,28 @@ function sameRuntimeConfiguration(left, right) {
   return left.outputRoot === right.outputRoot && left.cacheRoot === right.cacheRoot && left.assetDirectory === right.assetDirectory;
 }
 
+// libs/builder/generator/vite/demo-application.ts
+import { readFile as readFile5 } from "node:fs/promises";
+import path11 from "node:path";
+var DEMO_APPLICATION_MODULE = "demo-app.ts";
+var DEMO_PATH = /^export const NG_DOC_DEMO_PATH = '([^'\\\n]*)';$/m;
+var DEMO_PAGES = /^export const NG_DOC_DEMO_PAGES: string\[\] = (.*);$/m;
+async function readDemoApplication(outputRoot) {
+  const module = path11.join(outputRoot, DEMO_APPLICATION_MODULE);
+  const source = await readFile5(module, "utf8").catch(() => void 0);
+  const demoPath = source === void 0 ? void 0 : DEMO_PATH.exec(source)?.[1];
+  const pages2 = source === void 0 ? void 0 : demoPages(DEMO_PAGES.exec(source)?.[1]);
+  return demoPath && pages2 ? { module, path: demoPath, pages: pages2 } : void 0;
+}
+function demoPages(json) {
+  try {
+    const value = json === void 0 ? void 0 : JSON.parse(json);
+    return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
 // libs/builder/generator/vite/diagnostics.ts
 function diagnosticText(diagnostic4) {
   const source = diagnostic4.source ? ` (${diagnostic4.source.path}${diagnostic4.source.line ? `:${diagnostic4.source.line}` : ""})` : "";
@@ -6350,7 +6491,7 @@ function hostDiagnostic(code, message4) {
 }
 
 // libs/builder/generator/vite/lease.ts
-import path11 from "node:path";
+import path12 from "node:path";
 var identities = /* @__PURE__ */ new Map();
 var outputRoots = /* @__PURE__ */ new Map();
 function acquireOutputLease(identity2, defaultOutputRoot) {
@@ -6358,7 +6499,7 @@ function acquireOutputLease(identity2, defaultOutputRoot) {
     throw new Error(`[NGDOC_VITE_OUTPUT_LEASE] Output owner is already active for ${identity2}.`);
   }
   const token = Symbol(identity2);
-  const initialRoot = canonicalDrive(path11.resolve(defaultOutputRoot).replace(/\\/g, "/"));
+  const initialRoot = canonicalDrive(path12.resolve(defaultOutputRoot).replace(/\\/g, "/"));
   if (outputRoots.has(initialRoot)) {
     throw new Error(
       `[NGDOC_VITE_OUTPUT_LEASE] Default output root is already active: ${initialRoot}.`
@@ -6372,7 +6513,7 @@ function acquireOutputLease(identity2, defaultOutputRoot) {
   return {
     admit(value) {
       if (disposed) throw new Error("[NGDOC_VITE_OUTPUT_LEASE] Output lease is disposed.");
-      const normalized = canonicalDrive(path11.resolve(value).replace(/\\/g, "/"));
+      const normalized = canonicalDrive(path12.resolve(value).replace(/\\/g, "/"));
       const owner = outputRoots.get(normalized);
       if (owner && owner !== token) {
         throw new Error(
@@ -6403,11 +6544,11 @@ function acquireOutputLease(identity2, defaultOutputRoot) {
 
 // libs/builder/generator/vite/lifecycle.ts
 import { existsSync as existsSync5 } from "node:fs";
-import path16 from "node:path";
+import path17 from "node:path";
 
 // libs/builder/generator/vite/assets.ts
-import { readFile as readFile5 } from "node:fs/promises";
-import path12 from "node:path";
+import { readFile as readFile6 } from "node:fs/promises";
+import path13 from "node:path";
 var GENERATED_ASSET_PATH = "assets/ng-doc";
 var MIME = /* @__PURE__ */ new Map([
   [".css", "text/css; charset=utf-8"],
@@ -6429,7 +6570,7 @@ function normalizedBase(base) {
   return value.endsWith("/") ? value : `${value}/`;
 }
 function safeRelative2(value) {
-  return !!value && !value.includes("\0") && !value.includes("\\") && !path12.posix.isAbsolute(value) && !value.split("/").some((segment) => segment === ".." || segment === "");
+  return !!value && !value.includes("\0") && !value.includes("\\") && !path13.posix.isAbsolute(value) && !value.split("/").some((segment) => segment === ".." || segment === "");
 }
 function inventory(configuration, manifest) {
   const prefix = `${configuration.assetDirectory.replace(/\\/g, "/").replace(/\/$/, "")}/`;
@@ -6446,7 +6587,7 @@ function inventory(configuration, manifest) {
       throw new Error(`[NGDOC_VITE_ASSET_COLLISION] Duplicate generated asset: ${relative}.`);
     }
     result.set(relative, {
-      file: path12.join(configuration.outputRoot, output),
+      file: path13.join(configuration.outputRoot, output),
       outputName: outputName2
     });
   }
@@ -6485,12 +6626,12 @@ var GeneratedAssetInventory = class {
         next2();
         return;
       }
-      void readFile5(asset.file).then(
+      void readFile6(asset.file).then(
         (source) => {
           response.statusCode = 200;
           response.setHeader(
             "Content-Type",
-            MIME.get(path12.extname(relative).toLowerCase()) ?? "application/octet-stream"
+            MIME.get(path13.extname(relative).toLowerCase()) ?? "application/octet-stream"
           );
           response.end(source);
         },
@@ -6513,7 +6654,7 @@ var GeneratedAssetInventory = class {
       context.emitFile({
         type: "asset",
         fileName: asset.outputName,
-        source: await readFile5(asset.file)
+        source: await readFile6(asset.file)
       });
     }
   }
@@ -6524,7 +6665,7 @@ var GeneratedAssetInventory = class {
 
 // libs/builder/generator/vite/vite-event-source.ts
 import { existsSync as existsSync4, realpathSync as realpathSync2, statSync as statSync6 } from "node:fs";
-import path15 from "node:path";
+import path16 from "node:path";
 
 // libs/builder/generator/vite/external-probes.ts
 import { statSync as statSync5 } from "node:fs";
@@ -6605,7 +6746,7 @@ var ExternalProbeWatcher = class {
 
 // libs/builder/generator/vite/missing-paths.ts
 import { existsSync as existsSync3, watch as watchDirectory } from "node:fs";
-import path13 from "node:path";
+import path14 from "node:path";
 var MAX_MISSING_PATH_DIRECTORIES = 1024;
 var defaultWatch = (directory, listener) => watchDirectory(
   directory,
@@ -6613,9 +6754,9 @@ var defaultWatch = (directory, listener) => watchDirectory(
   (event, name) => listener(event, typeof name === "string" ? name : null)
 );
 function anchorOf(target) {
-  let cursor = path13.dirname(target);
+  let cursor = path14.dirname(target);
   while (!existsSync3(cursor)) {
-    const parent = path13.dirname(cursor);
+    const parent = path14.dirname(cursor);
     if (parent === cursor) break;
     cursor = parent;
   }
@@ -6702,7 +6843,7 @@ var MissingPathWatcher = class {
     const members2 = [...this.members.get(anchor) ?? []];
     const gone = !existsSync3(anchor);
     for (const target of members2) {
-      const entry = path13.relative(anchor, target).split(path13.sep)[0];
+      const entry = path14.relative(anchor, target).split(path14.sep)[0];
       if (!gone && name !== null && name !== entry) continue;
       this.refresh(target);
     }
@@ -6725,9 +6866,9 @@ var MissingPathWatcher = class {
 // libs/builder/generator/vite/watch-inputs.ts
 import { Minimatch } from "minimatch";
 import { access } from "node:fs/promises";
-import path14 from "node:path";
+import path15 from "node:path";
 function normalize4(value) {
-  return path14.resolve(value).replace(/\\/g, "/");
+  return path15.resolve(value).replace(/\\/g, "/");
 }
 function union(left, right) {
   const files = new Set([...left?.files ?? [], ...right?.files ?? []].map(normalize4));
@@ -6749,14 +6890,14 @@ function inputKey(inputs) {
   return JSON.stringify(inputs);
 }
 function absolutePattern(root, pattern) {
-  return normalize4(path14.isAbsolute(pattern) ? pattern : path14.join(root, pattern));
+  return normalize4(path15.isAbsolute(pattern) ? pattern : path15.join(root, pattern));
 }
 function patternBase(root, pattern) {
   const absolute2 = absolutePattern(root, pattern);
   const magic = absolute2.search(/[*?{}[\]()!]/);
-  if (magic < 0) return path14.dirname(absolute2).replace(/\\/g, "/");
+  if (magic < 0) return path15.dirname(absolute2).replace(/\\/g, "/");
   const slash2 = absolute2.lastIndexOf("/", magic);
-  return (slash2 > 0 ? absolute2.slice(0, slash2) : path14.parse(absolute2).root).replace(/\\/g, "/");
+  return (slash2 > 0 ? absolute2.slice(0, slash2) : path15.parse(absolute2).root).replace(/\\/g, "/");
 }
 async function nearestExisting(value) {
   let cursor = normalize4(value);
@@ -6765,7 +6906,7 @@ async function nearestExisting(value) {
       await access(cursor);
       return cursor;
     } catch {
-      const parent = path14.dirname(cursor).replace(/\\/g, "/");
+      const parent = path15.dirname(cursor).replace(/\\/g, "/");
       if (parent === cursor) return cursor;
       cursor = parent;
     }
@@ -6775,16 +6916,16 @@ function ancestorOf(target, candidate) {
   return target === candidate || target.startsWith(`${candidate}/`);
 }
 function globPattern(pattern) {
-  return path14.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern;
+  return path15.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern;
 }
 function compilePattern(pattern) {
   return {
-    absolute: path14.isAbsolute(pattern),
+    absolute: path15.isAbsolute(pattern),
     matcher: new Minimatch(globPattern(pattern), { dot: true })
   };
 }
 function patternMatches(glob2, pattern, changed) {
-  const subject = pattern.absolute ? changed : path14.relative(glob2.root, changed).replace(/\\/g, "/");
+  const subject = pattern.absolute ? changed : path15.relative(glob2.root, changed).replace(/\\/g, "/");
   return pattern.matcher.match(subject);
 }
 function globMatches(glob2, changed) {
@@ -6871,7 +7012,7 @@ var WatchInputRegistry = class {
     const directories = /* @__PURE__ */ new Set();
     for (const target of globBases) {
       const existing = await nearestExisting(target);
-      if (existing === path14.parse(existing).root.replace(/\\/g, "/")) {
+      if (existing === path15.parse(existing).root.replace(/\\/g, "/")) {
         throw new Error(
           `[NGDOC_VITE_WATCH_ROOT] Refusing an unbounded filesystem-root glob watch for ${target}.`
         );
@@ -6882,7 +7023,7 @@ var WatchInputRegistry = class {
       }
     }
     for (const target of desired) {
-      if (target === path14.parse(target).root.replace(/\\/g, "/")) {
+      if (target === path15.parse(target).root.replace(/\\/g, "/")) {
         throw new Error(
           `[NGDOC_VITE_WATCH_ROOT] Refusing an unbounded filesystem-root file watch for ${target}.`
         );
@@ -6941,7 +7082,7 @@ var WatchInputRegistry = class {
 
 // libs/builder/generator/vite/vite-event-source.ts
 function normalize5(value) {
-  return canonicalDrive(path15.resolve(value).replace(/\\/g, "/"));
+  return canonicalDrive(path16.resolve(value).replace(/\\/g, "/"));
 }
 function within2(target, root) {
   return target === root || target.startsWith(`${root}/`);
@@ -6962,12 +7103,12 @@ function statVersion(file) {
   }
 }
 function listed(watched, target) {
-  return watched.has(target) || (watched.get(path15.dirname(target))?.includes(path15.basename(target)) ?? false);
+  return watched.has(target) || (watched.get(path16.dirname(target))?.includes(path16.basename(target)) ?? false);
 }
 function nearestExistingPath(target) {
   let cursor = target;
   while (!existsSync4(cursor)) {
-    const parent = path15.dirname(cursor);
+    const parent = path16.dirname(cursor);
     if (parent === cursor) return cursor;
     cursor = parent;
   }
@@ -6992,7 +7133,7 @@ function workspaceRoots(root) {
     roots.add(normalize5(realpathSync2.native(root)));
   } catch {
   }
-  return [...roots].filter((value) => value !== normalize5(path15.parse(value).root));
+  return [...roots].filter((value) => value !== normalize5(path16.parse(value).root));
 }
 function watchesMissingPaths(watcher) {
   const options = watcher.options;
@@ -7446,7 +7587,24 @@ var ViteAdapterLifecycle = class {
     this.latestStarted = -1;
     this.hostUpdates = new HostUpdateCoordinator(
       () => this.server?.ws.send({ type: "full-reload" }),
-      (error2) => this.fail(error2)
+      (error2) => this.fail(error2),
+      {
+        warn: (message4) => this.warn(message4),
+        // Exactly the event Vite's watcher emits for the file: Vite invalidates its modules and
+        // runs the hot update hooks, which the coordinator matches like the lost report.
+        replay: (file, type) => {
+          if (this.disposed) return;
+          this.server?.watcher.emit(
+            type === "create" ? "add" : type === "delete" ? "unlink" : "change",
+            file
+          );
+        },
+        rescan: () => {
+          if (this.disposed) return;
+          void this.session?.rescan().catch(() => {
+          });
+        }
+      }
     );
   }
   get failure() {
@@ -7511,13 +7669,13 @@ var ViteAdapterLifecycle = class {
       const read = /* @__PURE__ */ new Set();
       for (const artifact of committed.snapshot.artifacts) {
         for (const dependency of artifact.dependencies) {
-          if (dependency.kind === "content" && DESCRIPTION_MODULE.test(path16.basename(dependency.path)))
-            read.add(canonicalDrive(path16.resolve(dependency.path)));
+          if (dependency.kind === "content" && DESCRIPTION_MODULE.test(path17.basename(dependency.path)))
+            read.add(canonicalDrive(path17.resolve(dependency.path)));
         }
       }
       committed.read = read;
     }
-    return committed.read.has(canonicalDrive(path16.resolve(file)));
+    return committed.read.has(canonicalDrive(path17.resolve(file)));
   }
   hostUpdateStarted(file, type, read) {
     const change = { kind: type, path: file };
@@ -7562,7 +7720,7 @@ var ViteAdapterLifecycle = class {
   hostClaimsFilesystemChange(file) {
     if (this.disposed) return false;
     if (this.hostUpdates.generated(file)) return true;
-    if (!DESCRIPTION_MODULE.test(path16.basename(file)) || !(this.source?.matches({ kind: "update", path: file }) ?? false))
+    if (!DESCRIPTION_MODULE.test(path17.basename(file)) || !(this.source?.matches({ kind: "update", path: file }) ?? false))
       return false;
     return !(this.committedDescriptionModule(file) && existsSync5(file));
   }
@@ -7717,6 +7875,14 @@ var ViteAdapterLifecycle = class {
     } catch {
     }
   }
+  warn(message4) {
+    if (!this.server) return;
+    this.interrupt();
+    try {
+      this.server.config.logger.warn(message4);
+    } catch {
+    }
+  }
   isCurrent(generation) {
     return !this.disposed && generation >= this.latestStarted && (!this.source || this.source.isCurrent(generation));
   }
@@ -7758,7 +7924,7 @@ var ViteAdapterLifecycle = class {
 var NG_DOC_SYNTAX_THEME_NAME = "css-variables";
 
 // libs/builder/generator/vite/options.ts
-import path17 from "node:path";
+import path18 from "node:path";
 
 // libs/builder/generator/progress/settings.ts
 var PROGRESS_SETTINGS = Object.freeze([
@@ -7887,6 +8053,16 @@ var ENGINE_SWITCHES = Object.freeze([
     values: /^(0|false|off|no|verify)$/i,
     effect: "every code block is highlighted again"
   },
+  {
+    name: "NGDOC_FORMAT_CACHE",
+    values: /^(0|false|off|no|verify)$/i,
+    effect: "every signature and snippet is formatted again"
+  },
+  {
+    name: "NGDOC_USED_GRAMMARS",
+    values: /^(0|false|off|no)$/i,
+    effect: "every Shiki grammar is loaded before code is highlighted"
+  },
   {
     name: "NGDOC_PARALLEL_RENDER",
     values: /^(0|false|off|no|verify)$/i,
@@ -7942,7 +8118,7 @@ function resolveOptions(options) {
     );
   }
   const angularComponentProbe = text2(options.angularComponentProbe, "angularComponentProbe");
-  if (!path17.isAbsolute(angularComponentProbe) || !/\.ts$/.test(angularComponentProbe) || /\.d\.ts$/.test(angularComponentProbe) || angularComponentProbe.includes("?")) {
+  if (!path18.isAbsolute(angularComponentProbe) || !/\.ts$/.test(angularComponentProbe) || /\.d\.ts$/.test(angularComponentProbe) || angularComponentProbe.includes("?")) {
     throw new TypeError(
       "angularComponentProbe must be an absolute application .ts component path."
     );
@@ -7961,8 +8137,8 @@ function resolveOptions(options) {
   if (options.progress !== void 0 && (!isProgressSetting(options.progress) || options.progress === "json")) {
     throw new TypeError("progress must be auto, live, plain, verbose, summary or off.");
   }
-  const workspace = path17.resolve(text2(options.generator.workspaceRoot, "workspaceRoot"));
-  const defaultRoot = path17.resolve(
+  const workspace = path18.resolve(text2(options.generator.workspaceRoot, "workspaceRoot"));
+  const defaultRoot = path18.resolve(
     text2(options.generator.defaults.outputRoot, "defaults.outputRoot")
   );
   return {
@@ -7972,7 +8148,7 @@ function resolveOptions(options) {
     themeModules,
     leaseIdentity: `${text2(options.generator.projectId, "projectId")}\0${workspace}\0${defaultRoot}`,
     angularPlugins: [...options.angularPlugins],
-    angularComponentProbe: path17.normalize(angularComponentProbe),
+    angularComponentProbe: path18.normalize(angularComponentProbe),
     ...options.progress ? { progress: options.progress } : {}
   };
 }
@@ -7989,14 +8165,14 @@ function themeImports(options, configuration) {
   ].sort();
 }
 function within3(root, file) {
-  const relative = path17.relative(root, file);
-  return relative === "" || !relative.startsWith("..") && !path17.isAbsolute(relative);
+  const relative = path18.relative(root, file);
+  return relative === "" || !relative.startsWith("..") && !path18.isAbsolute(relative);
 }
 var CacheRootWatchIgnore = class {
   constructor(options) {
     this.options = options;
     const cacheRoot = options.generator.defaults.cacheRoot;
-    this.cacheRoot = typeof cacheRoot === "string" && path17.isAbsolute(cacheRoot) ? canonicalDrive(path17.resolve(cacheRoot)) : void 0;
+    this.cacheRoot = typeof cacheRoot === "string" && path18.isAbsolute(cacheRoot) ? canonicalDrive(path18.resolve(cacheRoot)) : void 0;
     this.active = this.cacheRoot !== void 0;
   }
   get ignoring() {
@@ -8010,11 +8186,11 @@ var CacheRootWatchIgnore = class {
       workspaceRoot,
       defaults.outputRoot,
       defaults.docsRoot,
-      typeof defaults.tsConfig === "string" ? path17.dirname(defaults.tsConfig) : void 0
+      typeof defaults.tsConfig === "string" ? path18.dirname(defaults.tsConfig) : void 0
     ]);
     const cacheRoot = this.cacheRoot;
     if (!this.active || !cacheRoot) return void 0;
-    return (file) => this.active && typeof file === "string" && within3(cacheRoot, path17.resolve(file));
+    return (file) => this.active && typeof file === "string" && within3(cacheRoot, path18.resolve(file));
   }
   /** Re-checks the finally resolved Vite root (a later plugin can change `root`). */
   confirmRoot(viteRoot) {
@@ -8027,7 +8203,7 @@ var CacheRootWatchIgnore = class {
   admit(configuration) {
     const cacheRoot = this.cacheRoot;
     if (!this.active || !cacheRoot) return false;
-    const publishedCache = typeof configuration.cacheRoot === "string" ? canonicalDrive(path17.resolve(configuration.cacheRoot)) : void 0;
+    const publishedCache = typeof configuration.cacheRoot === "string" ? canonicalDrive(path18.resolve(configuration.cacheRoot)) : void 0;
     if (publishedCache === cacheRoot && this.guard([configuration.outputRoot])) return false;
     this.active = false;
     return true;
@@ -8035,7 +8211,7 @@ var CacheRootWatchIgnore = class {
   guard(roots) {
     const cacheRoot = this.cacheRoot;
     if (!this.active || !cacheRoot || // Unvalidated roots are rejected by bootstrap later; never ignore when one is missing.
-    roots.some((value) => typeof value !== "string" || !value) || roots.some((value) => within3(cacheRoot, path17.resolve(value)))) {
+    roots.some((value) => typeof value !== "string" || !value) || roots.some((value) => within3(cacheRoot, path18.resolve(value)))) {
       this.active = false;
     }
     return this.active;
@@ -8043,26 +8219,26 @@ var CacheRootWatchIgnore = class {
 };
 function metadataWatchIgnore(options, viteRoot) {
   const { workspaceRoot, defaults } = options.generator;
-  if (typeof workspaceRoot !== "string" || !path17.isAbsolute(workspaceRoot)) return void 0;
-  const idea = path17.resolve(workspaceRoot, ".idea");
+  if (typeof workspaceRoot !== "string" || !path18.isAbsolute(workspaceRoot)) return void 0;
+  const idea = path18.resolve(workspaceRoot, ".idea");
   const roots = [
     viteRoot,
     defaults.outputRoot,
     defaults.docsRoot,
-    typeof defaults.tsConfig === "string" ? path17.dirname(defaults.tsConfig) : void 0
+    typeof defaults.tsConfig === "string" ? path18.dirname(defaults.tsConfig) : void 0
   ];
   const ignoreIdea = !roots.some(
-    (value) => typeof value === "string" && value && within3(idea, path17.resolve(value))
+    (value) => typeof value === "string" && value && within3(idea, path18.resolve(value))
   );
   return (file) => {
     if (typeof file !== "string") return false;
-    const target = path17.resolve(file);
-    return path17.basename(target) === ".DS_Store" || ignoreIdea && within3(idea, target);
+    const target = path18.resolve(file);
+    return path18.basename(target) === ".DS_Store" || ignoreIdea && within3(idea, target);
   };
 }
 function staticViteConfig(options, viteRoot = process.cwd(), cacheWatch = new CacheRootWatchIgnore(options)) {
-  const cacheIgnore = cacheWatch.matcher(path17.resolve(viteRoot));
-  const metadataIgnore = metadataWatchIgnore(options, path17.resolve(viteRoot));
+  const cacheIgnore = cacheWatch.matcher(path18.resolve(viteRoot));
+  const metadataIgnore = metadataWatchIgnore(options, path18.resolve(viteRoot));
   const ignored = [GENERATED_STAGE_IGNORE];
   if (cacheIgnore) ignored.push(cacheIgnore);
   if (metadataIgnore) ignored.push(metadataIgnore);
@@ -8098,10 +8274,10 @@ function assertThemeModules(options, configuration) {
 
 // libs/builder/generator/vite/output-watch.ts
 import { realpathSync as realpathSync3 } from "node:fs";
-import path18 from "node:path";
+import path19 from "node:path";
 var OUTPUT_WATCH_ATTACH_TIMEOUT_MS = 1e4;
 function normalize6(value) {
-  return canonicalDrive(path18.resolve(value).replace(/\\/g, "/"));
+  return canonicalDrive(path19.resolve(value).replace(/\\/g, "/"));
 }
 function within4(target, root) {
   return target === root || target.startsWith(`${root}/`);
@@ -8133,9 +8309,9 @@ async function watchOutputRoot(watcher, viteRoot, outputRoot, files, options = {
   for (const file of files) {
     let target = `${root}/${file.replace(/\\/g, "/")}`;
     while (target !== root && within4(target, root)) {
-      const parent = path18.posix.dirname(target);
+      const parent = path19.posix.dirname(target);
       const listed2 = entries.get(parent) ?? /* @__PURE__ */ new Set();
-      listed2.add(path18.posix.basename(target));
+      listed2.add(path19.posix.basename(target));
       entries.set(parent, listed2);
       target = parent;
     }
@@ -9551,7 +9727,7 @@ function hotPayload(value, childToServer = false) {
     case "full-reload":
       return (value.path === void 0 || typeof value.path === "string") && (value.triggeredBy === void 0 || typeof value.triggeredBy === "string");
     case "prune":
-      return Array.isArray(value.paths) && value.paths.every((path24) => typeof path24 === "string");
+      return Array.isArray(value.paths) && value.paths.every((path25) => typeof path25 === "string");
     case "update":
       return Array.isArray(value.updates) && value.updates.every(
         (update) => record2(update) && (update.type === "js-update" || update.type === "css-update") && typeof update.path === "string" && typeof update.acceptedPath === "string" && Number.isFinite(update.timestamp)
@@ -10367,10 +10543,10 @@ function getNgDocViteSsrRenderer(plugins, options) {
 }
 
 // libs/builder/generator/vite/theme-index.ts
-import { readFile as readFile6 } from "node:fs/promises";
+import { readFile as readFile7 } from "node:fs/promises";
 var MARKER = "data-ng-doc-theme-restore";
 async function createThemeIndexTransformer(scriptUrl = new URL("./restore-theme.js", import.meta.url)) {
-  const source = await readFile6(scriptUrl, "utf8");
+  const source = await readFile7(scriptUrl, "utf8");
   const tag = `<script ${MARKER}>${source}</script>`;
   return async (content) => {
     if (content.includes(MARKER)) return content;
@@ -10642,6 +10818,20 @@ function createPlugin(options) {
       ngDocSsrRenderer: Object.freeze({
         schemaVersion: 1,
         select: (entry) => ssrRenderer.select(entry)
+      }),
+      ngDocDemoApplication: Object.freeze({
+        schemaVersion: 1,
+        // A build decides its inputs before it starts, so the application plugin asks for the
+        // generation early (its `options` hook); `buildStart` then finds it initialized.
+        async resolve() {
+          if (vite?.command === "build") await initializeBuild();
+          const state = active ?? await initialized;
+          return state ? readDemoApplication(state.configuration.outputRoot) : void 0;
+        },
+        async current() {
+          const configuration = active?.lifecycle.configuration ?? active?.configuration;
+          return configuration ? readDemoApplication(configuration.outputRoot) : void 0;
+        }
       })
     },
     enforce: "pre",
@@ -10663,7 +10853,7 @@ function createPlugin(options) {
           "[NGDOC_VITE_BUILD_WATCH] Vite build watch is unsupported; use the development server."
         );
       }
-      return staticViteConfig(resolved, path19.resolve(config.root ?? process.cwd()), cacheWatch);
+      return staticViteConfig(resolved, path20.resolve(config.root ?? process.cwd()), cacheWatch);
     },
     configResolved(config) {
       vite = config;
@@ -10844,13 +11034,13 @@ function createPlugin(options) {
 // libs/builder/generator/vite/application.ts
 import { minimatch as minimatch2 } from "minimatch";
 import { existsSync as existsSync6 } from "node:fs";
-import { readdir, readFile as readFile7, stat as stat5 } from "node:fs/promises";
+import { mkdir as mkdir2, readdir, readFile as readFile8, stat as stat5, writeFile as writeFile2 } from "node:fs/promises";
 import { createRequire as createRequire2 } from "node:module";
-import path22 from "node:path";
+import path23 from "node:path";
 import { escapePath, glob } from "tinyglobby";
 
 // libs/builder/generator/vite/dev-styles.ts
-import path20 from "node:path";
+import path21 from "node:path";
 var GATE_TIMINGS = { sheet: 5e3, quiet: 1500, limit: 1e4 };
 function ngDocDevStyleGate(timings = GATE_TIMINGS) {
   return `(() => {
@@ -10909,8 +11099,8 @@ async function ngDocDevStyleTags(server, styles) {
     { tag: "script", children: NG_DOC_DEV_STYLE_GATE, injectTo: "head-prepend" }
   ];
   for (const style of styles) {
-    const relative = path20.relative(root, style);
-    const url = relative && !relative.startsWith("..") && !path20.isAbsolute(relative) ? `/${relative.split(path20.sep).join("/")}` : `/@fs/${style.split(path20.sep).join("/").replace(/^\/+/, "")}`;
+    const relative = path21.relative(root, style);
+    const url = relative && !relative.startsWith("..") && !path21.isAbsolute(relative) ? `/${relative.split(path21.sep).join("/")}` : `/@fs/${style.split(path21.sep).join("/").replace(/^\/+/, "")}`;
     try {
       const sheet = cssModuleSheet((await environment.transformRequest(url))?.code ?? "");
       if (!sheet) continue;
@@ -10942,7 +11132,7 @@ function cssModuleSheet(code) {
 }
 
 // libs/builder/generator/vite/mime.ts
-import path21 from "node:path";
+import path22 from "node:path";
 var TYPES = {
   ".aac": "audio/aac",
   ".apng": "image/apng",
@@ -10992,14 +11182,21 @@ var TYPES = {
   ".zip": "application/zip"
 };
 function contentType(file) {
-  return TYPES[path21.extname(file).toLowerCase()] ?? "application/octet-stream";
+  return TYPES[path22.extname(file).toLowerCase()] ?? "application/octet-stream";
 }
 
 // libs/builder/generator/vite/application.ts
 var NG_DOC_BROWSER_ENTRY = "/@ng-doc-application/browser.js";
 var NG_DOC_SERVER_ENTRY = "/@ng-doc-application/server.js";
+var NG_DOC_DEMO_ENTRY = "/@ng-doc-application/demo.js";
+var NG_DOC_DEMO_SERVER_ENTRY = "/@ng-doc-application/demo-server.js";
+var NG_DOC_DEMO_PAGE = "ng-doc-demo.html";
+var NG_DOC_DEMO_SERVER_NAME = "demo-server";
 var BROWSER_ID = "\0ng-doc-application:browser";
 var SERVER_ID = "\0ng-doc-application:server";
+var DEMO_ID = "\0ng-doc-application:demo";
+var DEMO_SERVER_ID = "\0ng-doc-application:demo-server";
+var DEMO_ROOT = "<ng-doc-demo-app></ng-doc-demo-app>";
 var ANGULAR_DEDUPE = [
   "@angular/common",
   "@angular/compiler",
@@ -11091,23 +11288,23 @@ function posix(value) {
   return value.replace(/\\/g, "/");
 }
 function specifier(workspaceRoot, value) {
-  const file = path22.resolve(workspaceRoot, value);
-  return value.startsWith(".") || path22.isAbsolute(value) || existsSync6(file) ? posix(file) : value;
+  const file = path23.resolve(workspaceRoot, value);
+  return value.startsWith(".") || path23.isAbsolute(value) || existsSync6(file) ? posix(file) : value;
 }
 async function resolveAssets(assets, workspaceRoot, sourceRoot) {
   const resolved = [];
   for (const [index, asset] of assets.entries()) {
     if (typeof asset === "string") {
-      const input = path22.resolve(workspaceRoot, text4(asset, `assets[${index}]`));
+      const input = path23.resolve(workspaceRoot, text4(asset, `assets[${index}]`));
       const file = await stat5(input).then(
         (value) => value.isFile(),
         () => {
           throw optionError(`assets[${index}] does not exist: ${asset}`);
         }
       );
-      const directory = file ? path22.dirname(input) : input;
-      const relative = path22.relative(sourceRoot, directory);
-      if (relative.startsWith("..") || path22.isAbsolute(relative)) {
+      const directory = file ? path23.dirname(input) : input;
+      const relative = path23.relative(sourceRoot, directory);
+      if (relative.startsWith("..") || path23.isAbsolute(relative)) {
         throw optionError(
           `assets[${index}] (${asset}) is outside sourceRoot (${sourceRoot}); use a { glob, input, output } entry.`
         );
@@ -11115,18 +11312,18 @@ async function resolveAssets(assets, workspaceRoot, sourceRoot) {
       resolved.push({
         input: directory,
         output: posix(relative),
-        glob: file ? path22.basename(input) : "**/*",
+        glob: file ? path23.basename(input) : "**/*",
         ignore: []
       });
       continue;
     }
     if (!asset || typeof asset !== "object") throw optionError(`assets[${index}] is invalid.`);
     const output = posix(asset.output ?? "").replace(/^\/+|\/+$/g, "");
-    if (output.split("/").includes("..") || path22.isAbsolute(output)) {
+    if (output.split("/").includes("..") || path23.isAbsolute(output)) {
       throw optionError(`assets[${index}].output must stay inside the output directory.`);
     }
     resolved.push({
-      input: path22.resolve(workspaceRoot, text4(asset.input, `assets[${index}].input`)),
+      input: path23.resolve(workspaceRoot, text4(asset.input, `assets[${index}].input`)),
       output,
       glob: text4(asset.glob, `assets[${index}].glob`),
       ignore: [...asset.ignore ?? []]
@@ -11148,7 +11345,7 @@ async function collectAssets(assets) {
       expandDirectories: false
     });
     for (const relative of matches.map(posix).sort()) {
-      files.set(outputName(asset, relative), path22.join(asset.input, relative));
+      files.set(outputName(asset, relative), path23.join(asset.input, relative));
     }
   }
   return files;
@@ -11168,14 +11365,14 @@ function matchAssets(assets, base, url) {
   for (const asset of [...assets].reverse()) {
     const relative = asset.output ? requested.startsWith(`${asset.output}/`) ? requested.slice(asset.output.length + 1) : void 0 : requested;
     if (relative && minimatch2(relative, asset.glob, { dot: true }) && !asset.ignore.some((pattern) => minimatch2(relative, pattern, { dot: true }))) {
-      candidates.push({ file: path22.join(asset.input, relative), relative });
+      candidates.push({ file: path23.join(asset.input, relative), relative });
     }
   }
   return candidates;
 }
 function resolvable(root, name) {
   try {
-    createRequire2(path22.join(root, "package.json")).resolve(`${name}/package.json`);
+    createRequire2(path23.join(root, "package.json")).resolve(`${name}/package.json`);
     return true;
   } catch {
     return false;
@@ -11183,17 +11380,17 @@ function resolvable(root, name) {
 }
 async function coreImports(root) {
   const found = /* @__PURE__ */ new Set();
-  const require2 = createRequire2(path22.join(root, "package.json"));
+  const require2 = createRequire2(path23.join(root, "package.json"));
   for (const name of ["@ng-doc/app", "@ng-doc/ui-kit"]) {
     let directory;
     try {
-      directory = path22.join(path22.dirname(require2.resolve(`${name}/package.json`)), "fesm2022");
+      directory = path23.join(path23.dirname(require2.resolve(`${name}/package.json`)), "fesm2022");
     } catch {
       continue;
     }
     const files = await readdir(directory).catch(() => []);
     for (const file of files.filter((item) => item.endsWith(".mjs")).sort()) {
-      for (const match of (await readFile7(path22.join(directory, file), "utf8")).matchAll(
+      for (const match of (await readFile8(path23.join(directory, file), "utf8")).matchAll(
         CORE_IMPORT
       )) {
         found.add(match[1]);
@@ -11205,6 +11402,20 @@ async function coreImports(root) {
 function escapeAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
+function demoDocument(index) {
+  const body = /<body(\s[^>]*)?>[\s\S]*<\/body>/i;
+  return body.test(index) ? index.replace(
+    body,
+    (_all, attributes) => `<body${attributes ?? ""}>${DEMO_ROOT}</body>`
+  ) : `${index}${DEMO_ROOT}`;
+}
+function withDemoInput(input, key, id, next2) {
+  const record3 = typeof input === "string" ? { [path23.parse(input).name]: input } : Array.isArray(input) ? Object.fromEntries(input.map((item) => [path23.parse(item).name, item])) : { ...input ?? {} };
+  if (Object.values(record3).some((item) => item === id || posix(path23.resolve(item)) === id)) {
+    record3[key] = next2;
+  }
+  return record3;
+}
 function withBase(html, base) {
   if (!base.startsWith("/")) return html;
   const href = escapeAttribute(base);
@@ -11216,30 +11427,38 @@ function withBase(html, base) {
 function createNgDocApplicationPlugin(options) {
   if (!options || typeof options !== "object") throw optionError("options must be an object.");
   const warnings = checkOptionKeys(options);
-  const workspaceRoot = path22.resolve(options.workspaceRoot ?? process.cwd());
-  const browser = path22.resolve(workspaceRoot, text4(options.browser, "browser"));
-  const server = options.server === void 0 ? void 0 : path22.resolve(workspaceRoot, text4(options.server, "server"));
-  const sourceRoot = path22.resolve(workspaceRoot, options.sourceRoot ?? path22.dirname(browser));
+  const workspaceRoot = path23.resolve(options.workspaceRoot ?? process.cwd());
+  const browser = path23.resolve(workspaceRoot, text4(options.browser, "browser"));
+  const server = options.server === void 0 ? void 0 : path23.resolve(workspaceRoot, text4(options.server, "server"));
+  const sourceRoot = path23.resolve(workspaceRoot, options.sourceRoot ?? path23.dirname(browser));
   const polyfills = (options.polyfills ?? []).map(
     (item, index) => specifier(workspaceRoot, text4(item, `polyfills[${index}]`))
   );
   const styles = (options.styles ?? []).map(
-    (item, index) => posix(path22.resolve(workspaceRoot, text4(item, `styles[${index}]`)))
+    (item, index) => posix(path23.resolve(workspaceRoot, text4(item, `styles[${index}]`)))
   );
   const assetPatterns = [...options.assets ?? []];
+  const zone = (options.polyfills ?? []).some(
+    (item) => item === "zone.js" || item.startsWith("zone.js/")
+  );
+  let viteRoot = process.cwd();
+  let demoApi;
+  let demo;
+  const demoPage = () => posix(path23.join(viteRoot, NG_DOC_DEMO_PAGE));
+  const currentDemo = async () => config?.command === "build" ? demo : await demoApi?.current().catch(() => void 0);
   let assets;
   const resolvedAssets = () => assets ??= resolveAssets(assetPatterns, workspaceRoot, sourceRoot);
   let config;
-  const developmentPrebundles = async (viteRoot) => ({
+  const developmentPrebundles = async (viteRoot2) => ({
     include: [
       .../* @__PURE__ */ new Set([
-        ...await coreImports(viteRoot),
-        ...polyfills.filter((item) => !path22.isAbsolute(item)),
-        ...resolvable(viteRoot, "tslib") ? ["tslib"] : []
+        ...await coreImports(viteRoot2),
+        ...polyfills.filter((item) => !path23.isAbsolute(item)),
+        ...resolvable(viteRoot2, "tslib") ? ["tslib"] : []
       ])
     ].sort(),
-    entries: [...polyfills.filter((item) => path22.isAbsolute(item)), posix(browser)].map(
-      (file) => escapePath(posix(path22.relative(viteRoot, file)))
+    entries: [...polyfills.filter((item) => path23.isAbsolute(item)), posix(browser)].map(
+      (file) => escapePath(posix(path23.relative(viteRoot2, file)))
     )
   });
   const api = Object.freeze({
@@ -11251,6 +11470,7 @@ function createNgDocApplicationPlugin(options) {
     enforce: "pre",
     api: { ngDocApplication: api },
     async config(user, environment) {
+      viteRoot = path23.resolve(user.root ?? process.cwd());
       return {
         resolve: { dedupe: ANGULAR_DEDUPE },
         // Every `vite build` is a production build of the application (the Angular CLI's
@@ -11260,7 +11480,7 @@ function createNgDocApplicationPlugin(options) {
             ["ngDevMode", "ngJitMode"].filter((name) => !(user.define && name in user.define)).map((name) => [name, "false"])
           )
         } : {},
-        ...environment.command === "serve" ? { optimizeDeps: await developmentPrebundles(path22.resolve(user.root ?? process.cwd())) } : {},
+        ...environment.command === "serve" ? { optimizeDeps: await developmentPrebundles(viteRoot) } : {},
         // The server bundle is imported by a plain Node process: it must hold every dependency,
         // partially compiled Angular libraries included.
         ...environment.command === "build" && environment.isSsrBuild ? { ssr: { noExternal: true } } : {}
@@ -11268,11 +11488,42 @@ function createNgDocApplicationPlugin(options) {
     },
     configResolved(resolved) {
       config = resolved;
+      viteRoot = resolved.root ?? viteRoot;
+      const apis = (resolved.plugins ?? []).map((plugin) => plugin.api?.ngDocDemoApplication).filter((api2) => api2?.schemaVersion === 1);
+      demoApi = apis.length === 1 ? apis[0] : void 0;
       for (const warning of warnings) resolved.logger.warn(warning);
     },
+    // A build with demo pages builds the demo application too: its page is a second input of the
+    // browser build and its server entry a second input of the server build. Whether there are
+    // demo pages is known once NgDoc has generated, so the NgDoc plugin generates here, before
+    // the build starts, instead of in its `buildStart`.
+    async options(input) {
+      if (config?.command !== "build" || !demoApi) return null;
+      demo = await demoApi.resolve();
+      if (!demo) return null;
+      return {
+        ...input,
+        input: config.build.ssr ? withDemoInput(
+          input.input,
+          NG_DOC_DEMO_SERVER_NAME,
+          NG_DOC_SERVER_ENTRY,
+          NG_DOC_DEMO_SERVER_ENTRY
+        ) : withDemoInput(
+          input.input ?? path23.join(viteRoot, "index.html"),
+          "ng-doc-demo",
+          posix(path23.join(viteRoot, "index.html")),
+          demoPage()
+        )
+      };
+    },
     resolveId(source, importer, resolveOptions2) {
       if (source === NG_DOC_BROWSER_ENTRY) return BROWSER_ID;
-      if (importer === BROWSER_ID && config?.command === "build") {
+      if (source === NG_DOC_DEMO_ENTRY) return DEMO_ID;
+      if (source === NG_DOC_DEMO_SERVER_ENTRY) return DEMO_SERVER_ID;
+      if (config?.command === "build" && demo && posix(path23.resolve(viteRoot, source)) === demoPage()) {
+        return demoPage();
+      }
+      if ((importer === BROWSER_ID || importer === DEMO_ID) && config?.command === "build") {
         const { isEntry, custom } = resolveOptions2;
         return this.resolve(source, importer, { isEntry, custom, skipSelf: true }).then(
           (resolved) => resolved && !resolved.external ? { ...resolved, moduleSideEffects: true } : resolved
@@ -11287,6 +11538,25 @@ function createNgDocApplicationPlugin(options) {
       return SERVER_ID;
     },
     load(id) {
+      if (config?.command === "build" && demo && id === demoPage()) {
+        const index = path23.join(viteRoot, "index.html");
+        this.addWatchFile(index);
+        return readFile8(index, "utf8").then(demoDocument);
+      }
+      if (id === DEMO_ID || id === DEMO_SERVER_ID) {
+        return currentDemo().then((current) => {
+          if (!current) {
+            throw new Error(
+              "[NGDOC_VITE_DEMO_APPLICATION] The demo application was requested, but NgDoc generated no demo pages."
+            );
+          }
+          return demoEntry(id === DEMO_SERVER_ID ? "server" : "browser", current.module, {
+            polyfills: id === DEMO_SERVER_ID ? serverPolyfills(options.polyfills ?? []) : polyfills,
+            styles: id === DEMO_SERVER_ID ? [] : styles,
+            zone
+          });
+        });
+      }
       if (id === BROWSER_ID) {
         return [...polyfills, ...styles, posix(browser)].map((item) => `import ${JSON.stringify(item)};`).join("\n");
       }
@@ -11318,6 +11588,7 @@ function createNgDocApplicationPlugin(options) {
     transformIndexHtml: {
       order: "pre",
       async handler(html, context) {
+        const demoPageHtml = html.includes(DEMO_ROOT);
         return {
           html: withBase(html, config?.base ?? "/"),
           tags: [
@@ -11326,7 +11597,10 @@ function createNgDocApplicationPlugin(options) {
             ...context.server ? await ngDocDevStyleTags(context.server, styles) : [],
             {
               tag: "script",
-              attrs: { type: "module", src: NG_DOC_BROWSER_ENTRY },
+              attrs: {
+                type: "module",
+                src: demoPageHtml ? NG_DOC_DEMO_ENTRY : NG_DOC_BROWSER_ENTRY
+              },
               injectTo: "body"
             }
           ]
@@ -11335,6 +11609,43 @@ function createNgDocApplicationPlugin(options) {
     },
     configureServer(server2) {
       server2.middlewares.use(assetMiddleware(resolvedAssets, () => server2.config.base));
+      server2.middlewares.use((request, response, next2) => {
+        const accept = request.headers.accept;
+        const url = request.url ?? "/";
+        if (request.method !== "GET" || !(Array.isArray(accept) ? accept.join(",") : accept ?? "").includes("text/html")) {
+          next2();
+          return;
+        }
+        void currentDemo().then(async (current) => {
+          const prefix = `${server2.config.base.replace(/\/?$/, "/")}${current?.path}/`;
+          if (!current || !url.split(/[?#]/, 1)[0].startsWith(prefix)) {
+            next2();
+            return;
+          }
+          const index = await readFile8(path23.join(viteRoot, "index.html"), "utf8");
+          const html = await server2.transformIndexHtml(
+            url,
+            demoDocument(index),
+            request.originalUrl
+          );
+          response.statusCode = 200;
+          response.setHeader("Content-Type", "text/html");
+          response.end(html);
+        }).catch((error2) => next2(error2));
+      });
+    },
+    // Every demo page is a copy of the demo application's page, so a static host without a
+    // fallback serves it, as with hash URLs (which are built without prerendering). Prerendering
+    // replaces each copy with the rendered page.
+    async writeBundle(output) {
+      if (config?.command !== "build" || config.build.ssr || !demo || !output.dir) return;
+      const page = await readFile8(path23.join(output.dir, NG_DOC_DEMO_PAGE), "utf8");
+      for (const route of [...demo.pages].sort()) {
+        if (unsafeSegment(route)) continue;
+        const file = path23.join(output.dir, ...route.split("/"), "index.html");
+        await mkdir2(path23.dirname(file), { recursive: true });
+        await writeFile2(file, page);
+      }
     },
     async generateBundle(_output, bundle) {
       if (config?.command !== "build" || config.build.ssr) return;
@@ -11344,7 +11655,7 @@ function createNgDocApplicationPlugin(options) {
         if (bundle[fileName]) {
           throw new Error(`[NGDOC_VITE_ASSET_COLLISION] Vite bundle already owns ${fileName}.`);
         }
-        this.emitFile({ type: "asset", fileName, source: await readFile7(file) });
+        this.emitFile({ type: "asset", fileName, source: await readFile8(file) });
       }
     }
   };
@@ -11354,7 +11665,7 @@ function assetMiddleware(assets, base) {
     void assets().then(
       async (resolved) => {
         for (const match of matchAssets(resolved, base(), request.url ?? "/")) {
-          const source = await readFile7(match.file).catch(() => void 0);
+          const source = await readFile8(match.file).catch(() => void 0);
           if (!source) continue;
           response.statusCode = 200;
           response.setHeader("Content-Type", contentType(match.relative));
@@ -11367,6 +11678,50 @@ function assetMiddleware(assets, base) {
     );
   };
 }
+function demoEntry(platform, module, options) {
+  const imports = [...options.polyfills, ...options.styles].map(
+    (item) => `import ${JSON.stringify(item)};`
+  );
+  const application = [
+    `import { bootstrapApplication } from '@angular/platform-browser';`,
+    `import { NgDocDemoAppComponent, \u0275ngDocDemoApplicationConfig } from '@ng-doc/app/demo-app';`,
+    `import { NG_DOC_DEMO_PROVIDERS, NG_DOC_DEMO_ROUTES } from ${JSON.stringify(posix(module))};`
+  ];
+  if (platform === "browser") {
+    return [
+      ...imports,
+      ...application,
+      // A page the server rendered carries the serialized state (`<script id="ng-state">`, the
+      // default APP_ID); the other pages (the copies of the demo page, the development server's)
+      // start without hydration, as Angular warns (NG0505) when it finds no state.
+      `\u0275ngDocDemoApplicationConfig(NG_DOC_DEMO_ROUTES, NG_DOC_DEMO_PROVIDERS, {`,
+      `  zone: ${options.zone},`,
+      `  hydration: document.getElementById('ng-state') !== null,`,
+      `})`,
+      `  .then((config) => bootstrapApplication(NgDocDemoAppComponent, config))`,
+      `  .catch((error) => console.error(error));`
+    ].join("\n");
+  }
+  return [
+    ...imports,
+    ...application,
+    `import { provideServerRendering } from '@angular/platform-server';`,
+    `export const bootstrap = async (context) =>`,
+    `  bootstrapApplication(`,
+    `    NgDocDemoAppComponent,`,
+    `    await \u0275ngDocDemoApplicationConfig(NG_DOC_DEMO_ROUTES, NG_DOC_DEMO_PROVIDERS, {`,
+    `      zone: ${options.zone},`,
+    `      hydration: true,`,
+    `      providers: [provideServerRendering()],`,
+    `    }),`,
+    `    context,`,
+    `  );`,
+    `export default bootstrap;`,
+    `export { renderApplication } from '@angular/platform-server';`,
+    `export { Router } from '@angular/router';`,
+    `export { runInInjectionContext } from '@angular/core';`
+  ].join("\n");
+}
 
 // libs/builder/generator/vite/prerender.ts
 import { fork as fork3 } from "node:child_process";
@@ -11385,7 +11740,8 @@ function prerenderNgDoc(options) {
     serverEntry: options.serverEntry,
     routes: [...options.routes ?? []],
     discoverRoutes: options.discoverRoutes ?? true,
-    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs }
+    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
+    ...options.demoServerEntry ? { demoServerEntry: options.demoServerEntry } : {}
   };
   if (request.routeTimeoutMs !== void 0 && (!Number.isSafeInteger(request.routeTimeoutMs) || request.routeTimeoutMs < 1)) {
     return Promise.reject(
@@ -11436,8 +11792,9 @@ function prerenderNgDoc(options) {
 }
 
 // libs/builder/generator/vite/production.ts
-import { rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
-import path23 from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
+import path24 from "node:path";
 import { build as viteBuild } from "vite";
 var defaultDependencies = {
   build: viteBuild,
@@ -11474,11 +11831,11 @@ function applicationProbe() {
 async function buildNgDocViteApplication(options, dependencies = defaultDependencies) {
   assertSupportedViteVersion();
   assertConsistentAngularBuild();
-  const configFile = path23.resolve(options.configFile);
-  const outputPath = path23.resolve(options.outputPath);
-  const browser = path23.join(outputPath, "browser");
-  const serverDirectory = path23.join(outputPath, "server");
-  const serverEntry = path23.join(serverDirectory, "server.mjs");
+  const configFile = path24.resolve(options.configFile);
+  const outputPath = path24.resolve(options.outputPath);
+  const browser = path24.join(outputPath, "browser");
+  const serverDirectory = path24.join(outputPath, "server");
+  const serverEntry = path24.join(serverDirectory, "server.mjs");
   const mode = options.mode ?? "production";
   const log = options.log ?? (() => {
   });
@@ -11515,7 +11872,7 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
     ssr ??= entry !== void 0;
     if (!ssr) {
       await rm2(serverDirectory, { recursive: true, force: true });
-      await rm2(path23.join(outputPath, "prerendered-routes.json"), { force: true });
+      await rm2(path24.join(outputPath, "prerendered-routes.json"), { force: true });
       if (options.prerender === true) throw noServer();
     } else {
       if (!entry) {
@@ -11550,23 +11907,26 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
   }
   const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
   if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const demoServerEntry = path24.join(serverDirectory, "demo-server.mjs");
   const report = await timed(
     "Prerendered the routes",
     () => dependencies.prerender({
       browserDir: browser,
       serverEntry,
+      ...existsSync7(demoServerEntry) && existsSync7(path24.join(browser, "ng-doc-demo.html")) ? { demoServerEntry } : {},
       routes: options.routes ?? [],
       discoverRoutes: options.discoverRoutes ?? true,
       ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
       ...options.signal ? { signal: options.signal } : {}
     })
   );
-  await writeFile2(
-    path23.join(outputPath, "prerendered-routes.json"),
+  await writeFile3(
+    path24.join(outputPath, "prerendered-routes.json"),
     `${JSON.stringify({ routes: report.routes, excluded: report.excluded }, null, 2)}
 `
   );
   log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  for (const { route, message: message4 } of report.warnings ?? []) log(`Warning: ${route}: ${message4}`);
   if (report.errors.length) {
     log(`The application logged ${report.errors.length} error(s) while prerendering:`);
     for (const { route, message: message4 } of report.errors.slice(0, 10)) log(`  ${route}: ${message4}`);