@ng-doc/builder 22.0.0 → 22.2.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,43 @@ 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`, `isolatedPlaygrounds`, `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.
+     * - `playgroundPages`: `all` builds the playground pages of every playground
+     *   (`isolatedPlaygrounds`, or `demoApplication` set); absent, only the guides with an isolated playground get them, and
+     *   no guide does when `pages` is `none`.
+     * - `isolatedPlaygrounds`: `true` when `isolatedPlaygrounds` is: every playground shows its demos
+     *   in iframes 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;
+        playgroundPages?: 'all';
+        isolatedPlaygrounds?: 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';
@@ -327,6 +366,11 @@ export interface PlaygroundDescriptor {
     /** Existing NgDocPlaygroundProperties shape with JSON-safe values, aliases and model inputs. */
     properties: Record<string, JsonValue>;
     content: Record<string, string>;
+    /**
+     * `true` when the playground's configuration in `ng-doc.page.ts` sets `isolated: true`, so its
+     * guide gets playground pages. Absent otherwise, so every other guide keeps its semantics.
+     */
+    isolated?: true;
 }
 export interface GuideSemantics {
     demos: Record<string, DemoAsset[]>;
@@ -608,6 +652,19 @@ 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[];
+    /**
+     * The guide's playground pages relative to its demo route (`playground/<id>/<target>`), with
+     * `demoModulePath`. Only written for a guide that has them.
+     */
+    playgroundPages?: 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

@@ -29,12 +29,17 @@ export declare const INCREMENTAL_PROGRAM_FLAG = "NGDOC_INCREMENTAL_PROGRAM";
 export declare const SHAPE_CLOSURE_FLAG = "NGDOC_SHAPE_CLOSURE";
 export declare const ANGULAR_SHARED_PASS_FLAG = "NGDOC_ANGULAR_SHARED_PASS";
 export declare const ANGULAR_STRUCTURAL_PASS_FLAG = "NGDOC_ANGULAR_STRUCTURAL_PASS";
+export declare const ANGULAR_DESCRIPTION_PASS_FLAG = "NGDOC_ANGULAR_DESCRIPTION_PASS";
+export declare const VITE_CONTENT_UPDATE_FLAG = "NGDOC_VITE_CONTENT_UPDATE";
 export declare const VITE_BUILD_HANDOFF_FLAG = "NGDOC_VITE_BUILD_HANDOFF";
+export declare const VITE_MODULELESS_SETTLE_FLAG = "NGDOC_VITE_MODULELESS_SETTLE";
 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,39 @@ export declare class OutputAssemblerImpl implements OutputAssembler {
     assemblePage(request: PageAssemblyRequest): PageAssembly;
     aggregate(request: AggregateRequest): AggregateAssembly;
     private guide;
+    /**
+     * Writes the guide's demo routes module when the guide gets demo or playground pages, and
+     * returns its path, the names of the demos that got a page and the playground pages (relative
+     * to the guide's demo route), or undefined.
+     *
+     * - Demo pages: with `pages: 'all'`, by default when its content has a demo with
+     *   `isolated: true`, and whenever the guide gets playground pages: the page then has a demo
+     *   route, and the runtime offers every demo of such a page its demo page.
+     * - Playground pages (`playground/<id>/<target>`, one per target of every playground of the
+     *   guide, under the page's providers and its generated playground classes): with
+     *   `playgroundPages: 'all'`, or by default when a `playground` action of its content or a
+     *   playground of its configuration has `isolated: true`.
+     */
+    private demoRoutes;
+    /**
+     * The playground pages of a guide, when it gets them (see `demoRoutes`): one per target of each
+     * playground, in the order of the guide's playgrounds and of `playgroundTargets`. A playground
+     * whose ID is no URL segment gets none, with a warning.
+     * @param request - The guide's assembly request.
+     * @param slots - The guide's content.
+     * @param diagnostics - Receives the warnings.
+     */
+    private playgroundRoutes;
     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
+     * or playground pages, under its categories' providers), every such page (`NG_DOC_DEMO_PAGES`)
+     * 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,43 @@
+// @ts-nocheck
+import {Routes} from '@angular/router';
+{%- if demos.length or not playgrounds.length %}
+import {NgDocDemoHostComponent} from '@ng-doc/app/demo-app';
+{%- endif %}
+{%- if playgrounds.length %}
+import {NgDocPlaygroundHostComponent} from '@ng-doc/app/components/playground';
+{%- endif %}
+import entry from '{{ entryImport }}';
+{%- if playgrounds.length %}
+import {PLAYGROUND_PROVIDERS} from '{{ playgroundsImport }}';
+{%- endif %}
+
+// The demo pages of one guide: one route per demo, under the page's providers, as the demos have
+// them on the page.
+{%- if playgrounds.length %}
+// Its playground pages: one route per target of each playground, which finds the generated
+// playground classes of the page through PLAYGROUND_PROVIDERS, as the page does.
+{%- endif %}
+const routes: Routes = [{
+  path: '',
+  providers: [{% if playgrounds.length %}PLAYGROUND_PROVIDERS, {% endif %}...(entry.providers ?? [])],
+  children: [
+    {%- for demo in demos %}
+    {
+      path: '{{ demo.name }}',
+      component: NgDocDemoHostComponent,
+      title: `{{ demo.title | toTemplateString }}`,
+      data: {ngDocDemo: entry.demos?.['{{ demo.name }}']},
+    },
+    {%- endfor %}
+    {%- for playground in playgrounds %}
+    {
+      path: '{{ playground.path }}',
+      component: NgDocPlaygroundHostComponent,
+      title: `{{ playground.title | toTemplateString }}`,
+      data: {ngDocPlayground: {{ playground.data | dump }}},
+    },
+    {%- 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,24 @@ export class PageComponent extends NgDocRootPage {
     {%- if demoAssetsPath %}
   readonly demoAssets: NgDocDemoAssets = demoAssets;
     {%- endif %}
+    {#- The demo and playground pages of the guide (Vite engine), and whether its demos and
+        playgrounds are isolated by default. #}
+    {%- if demoRoute %}
+  readonly demoRoute: string = '{{ demoRoute | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}';
+      {%- if isolatedDemos %}
+  readonly isolatedDemos: boolean = true;
+      {%- endif %}
+      {%- if isolatedPlaygrounds %}
+  readonly isolatedPlaygrounds: 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 +92,6 @@ const routes: Routes = [ɵwithNgDocContent({
     {%- endif %}
   path: '',
   component: PageComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
 }, pageContentSource)]
 {%- else %}
 
@@ -89,7 +101,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/angular/analog-provenance.json

@@ -858,7 +858,7 @@
     },
     {
       "id": "vite",
-      "owner": "peer vite@8.3.2"
+      "owner": "peer vite@8.3.3"
     }
   ],
   "encounteredStaticExternals": [

package/generator/vite/angular-composition.d.ts

@@ -10,6 +10,17 @@ import { type HostUpdateTicket, type InitialCompilationInventory } from './host-
  * @returns Whether only global style sheets depend on the file.
  */
 export declare function globalStyleSheet(context: Pick<HmrContext, 'file' | 'modules'>): boolean;
+/**
+ * Whether a hot update's hooks hand Vite anything to do once they return: a module to update, or
+ * (for an HTML file without modules) the page reload Vite sends itself. Only such a hot update
+ * has to wait for the newest publication before it returns; a module-less one settles once it is
+ * acknowledged (`HostUpdateCoordinator.settle`).
+ * @param file - The hot update's file.
+ * @param modules - The modules Vite updates after this hook: what the hook returned, or the
+ *   context's modules when it returned nothing.
+ * @returns Whether Vite updates or reloads anything for the hot update.
+ */
+export declare function handsViteModules(file: string, modules: readonly unknown[]): boolean;
 /**
  * The hooks NgDoc's patched Analog compiler exposes as `api.ngDocHost` (the
  * `generation-claimed-filesystem-*` changes): a claimed add or unlink event invalidates the
@@ -31,6 +42,15 @@ export interface AngularCompositionBridge {
     start(file: string, read: () => string | Promise<string>): HostUpdateTicket;
     /** Other TypeScript outputs to compile in this ready ticket's pass (see compilerCompanions). */
     companions?(ticket: HostUpdateTicket): string[];
+    /**
+     * Whether the generation of this committed source update still has a generated TypeScript
+     * update to compile (see HostUpdateCoordinator.generationPass).
+     */
+    generationPass?(ticket: HostUpdateTicket): boolean;
+    /** Whether `file` is a description module the generator watches. */
+    descriptionModule?(file: string): boolean;
+    /** Whether `file` is a generated output. */
+    generated?(file: string): boolean;
     /** A mark of the diagnostics recorded so far (see HostUpdateCoordinator.diagnosticMark). */
     diagnosticMark?(): number;
     /**
@@ -41,7 +61,11 @@ export interface AngularCompositionBridge {
     acknowledge(ticket: HostUpdateTicket, resourceWitness: boolean, compilerPass?: boolean, recoverBefore?: number): Promise<void>;
     diagnostic(ticket: HostUpdateTicket, error: Error): void;
     committed(ticket: HostUpdateTicket): Promise<void>;
-    settle(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Settles the hot update (see HostUpdateCoordinator.settle). `modules` is false when its hooks
+     * hand Vite nothing to update ({@link handsViteModules}); omitted, it is true.
+     */
+    settle(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     fail(error: Error): void;
 }
 export interface AngularComposition {

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/content-updates.d.ts

@@ -0,0 +1,62 @@
+import type { HtmlTagDescriptor, ViteDevServer, WebSocketClient } from 'vite';
+import type { AnnouncedChange } from './host-updates.js';
+/** The custom HMR event that carries a content update to the NgDoc client of a page. */
+export declare const CONTENT_UPDATE_EVENT = "ng-doc:content-update";
+/** The custom HMR event a page's NgDoc client sends once it listens for content updates. */
+export declare const CONTENT_CLIENT_EVENT = "ng-doc:content-client";
+/** The version of the content update messages; a client announces the version it reads. */
+export declare const CONTENT_UPDATE_VERSION = 1;
+/** A content update as the server sends it to a client. */
+export interface ContentUpdateMessage {
+    readonly version: typeof CONTENT_UPDATE_VERSION;
+    /** The URLs to import the changed content modules from, each with a fresh timestamp. */
+    readonly modules: readonly string[];
+    /** Whether the search index changed. */
+    readonly search: boolean;
+}
+/** What a content-only publication changed. */
+export interface ContentChanges {
+    /** The changed content modules (`*.content.mjs`), absolute, in path order. */
+    readonly modules: readonly string[];
+    /** Whether the search index changed. */
+    readonly search: boolean;
+}
+/**
+ * The page's NgDoc development client, a module script Vite serves with a hot context. It imports
+ * the changed content modules again and hands their payloads to the NgDoc runtime as a cancelable
+ * window event (`@ng-doc/app`'s `ɵNG_DOC_CONTENT_UPDATE_EVENT`, the same name). The runtime
+ * cancels it once it applied them; otherwise (no NgDoc runtime on the page, a payload it cannot
+ * read) and on any failure the client reloads the page, as it did before. Updates apply one at a
+ * time, in the order they arrive.
+ */
+export declare const CONTENT_UPDATE_CLIENT: string;
+/**
+ * The tag that adds the NgDoc development client to a page the development server serves.
+ * Vite turns an inline module script into a module of its own, with a hot context.
+ * @param html The page.
+ * @returns The tag, or none when the page carries the client or the switch is off.
+ */
+export declare function contentUpdateClientTags(html: string): HtmlTagDescriptor[];
+/** Whether content updates are on (`NGDOC_VITE_CONTENT_UPDATE`). */
+export declare function contentUpdatesEnabled(): boolean;
+/**
+ * What a reload announces, when it changes only content: every changed file is an existing
+ * content module (`*.content.mjs`) whose bytes changed, the search index or the keyword map
+ * (which no page reads). Anything else (a TypeScript module, a created or deleted file, another
+ * asset, the API lists) takes a full reload.
+ * @param changes The files that differ from the last announcement.
+ * @param assetDirectory The asset directory, relative to the output root.
+ * @returns The content changes, or `undefined` for a full reload.
+ */
+export declare function contentOnly(changes: readonly AnnouncedChange[] | undefined, assetDirectory: string): ContentChanges | undefined;
+/**
+ * Sends a content update. Each client that announced its NgDoc client gets the changed content
+ * modules it may have loaded (those in the client module graph: a module nobody imported loads
+ * afresh anyway); every other client reloads, as before. Without any client the reload is sent
+ * as Vite buffers it, so a page that connects later reloads.
+ * @param server The development server.
+ * @param clients The clients that announced the NgDoc client.
+ * @param changes The content changes.
+ * @param timestamp A timestamp no earlier update used, so the browser imports new modules.
+ */
+export declare function sendContentUpdate(server: ViteDevServer, clients: WeakSet<WebSocketClient>, changes: ContentChanges, timestamp: number): void;