@ng-doc/builder 22.0.0 → 22.1.0

package/generator/contracts.d.ts

@@ -151,6 +151,12 @@ export interface RemoteKeywordSnapshot {
     /** Optional upstream validator is evidence, never an assumed lifetime guarantee. */
     validator?: string;
 }
+/** A Shiki (TextMate) language registration of `shiki.langs`: a grammar as plain JSON. */
+export interface ShikiLanguage {
+    readonly name: string;
+    readonly scopeName: string;
+    readonly [key: string]: JsonValue;
+}
 export interface GeneratorConfiguration {
     projectId: ProjectId;
     workspaceRoot: FilePath;
@@ -166,10 +172,35 @@ export interface GeneratorConfiguration {
     inlineStyleLanguage: 'CSS' | 'SCSS' | 'SASS' | 'LESS';
     anchorHeadings: Array<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'>;
     headerTemplate?: FilePath;
+    /**
+     * `false` when `api.protectedMembers` is `false`: API templates then list only public class
+     * members. Absent otherwise, so every other configuration keeps its digest.
+     */
+    apiProtectedMembers?: false;
+    /**
+     * The demo pages (`isolatedDemos`, `demoApplication`, `demoProviders`). Absent when none of them
+     * is set, so every other configuration keeps its digest, and so is every default field:
+     * - `pages`: `all` builds a demo page for every demo, `none` for none; absent, only the guides
+     *   with an isolated demo get them.
+     * - `isolated`: `true` when `isolatedDemos` is: every `demo` action shows an iframe by default.
+     * - `path`: the URL path of the demo pages, absent for `demo-preview`.
+     * - `providers`: the module that `demoProviders` imports.
+     */
+    demoApplication?: {
+        pages?: 'all' | 'none';
+        isolated?: true;
+        path?: string;
+        providers?: FilePath;
+    };
     themes: {
         light: string;
         dark: string;
     };
+    /**
+     * The Shiki language registrations of `shiki.langs`, flattened, as plain JSON in configuration
+     * order. Absent without any, so every other configuration keeps its digest.
+     */
+    shikiLangs?: ShikiLanguage[];
     repo?: {
         url: string;
         platform: 'github' | 'gitlab';
@@ -608,6 +639,14 @@ export interface RouteRecord {
      * for the root list), which its route carries as `ngDocApiListSegment` data.
      */
     apiListSegment?: string;
+    /**
+     * The guide's demo routes module (relative to the output root), when the guide has demo pages.
+     * The aggregate lists it in `demo-app.ts`. Optional and only written for such guides, so a cache
+     * written without it stays valid: every other route record is unchanged.
+     */
+    demoModulePath?: string;
+    /** The names of the guide's demo pages, in the order of `demos`, with `demoModulePath`. */
+    demoNames?: string[];
 }
 export interface ApiListRecord {
     apiEntryId: EntryId;

package/generator/discovery/index.d.ts

@@ -69,6 +69,8 @@ export declare function createDiscoveryServices(options?: DiscoveryOptions): {
     values: GuideValueReader;
     runtime: DiscoveryServiceImpl;
 };
+/** The default URL path of the demo pages. */
+export declare const DEFAULT_DEMO_PATH = "demo-preview";
 /**
  * The `evaluated` digest of every entry of a discovery snapshot: the refresh source of the
  * `evaluated` dependencies a generation recorded against it.

package/generator/kernel/flags.d.ts

@@ -34,7 +34,9 @@ export declare const TRACKED_PROGRAM_REUSE_FLAG = "NGDOC_TRACKED_PROGRAM_REUSE";
 export declare const FAST_START_FLAG = "NGDOC_FAST_START";
 export declare const PARALLEL_WRITES_FLAG = "NGDOC_PARALLEL_WRITES";
 export declare const HIGHLIGHT_CACHE_FLAG = "NGDOC_HIGHLIGHT_CACHE";
+export declare const FORMAT_CACHE_FLAG = "NGDOC_FORMAT_CACHE";
 export declare const PARALLEL_RENDER_FLAG = "NGDOC_PARALLEL_RENDER";
+export declare const USED_GRAMMARS_FLAG = "NGDOC_USED_GRAMMARS";
 /** The registry, in the order the engine applies the switches. */
 export declare const FLAGS: readonly FlagDefinition[];
 /**

package/generator/outputs/index.d.ts

@@ -56,10 +56,23 @@ export declare class OutputAssemblerImpl implements OutputAssembler {
     assemblePage(request: PageAssemblyRequest): PageAssembly;
     aggregate(request: AggregateRequest): AggregateAssembly;
     private guide;
+    /**
+     * 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.
+     */
+    private demoRoutes;
     private apiEntry;
     private apiDeclaration;
     private apiLists;
     private addContentSource;
+    /**
+     * 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.
+     */
+    private demoApplication;
     private renderOutput;
 }
 export declare function createOutputAssembler(options?: {

package/generator/semantic/angular.d.ts

@@ -2,8 +2,28 @@ import { type ObjectLiteralExpression, type SourceFile, Node, ts } from 'ts-morp
 import type { GeneratorConfiguration, GuideSemantics, JsonValue } from '../contracts.js';
 import { type TrackedFiles } from './dependencies.js';
 import type { JsDoc } from './rendering.js';
-/** Resolves wrappers and local constants without executing source code. */
+/**
+ * Resolves wrappers and local constants without executing source code.
+ * @param node
+ * @param seen
+ */
 export declare function unwrap(node: Node | undefined, seen?: Set<Node<ts.Node>>): Node | undefined;
+/**
+ *
+ * @param source
+ */
 export declare function entryObject(source: SourceFile): ObjectLiteralExpression;
+/**
+ *
+ * @param node
+ */
 export declare function literal(node: Node | undefined): JsonValue;
+/**
+ *
+ * @param source
+ * @param files
+ * @param config
+ * @param docs
+ * @param values
+ */
 export declare function guideSemantics(source: SourceFile, files: TrackedFiles, config: GeneratorConfiguration, docs: JsDoc, values?: JsonValue): GuideSemantics;

package/generator/semantic/formatting.d.ts

@@ -0,0 +1,27 @@
+import type { Options } from 'prettier';
+/**
+ * The cache `formatCode` consults: `FormatCodeCache` of `helpers/format-cache.ts`, restated here
+ * because the published declarations reach this module and cannot import from outside the
+ * generator. TypeScript checks that the two agree where `formatting` installs it.
+ */
+export interface GenerationFormatCache {
+    config(configDirectory: string | undefined, resolve: () => Options | null): Options | null;
+    format(input: {
+        code: string;
+        parser: string;
+        config: Options | null;
+    }, format: () => string): string;
+}
+/**
+ * Makes `cache` the one {@link formatting} installs (undefined: none). A runtime compiles one
+ * generation at a time; the compiler sets it when it plans a generation and clears it when the
+ * compile ends, so a later generation never sees an earlier one's resolved configuration.
+ * @param cache The generation's cache (`content/format-cache.ts`).
+ */
+export declare function useFormatCache(cache: GenerationFormatCache | undefined): void;
+/**
+ * Runs synchronous formatting work (API templates, demo snippets) with the current generation's
+ * format cache, if any.
+ * @param run The work; `formatCode` calls it makes consult the cache.
+ */
+export declare function formatting<T>(run: () => T): T;

package/generator/semantic/fragments.d.ts

@@ -22,7 +22,16 @@ export interface FragmentContext extends QueryContext {
     /** The API template root (the option, or the shipped templates). */
     templateRoot(): string;
 }
-/** The recorder scope of a fragment request: its phase kind and its unit key. */
+/**
+ * The recorder scope of a fragment request: its phase kind and its unit key.
+ * @param request
+ */
 export declare function fragmentScope(request: SemanticFragmentRequest): [FootprintScopeKind, string];
-/** Renders one fragment request against the snapshot, recording its reads in `files`. */
+/**
+ * Renders one fragment request against the snapshot, recording its reads in `files`.
+ * @param state
+ * @param request
+ * @param files
+ * @param context
+ */
 export declare function renderFragment(state: Snapshot, request: SemanticFragmentRequest, files: TrackedFiles, context: FragmentContext): SemanticFragment;

package/generator/templates/api/class-declaration.html.nunj

@@ -7,10 +7,12 @@
 {% import "helpers/modifier.html.nunj" as modifierMacro %}
 
 {% block overview %}
+    {#- The new engine sets `hideProtectedMembers` for `api.protectedMembers: false`; the legacy engine never does. #}
+    {%- set memberScopes = ["public"] if hideProtectedMembers else ["public", "protected"] -%}
     {%- set constructors = declaration.getConstructors() | filterByScope("public") | excludeByJsDocTags('internal') -%}
-    {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-    {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-    {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
+    {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+    {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+    {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
 
     {%- set staticProperties = allProperties | filterByStatic(true) -%}
     {%- set staticAccessors = allAccessors | filterByStatic(true) -%}

package/generator/templates/demo-app.ts.nunj

@@ -0,0 +1,37 @@
+// @ts-nocheck
+import {Routes} from '@angular/router';
+{%- for category in categories %}
+import {{ category[0] }} from '{{ category[1] }}';
+{%- endfor %}
+
+// The URL path of the demo pages, which the Vite host serves the demo application's page under.
+export const NG_DOC_DEMO_PATH = '{{ demoPath }}';
+
+// Every demo page, which a build without prerendering writes as a copy of the demo application's
+// page, so that static hosts serve it without a fallback.
+export const NG_DOC_DEMO_PAGES: string[] = {{ demoPages | dump }};
+
+// The routes of the demo application: one lazy route per guide with demo pages, under the
+// providers of its categories, as on the documentation pages.
+export const NG_DOC_DEMO_ROUTES: Routes = [
+  {%- for page in pages %}
+  {
+    path: '{{ page.path | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}',
+    {%- if page.categories.length %}
+    providers: [
+      {%- for id in page.categories %}
+      ...({{ id }}.providers ?? []),
+      {%- endfor %}
+    ],
+    {%- endif %}
+    loadChildren: () => import('{{ page.importPath }}'),
+  },
+  {%- endfor %}
+];
+
+// The module of `demoProviders`, which only the demo application imports.
+{%- if providersImport %}
+export const NG_DOC_DEMO_PROVIDERS = () => import('{{ providersImport }}');
+{%- else %}
+export const NG_DOC_DEMO_PROVIDERS = undefined;
+{%- endif %}

package/generator/templates/demo-routes.ts.nunj

@@ -0,0 +1,23 @@
+// @ts-nocheck
+import {Routes} from '@angular/router';
+import {NgDocDemoHostComponent} from '@ng-doc/app/demo-app';
+import entry from '{{ entryImport }}';
+
+// The demo pages of one guide: one route per demo, under the page's providers, as the demos have
+// them on the page.
+const routes: Routes = [{
+  path: '',
+  providers: [...(entry.providers ?? [])],
+  children: [
+    {%- for demo in demos %}
+    {
+      path: '{{ demo.name }}',
+      component: NgDocDemoHostComponent,
+      title: `{{ demo.title | toTemplateString }}`,
+      data: {ngDocDemo: entry.demos?.['{{ demo.name }}']},
+    },
+    {%- endfor %}
+  ],
+}];
+
+export default routes;

package/generator/templates/index.ts.nunj

@@ -1,2 +1,7 @@
 export * from './context';
 export * from './routes';
+{% if demoApplication -%}
+// Keeps the demo application's modules, the demo routes and the module of `demoProviders`, in the
+// application's Angular compilation, which compiles them: only the demo application imports them.
+import type {} from './demo-app';
+{% endif -%}

package/generator/templates/page-wrapper.ts.nunj

@@ -42,7 +42,11 @@ const routes: Routes = [{
 {%- endif %}
   path: '',
   component: PageWrapperComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
+  {#- No title: the route inherits the page's title from the route that loads it, and a second
+      copy of it would repeat it in a title strategy that joins the titles of the route. #}
+  data: {
+    ngDocPageType: '{{ pageType }}',
+  },
   children: [
     {%- for importPath, entry in entries  %}
     {
@@ -51,6 +55,7 @@ const routes: Routes = [{
       title: `{{ entry.title | toTemplateString }}`,
       data: {
         icon: '{{ entry.entry.icon }}',
+        ngDocTitle: 'tab',
       }
     },
     {%- endfor %}

package/generator/templates/page.ts.nunj

@@ -64,11 +64,20 @@ export class PageComponent extends NgDocRootPage {
     {%- if demoAssetsPath %}
   readonly demoAssets: NgDocDemoAssets = demoAssets;
     {%- endif %}
+    {#- The demo pages of the guide (Vite engine), and whether its demos are isolated by default. #}
+    {%- if demoRoute %}
+  readonly demoRoute: string = '{{ demoRoute | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}';
+      {%- if isolatedDemos %}
+  readonly isolatedDemos: boolean = true;
+      {%- endif %}
+    {%- endif %}
 
   constructor() {
     super();
   }
 }
+{#- The route has no title of its own: it inherits the title of its tab route, so a page's own
+    `route.title` is the only title here and wins over the generated one. #}
 {%- if contentSourceImport %}
 
 // The router shows the page only once its content has loaded, so the previous page stays on
@@ -79,7 +88,6 @@ const routes: Routes = [ɵwithNgDocContent({
     {%- endif %}
   path: '',
   component: PageComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
 }, pageContentSource)]
 {%- else %}
 
@@ -89,7 +97,6 @@ const routes: Routes = [{
     {%- endif %}
   path: '',
   component: PageComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
 }]
 {%- endif %}
 

package/generator/templates/routes.ts.nunj

@@ -20,9 +20,13 @@ export const NG_DOC_ROUTING: Routes = [
 	{
 		path: '{{ entry.item.route | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}',
 		title: `{{ entry.item.title | toTemplateString }}`,
-    {%- if entry.item.apiListSegment is defined %}
-    data: {ngDocApiListSegment: '{{ entry.item.apiListSegment | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}'},
-    {%- endif %}
+    {#- `ngDocTitle` names what the title belongs to, so a title strategy can compose the titles of
+        the route without repeating one (`provideNgDocTitle`). #}
+    data: {ngDocTitle: '{{ 'category' if entry.item.isCategory else 'page' }}'
+    {%- if entry.item.apiListSegment is defined -%}
+    , ngDocApiListSegment: '{{ entry.item.apiListSegment | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}'
+    {%- endif -%}
+    },
     {%- if entry.item.isCategory %}
     providers: [
       ...({{ entry.item.id }}.providers ?? []),

package/generator/templates/symbol/members.html.nunj

@@ -197,12 +197,14 @@
     </tr>
 {%- endmacro %}
 
-{% macro render(declaration) %}
+{#- `hideProtected` (the `api.protectedMembers: false` option) lists public class members only. #}
+{% macro render(declaration, hideProtected=false) %}
+    {%- set memberScopes = ["public"] if hideProtected else ["public", "protected"] -%}
     {%- if Node.isClassDeclaration(declaration) %}
         {%- set constructors = declaration.getConstructors() | filterByScope("public") | excludeByJsDocTags('internal') -%}
-        {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-        {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-        {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
+        {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+        {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+        {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
         {%- set staticProperties = allProperties | filterByStatic(true) -%}
         {%- set properties = allProperties | filterByStatic(false) -%}
         {%- set staticAccessors = allAccessors | filterByStatic(true) | groupAccessors -%}

package/generator/templates/symbol/page.html.nunj

@@ -69,7 +69,7 @@
         {{ overloadMacro.render(overloads) }}
     {% endif %}
 {% else %}
-    {{ membersMacro.render(declaration) }}
+    {{ membersMacro.render(declaration, hideProtectedMembers) }}
 {% endif %}
 
 {% include "parts/examples.html.nunj" %}

package/generator/vite/application-builder.js

@@ -7,6 +7,7 @@ import { Observable } from "rxjs";
 import { createServer as viteCreateServer } from "vite";
 
 // libs/builder/generator/vite/production.ts
+import { existsSync } from "node:fs";
 import { rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build as viteBuild } from "vite";
@@ -75,7 +76,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(
@@ -256,11 +258,13 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
   }
   const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
   if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const demoServerEntry = path.join(serverDirectory, "demo-server.mjs");
   const report = await timed(
     "Prerendered the routes",
     () => dependencies.prerender({
       browserDir: browser,
       serverEntry,
+      ...existsSync(demoServerEntry) && existsSync(path.join(browser, "ng-doc-demo.html")) ? { demoServerEntry } : {},
       routes: options.routes ?? [],
       discoverRoutes: options.discoverRoutes ?? true,
       ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
@@ -273,6 +277,7 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
 `
   );
   log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  for (const { route, message: message2 } of report.warnings ?? []) log(`Warning: ${route}: ${message2}`);
   if (report.errors.length) {
     log(`The application logged ${report.errors.length} error(s) while prerendering:`);
     for (const { route, message: message2 } of report.errors.slice(0, 10)) log(`  ${route}: ${message2}`);

package/generator/vite/application.d.ts

@@ -41,6 +41,14 @@ export interface NgDocViteApplicationOptions {
 export declare const NG_DOC_BROWSER_ENTRY = "/@ng-doc-application/browser.js";
 /** The module id of the server entry; `buildNgDocViteApplication` builds it into `server.mjs`. */
 export declare const NG_DOC_SERVER_ENTRY = "/@ng-doc-application/server.js";
+/** The URL of the demo application's browser entry, which its page loads. */
+export declare const NG_DOC_DEMO_ENTRY = "/@ng-doc-application/demo.js";
+/** The module id of the demo application's server entry, built next to `server.mjs`. */
+export declare const NG_DOC_DEMO_SERVER_ENTRY = "/@ng-doc-application/demo-server.js";
+/** The page of the demo application, next to index.html in the build output. */
+export declare const NG_DOC_DEMO_PAGE = "ng-doc-demo.html";
+/** The name of the demo application's server entry in the server build (`demo-server.mjs`). */
+export declare const NG_DOC_DEMO_SERVER_NAME = "demo-server";
 interface ResolvedAsset {
     input: string;
     output: string;
@@ -77,6 +85,12 @@ export declare function matchAssets(assets: readonly ResolvedAsset[], base: stri
     file: string;
     relative: string;
 }>;
+/**
+ * The page of the demo application: the application's index.html with the demo application's
+ * root as its body, so it has the same head (base href, fonts, icons, theme script).
+ * @param index - The content of index.html.
+ */
+export declare function demoDocument(index: string): string;
 /** Sets `<base href>` to an absolute Vite base, or adds it at the start of `<head>`. */
 export declare function withBase(html: string, base: string): string;
 /**

package/generator/vite/demo-application.d.ts

@@ -0,0 +1,34 @@
+/** The generated module of the demo application, in the output root (`demo-app.ts.nunj`). */
+export declare const DEMO_APPLICATION_MODULE = "demo-app.ts";
+/**
+ * The demo application of a generation: its generated module and the URL path of its pages.
+ * The NgDoc plugin publishes it to the application plugin (`NgDocDemoApplicationApi`).
+ */
+export interface NgDocDemoApplication {
+    /** The generated module (absolute), which exports the routes and the providers import. */
+    readonly module: string;
+    /** The URL path of the demo pages, relative to the base href, without slashes around it. */
+    readonly path: string;
+    /** Every demo page, relative to the base href (`<path>/<page route>/<demo name>`). */
+    readonly pages: readonly string[];
+}
+/**
+ * What the NgDoc plugin offers the application plugin through `api.ngDocDemoApplication`.
+ * @internal
+ */
+export interface NgDocDemoApplicationApi {
+    readonly schemaVersion: 1;
+    /**
+     * The demo application of the build's generation, generating first if the build has not yet: a
+     * build adds the demo page's input before it starts, when there is one.
+     */
+    resolve(): Promise<NgDocDemoApplication | undefined>;
+    /** The demo application of the current generation of the development server, if any. */
+    current(): Promise<NgDocDemoApplication | undefined>;
+}
+/**
+ * Reads the demo application from a committed output root: a generation writes `demo-app.ts`
+ * only when a guide has demo pages, and that module names the URL path of the pages.
+ * @param outputRoot - The output root of the published generation.
+ */
+export declare function readDemoApplication(outputRoot: string): Promise<NgDocDemoApplication | undefined>;

package/generator/vite/dev-server-builder.js

@@ -7,6 +7,7 @@ import { Observable } from "rxjs";
 import { createServer as viteCreateServer } from "vite";
 
 // libs/builder/generator/vite/production.ts
+import { existsSync } from "node:fs";
 import { rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build as viteBuild } from "vite";
@@ -75,7 +76,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(
@@ -256,11 +258,13 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
   }
   const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
   if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const demoServerEntry = path.join(serverDirectory, "demo-server.mjs");
   const report = await timed(
     "Prerendered the routes",
     () => dependencies.prerender({
       browserDir: browser,
       serverEntry,
+      ...existsSync(demoServerEntry) && existsSync(path.join(browser, "ng-doc-demo.html")) ? { demoServerEntry } : {},
       routes: options.routes ?? [],
       discoverRoutes: options.discoverRoutes ?? true,
       ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
@@ -273,6 +277,7 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
 `
   );
   log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  for (const { route, message: message2 } of report.warnings ?? []) log(`Warning: ${route}: ${message2}`);
   if (report.errors.length) {
     log(`The application logged ${report.errors.length} error(s) while prerendering:`);
     for (const { route, message: message2 } of report.errors.slice(0, 10)) log(`  ${route}: ${message2}`);

package/generator/vite/host-updates.d.ts

@@ -15,13 +15,53 @@ export interface InitialCompilationInventory {
     }>;
     isCurrent(): boolean;
 }
+/**
+ * What the host does for the coordinator when a burst ends (see {@link HostUpdateCoordinator}).
+ */
+export interface HostUpdateRecovery {
+    /** Logs a warning: the summary of the host update timeouts a burst held back. */
+    warn(message: string): void;
+    /**
+     * Reports `file` again as its watcher would have: a generated output whose report never
+     * completed its generation's expectation (lost, or its hook timed out and threw).
+     */
+    replay(file: string, type: 'create' | 'update' | 'delete'): void;
+    /** Re-observes every recorded input before the next generation (`BuildSession.rescan`). */
+    rescan(): void;
+}
+/** How long a host update waits for the publication's host obligations to drain. */
+export declare const HOST_COMPLETION_TIMEOUT_MS = 30000;
+/** Hot updates within {@link HOST_BURST_WINDOW_MS} that open a burst of file events. */
+export declare const HOST_BURST_EVENTS = 1000;
+/** The window in which {@link HOST_BURST_EVENTS} hot updates open a burst. */
+export declare const HOST_BURST_WINDOW_MS = 1000;
+/** A burst ends after this long without a hot update or a host update timeout. */
+export declare const HOST_BURST_QUIET_MS = 2000;
 export declare function observePhysicalState(file: string, read?: () => string | Promise<string>): Promise<PhysicalState>;
 /** A synchronous metadata-only stamp preserves the event-time identity without starting I/O queues. */
 export declare function observePhysicalVersion(file: string): string | undefined;
-/** Coordinates committed generator versions with Vite's client hot-update pipeline. */
+/**
+ * Coordinates committed generator versions with Vite's client hot-update pipeline.
+ *
+ * Bursts: thousands of file events at once (a script or a checkout writing many files) flood
+ * Vite's hot-update pipeline and the watcher. Host updates then wait longer than
+ * {@link HOST_COMPLETION_TIMEOUT_MS}, a hook that timed out leaves its generation's obligation
+ * open (nothing reports that output again, so no reload is ever sent), and chokidar may lose
+ * events without any signal. So a burst is tracked: it opens with {@link HOST_BURST_EVENTS} hot
+ * updates of files outside the output root (once the first generation is published) within
+ * {@link HOST_BURST_WINDOW_MS}, or with a host update timeout, and ends after
+ * {@link HOST_BURST_QUIET_MS} without either. Only its first timeout is reported as it happens;
+ * the others are summed up in one warning when it ends. Then it takes one more pass: every
+ * generated output whose report never completed its expectation, and whose file is still what
+ * its generation wrote, is reported again (`HostUpdateRecovery.replay`), and every recorded
+ * input is re-observed (`HostUpdateRecovery.rescan`), so the newest edit is published even if
+ * its event was lost or its generation failed under the load. A replayed report is matched like
+ * any other: one that arrives twice is a repeat, so an edit still reloads once.
+ */
 export declare class HostUpdateCoordinator {
     private readonly notify;
     private readonly fail;
+    private readonly recovery?;
     private outputRoot?;
     private manifest?;
     private announcedManifest?;
@@ -43,7 +83,10 @@ export declare class HostUpdateCoordinator {
     private pendingGeneration?;
     private sequence;
     private disposed;
-    constructor(notify: () => void, fail: (error: Error) => void);
+    private burst?;
+    /** The start and the hot updates of the current burst-detection window. */
+    private window;
+    constructor(notify: () => void, fail: (error: Error) => void, recovery?: HostUpdateRecovery | undefined);
     seed(outputRoot: string, manifest: OutputManifest): void;
     initialCompilationInventory(): InitialCompilationInventory;
     started(generation: number, changes: FileChange[]): void;
@@ -141,5 +184,29 @@ export declare class HostUpdateCoordinator {
     private delta;
     private prune;
     private withTimeout;
+    /** Counts a hot update towards a burst of file events (see the class description). */
+    private hotUpdate;
+    /**
+     * 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.
+     */
+    private timedOut;
+    private openBurst;
+    /**
+     * 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.
+     */
+    private armBurst;
+    /**
+     * 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.
+     */
+    private recover;
 }
 export {};