@ng-doc/builder 22.0.0-beta.2 → 22.0.0

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

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+export declare const ANGULAR_COMPATIBILITY_FORMAT = "ng-doc-analog-2.8.0-resources-v1";
+export declare const ANGULAR_COMPILER_NAME = "@analogjs/vite-plugin-angular";
+/** Compatibility assertion for the tested compiler implementation; not an authenticity signature. */
+export declare function qualifyAngularPlugins(plugins: Plugin[]): Plugin[];
+export declare function assertAngularCompatibility(plugins: readonly Plugin[]): void;

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

@@ -0,0 +1,68 @@
+import type { HmrContext, Plugin, ViteDevServer } from 'vite';
+import { type HostUpdateTicket, type InitialCompilationInventory } from './host-updates.js';
+/**
+ * Whether a hot update is for a global style sheet or for a Sass file only global sheets use:
+ * every module of the file reaches, through style sheets alone, only virtual importers (ids
+ * starting with a NUL character, such as the application's browser entry). A component style
+ * sheet is served with a query (`?direct&ngcomp`) or imported by the component's TypeScript, so
+ * neither it nor a partial it uses ever matches.
+ * @param context - The hot update.
+ * @returns Whether only global style sheets depend on the file.
+ */
+export declare function globalStyleSheet(context: Pick<HmrContext, 'file' | 'modules'>): 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
+ * compiler's caches at once and joins its next pass instead of starting one, and `passes` counts
+ * its passes.
+ */
+export interface AnalogHostHooks {
+    claimFilesystemChange?: (file: string) => boolean;
+    readonly passes: number;
+}
+/**
+ * The patched compiler's hooks, when it exposes them.
+ * @param compiler The Analog compiler plugin.
+ */
+export declare function analogHostHooks(compiler: Plugin | undefined): AnalogHostHooks | undefined;
+export interface AngularCompositionBridge {
+    initialize(): Promise<void>;
+    initialCompilationInventory?(): InitialCompilationInventory | undefined;
+    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[];
+    /** A mark of the diagnostics recorded so far (see HostUpdateCoordinator.diagnosticMark). */
+    diagnosticMark?(): number;
+    /**
+     * Whether the add or unlink event of `file` joins the pass of its generation (a generated output
+     * or a watched description module).
+     */
+    claimsFilesystemChange?(file: string): boolean;
+    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>;
+    fail(error: Error): void;
+}
+export interface AngularComposition {
+    readonly plugins: Plugin[];
+    attachServer(server: ViteDevServer): void;
+    observeStartupUpdate(file: string, read: () => string | Promise<string>): void;
+    preflight(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * The id Analog keys its per-file maps with: forward slashes, as Vite normalizes ids. A resolved
+ * Windows path would miss them and compile a companion from stale bytes.
+ */
+export declare function analogFileId(file: string): string;
+/**
+ * The user error for an import Vite could not resolve, or undefined for any other error. Vite's
+ * import analysis reports it after every transform has run, so the Angular compiler is not at
+ * fault: the import names a module that does not exist, or one that only a tsconfig path mapping
+ * or a Vite alias the configuration lacks would resolve.
+ * @param cause - The error of a module transform.
+ */
+export declare function unresolvedImportError(cause: unknown): Error | undefined;
+/** Owns the supported Analog compiler hooks while retaining the complete factory result. */
+export declare function composeAngularPlugins(angularPlugins: readonly Plugin[], componentProbe: string, bridge: AngularCompositionBridge): AngularComposition;

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

@@ -0,0 +1,38 @@
+/**
+ * The first Angular release with the newer `@angular/build` transformer API. The bundled Analog 2.8
+ * picks the API it calls from the `@angular/compiler-cli` version (`>=22.2.0` calls
+ * `initializeHash()` and passes transform options), but takes the implementation from the
+ * `@angular/build` it resolves. When the two packages fall on different sides of this release,
+ * linking fails late with "Hash utility must be initialized" or a wrong call signature.
+ *
+ * The builder therefore takes `@angular/build` as a peer dependency, the application's own copy, and
+ * the engine checks at start that the pair agrees.
+ */
+export declare const TRANSFORM_OPTIONS_ANGULAR = "22.2.0";
+/**
+ * Whether the bundled Analog can drive this `@angular/build` from this `@angular/compiler-cli`: both
+ * versions are valid, of the same major, and on the same side of {@link TRANSFORM_OPTIONS_ANGULAR}.
+ * Different patch or minor releases on the same side work, as they do in the Angular CLI.
+ * @param compiler - The `@angular/compiler-cli` version.
+ * @param build - The `@angular/build` version.
+ */
+export declare function isConsistentAngularBuild(compiler: string, build: string): boolean;
+/**
+ * The version of the `@angular/compiler-cli` that the bundled Analog loads: the one resolved from
+ * NgDoc's own location. Undefined when none can be resolved.
+ */
+export declare function resolveAngularCompilerVersion(): string | undefined;
+/**
+ * The version of the `@angular/build` that the bundled Analog loads, resolved from NgDoc's own
+ * location like its `require('@angular/build/private')`. Undefined when none can be resolved.
+ */
+export declare function resolveAngularBuildVersion(): string | undefined;
+/**
+ * Fails when the Vite engine would run with an `@angular/compiler-cli` and an `@angular/build`
+ * that the bundled Analog cannot drive together ({@link isConsistentAngularBuild}), or without
+ * either of them. This happens when the package manager installs a second `@angular/build` for
+ * NgDoc instead of reusing the application's (an override, or a lockfile written before).
+ * @param compiler - The `@angular/compiler-cli` version; by default the one NgDoc resolves.
+ * @param build - The `@angular/build` version; by default the one NgDoc resolves.
+ */
+export declare function assertConsistentAngularBuild(compiler?: string | undefined, build?: string | undefined): void;

package/generator/vite/application-builder.js

@@ -0,0 +1,331 @@
+// libs/builder/generator/vite/application-builder.ts
+import { createBuilder } from "@angular-devkit/architect";
+
+// libs/builder/generator/vite/builders.ts
+import path2 from "node:path";
+import { Observable } from "rxjs";
+import { createServer as viteCreateServer } from "vite";
+
+// libs/builder/generator/vite/production.ts
+import { rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { build as viteBuild } from "vite";
+
+// libs/builder/generator/vite/angular-version.ts
+import { createRequire } from "node:module";
+var TRANSFORM_OPTIONS_ANGULAR = "22.2.0";
+var VERSION = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.+-]*)?$/;
+function parse(version) {
+  const match = VERSION.exec(version);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : void 0;
+}
+function usesTransformOptions([major, minor, patch]) {
+  const [lowMajor, lowMinor, lowPatch] = parse(TRANSFORM_OPTIONS_ANGULAR);
+  if (major !== lowMajor) return major > lowMajor;
+  if (minor !== lowMinor) return minor > lowMinor;
+  return patch >= lowPatch;
+}
+function isConsistentAngularBuild(compiler, build) {
+  const left = parse(compiler);
+  const right = parse(build);
+  if (!left || !right || left[0] !== right[0]) return false;
+  return usesTransformOptions(left) === usesTransformOptions(right);
+}
+function resolveVersion(name) {
+  try {
+    const manifest = createRequire(import.meta.url)(`${name}/package.json`);
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveAngularCompilerVersion() {
+  return resolveVersion("@angular/compiler-cli");
+}
+function resolveAngularBuildVersion() {
+  return resolveVersion("@angular/build");
+}
+function assertConsistentAngularBuild(compiler = resolveAngularCompilerVersion(), build = resolveAngularBuildVersion()) {
+  if (compiler && build && isConsistentAngularBuild(compiler, build)) return;
+  if (!compiler || !build) {
+    const missing = !compiler ? "@angular/compiler-cli" : "@angular/build";
+    throw new Error(
+      `[NGDOC_VITE_ANGULAR_VERSION] The NgDoc Vite engine needs @angular/compiler-cli and @angular/build of the application's Angular 22, but ${missing} is not installed. Install it in the application's devDependencies: npm i -D ${missing}@22.`
+    );
+  }
+  throw new Error(
+    `[NGDOC_VITE_ANGULAR_VERSION] NgDoc resolves @angular/compiler-cli ${compiler} and @angular/build ${build}, which belong to different Angular releases: the Vite engine drives @angular/build through the compiler's version, so both must be from before ${TRANSFORM_OPTIONS_ANGULAR} or both from ${TRANSFORM_OPTIONS_ANGULAR} or later. This usually means a second @angular/build was installed for NgDoc: check with \`npm ls @angular/build\`, then install the same Angular version for every @angular/* package (ng update @angular/core@22 @angular/cli@22) and reinstall, or deduplicate @angular/build (npm dedupe, an override or a resolution).`
+  );
+}
+
+// libs/builder/generator/vite/prerender.ts
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+function prerenderError(code, message2) {
+  return new Error(`[${code}] ${message2}`);
+}
+function heapArguments(execArgv) {
+  return execArgv.filter(
+    (item) => /^--(?:max-old-space-size|max-semi-space-size|stack-size)=/.test(item)
+  );
+}
+function prerenderNgDoc(options) {
+  const request = {
+    browserDir: options.browserDir,
+    serverEntry: options.serverEntry,
+    routes: [...options.routes ?? []],
+    discoverRoutes: options.discoverRoutes ?? true,
+    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs }
+  };
+  if (request.routeTimeoutMs !== void 0 && (!Number.isSafeInteger(request.routeTimeoutMs) || request.routeTimeoutMs < 1)) {
+    return Promise.reject(
+      prerenderError("NGDOC_PRERENDER_OPTION", "routeTimeoutMs must be a positive integer.")
+    );
+  }
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(prerenderError("NGDOC_PRERENDER_ABORTED", "Prerendering was aborted."));
+      return;
+    }
+    const child = fork(
+      fileURLToPath(options.entryUrl ?? new URL("./prerender-entry.js", import.meta.url)),
+      [],
+      // Keep the host's heap limits (a large site renders many routes in one process), nothing else.
+      { execArgv: heapArguments(process.execArgv), stdio: ["ignore", "inherit", "inherit", "ipc"] }
+    );
+    let reply;
+    const abort = () => child.kill("SIGKILL");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    child.on("message", (message2) => {
+      reply ??= message2;
+    });
+    child.once("error", (error) => {
+      options.signal?.removeEventListener("abort", abort);
+      reject(error);
+    });
+    child.once("exit", (code, signal) => {
+      options.signal?.removeEventListener("abort", abort);
+      if (options.signal?.aborted) {
+        reject(prerenderError("NGDOC_PRERENDER_ABORTED", "Prerendering was aborted."));
+      } else if (reply?.type === "result" && code === 0) {
+        resolve(reply.report);
+      } else if (reply?.type === "error") {
+        reject(new Error(reply.message));
+      } else {
+        reject(
+          prerenderError(
+            "NGDOC_PRERENDER_EXIT",
+            `The prerender process exited without a result (code=${String(code)}, signal=${String(signal)}).`
+          )
+        );
+      }
+    });
+    child.send(request, () => {
+    });
+  });
+}
+
+// libs/builder/generator/vite/vite-version.ts
+import { version as resolvedViteVersion } from "vite";
+var SUPPORTED_VITE_RANGE = "^8.3.0";
+var SUPPORTED_MAJOR = 8;
+var MINIMUM_MINOR = 3;
+function isSupportedViteVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+  if (!match) return false;
+  const [major, minor, patch] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (major !== SUPPORTED_MAJOR || minor < MINIMUM_MINOR) return false;
+  return !(match[4] && minor === MINIMUM_MINOR && patch === 0);
+}
+function assertSupportedViteVersion(found = resolvedViteVersion) {
+  if (found && isSupportedViteVersion(found)) return;
+  throw new Error(
+    `[NGDOC_VITE_VERSION] The NgDoc Vite engine requires vite ${SUPPORTED_VITE_RANGE}, but vite ${found || "(unknown version)"} is running. Install a supported release in the application's devDependencies: npm i -D vite@${SUPPORTED_VITE_RANGE}. The legacy builders (@ng-doc/builder:application and dev-server) do not use Vite.`
+  );
+}
+
+// libs/builder/generator/vite/production.ts
+var defaultDependencies = {
+  build: viteBuild,
+  prerender: prerenderNgDoc
+};
+function generationHandoff() {
+  const handoff = { schemaVersion: 1 };
+  return { name: "@ng-doc/vite:generation-handoff", api: { ngDocGeneration: handoff } };
+}
+function buildError(code, message2) {
+  return new Error(`[${code}] ${message2}`);
+}
+function applicationProbe() {
+  let found;
+  return {
+    plugin: {
+      name: "@ng-doc/vite:build-probe",
+      configResolved(config) {
+        const matches = config.plugins.filter(
+          (plugin) => plugin.api?.ngDocApplication?.schemaVersion === 1
+        );
+        if (matches.length > 1) {
+          throw buildError(
+            "NGDOC_VITE_APPLICATION",
+            "Expected at most one createNgDocApplicationPlugin in the Vite configuration."
+          );
+        }
+        found = matches[0]?.api.ngDocApplication;
+      }
+    },
+    api: () => found
+  };
+}
+async function buildNgDocViteApplication(options, dependencies = defaultDependencies) {
+  assertSupportedViteVersion();
+  assertConsistentAngularBuild();
+  const configFile = path.resolve(options.configFile);
+  const outputPath = path.resolve(options.outputPath);
+  const browser = path.join(outputPath, "browser");
+  const serverDirectory = path.join(outputPath, "server");
+  const serverEntry = path.join(serverDirectory, "server.mjs");
+  const mode = options.mode ?? "production";
+  const log = options.log ?? (() => {
+  });
+  const aborted = () => {
+    if (options.signal?.aborted)
+      throw buildError("NGDOC_VITE_BUILD_ABORTED", "The build was aborted.");
+  };
+  const timed = async (label, step) => {
+    const started = Date.now();
+    const value = await step();
+    log(`${label} in ${((Date.now() - started) / 1e3).toFixed(1)} s`);
+    return value;
+  };
+  let ssr = options.ssr;
+  const noServer = () => buildError(
+    "NGDOC_VITE_SERVER_ENTRY",
+    "Prerendering needs the server bundle: build it (ssr) from createNgDocApplicationPlugin with a server entry."
+  );
+  if (!options.skipBuild && options.prerender === true && options.ssr === false) throw noServer();
+  if (!options.skipBuild) {
+    const probe = applicationProbe();
+    const generation = generationHandoff();
+    await timed(
+      `Built the browser bundle into ${browser}`,
+      () => dependencies.build({
+        configFile,
+        mode,
+        plugins: [probe.plugin, generation],
+        build: { outDir: browser, emptyOutDir: true }
+      })
+    );
+    aborted();
+    const entry = probe.api()?.serverEntry;
+    ssr ??= entry !== void 0;
+    if (!ssr) {
+      await rm(serverDirectory, { recursive: true, force: true });
+      await rm(path.join(outputPath, "prerendered-routes.json"), { force: true });
+      if (options.prerender === true) throw noServer();
+    } else {
+      if (!entry) {
+        throw buildError(
+          "NGDOC_VITE_SERVER_ENTRY",
+          "The server build needs createNgDocApplicationPlugin with a server entry in the Vite configuration."
+        );
+      }
+      await timed(
+        `Built the server bundle into ${serverDirectory}`,
+        () => dependencies.build({
+          configFile,
+          mode,
+          plugins: [generation],
+          build: {
+            ssr: true,
+            outDir: serverDirectory,
+            emptyOutDir: true,
+            rolldownOptions: {
+              input: { server: entry },
+              output: {
+                format: "es",
+                entryFileNames: "[name].mjs",
+                chunkFileNames: "chunks/[name]-[hash].mjs"
+              }
+            }
+          }
+        })
+      );
+      aborted();
+    }
+  }
+  const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
+  if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const report = await timed(
+    "Prerendered the routes",
+    () => dependencies.prerender({
+      browserDir: browser,
+      serverEntry,
+      routes: options.routes ?? [],
+      discoverRoutes: options.discoverRoutes ?? true,
+      ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
+      ...options.signal ? { signal: options.signal } : {}
+    })
+  );
+  await writeFile(
+    path.join(outputPath, "prerendered-routes.json"),
+    `${JSON.stringify({ routes: report.routes, excluded: report.excluded }, null, 2)}
+`
+  );
+  log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  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}`);
+  }
+  return { browser, server: serverEntry, prerendered: report };
+}
+
+// libs/builder/generator/vite/builders.ts
+var defaultDependencies2 = {
+  build: (options) => buildNgDocViteApplication(options),
+  createServer: viteCreateServer
+};
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runViteApplicationBuilder(options, context, dependencies = defaultDependencies2, signal) {
+  const resolve = (value) => path2.resolve(context.workspaceRoot, value);
+  try {
+    await dependencies.build({
+      configFile: resolve(options.configFile),
+      outputPath: resolve(options.outputPath),
+      mode: options.mode ?? "production",
+      ...options.ssr === void 0 ? {} : { ssr: options.ssr },
+      ...options.prerender === void 0 ? {} : { prerender: options.prerender },
+      ...options.routes ? { routes: options.routes } : {},
+      ...options.discoverRoutes === void 0 ? {} : { discoverRoutes: options.discoverRoutes },
+      ...options.routeTimeout === void 0 ? {} : { routeTimeoutMs: options.routeTimeout },
+      log: (line) => context.logger.info(line),
+      ...signal ? { signal } : {}
+    });
+    return { success: true };
+  } catch (error) {
+    context.logger.error(message(error));
+    return { success: false, error: message(error) };
+  }
+}
+function viteApplicationBuilderOutputs(options, context, dependencies = defaultDependencies2) {
+  return new Observable((subscriber) => {
+    const controller = new AbortController();
+    void runViteApplicationBuilder(options, context, dependencies, controller.signal).then(
+      (output) => {
+        subscriber.next(output);
+        subscriber.complete();
+      }
+    );
+    return () => controller.abort();
+  });
+}
+
+// libs/builder/generator/vite/application-builder.ts
+var application_builder_default = createBuilder(
+  (options, context) => viteApplicationBuilderOutputs(options, context)
+);
+export {
+  application_builder_default as default
+};

package/generator/vite/application-builder.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "NgDoc Vite application",
+  "description": "Builds an Angular application with Vite and the NgDoc Vite engine: the browser bundle, the server bundle and every prerendered route.",
+  "type": "object",
+  "properties": {
+    "configFile": {
+      "type": "string",
+      "description": "The Vite configuration file, relative to the workspace root."
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "The output directory, relative to the workspace root: browser/, server/server.mjs and prerendered-routes.json."
+    },
+    "mode": {
+      "type": "string",
+      "description": "The Vite mode.",
+      "default": "production"
+    },
+    "ssr": {
+      "type": "boolean",
+      "description": "Build the server bundle. Defaults to true when the Vite configuration's createNgDocApplicationPlugin has a server entry."
+    },
+    "prerender": {
+      "type": "boolean",
+      "description": "Prerender every route into browser/. Defaults to true when the server bundle is built."
+    },
+    "routes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Routes prerendered in addition to the discovered ones, for example pages with route parameters."
+    },
+    "routeTimeout": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Fails a route that takes longer to render, in milliseconds. No limit by default."
+    },
+    "discoverRoutes": {
+      "type": "boolean",
+      "description": "Prerender every concrete route of the application's router configuration.",
+      "default": true
+    }
+  },
+  "required": ["configFile", "outputPath"],
+  "additionalProperties": false
+}

package/generator/vite/application.d.ts

@@ -0,0 +1,91 @@
+import type { Plugin } from 'vite';
+/**
+ * An asset entry, as in the `assets` option of Angular's application builder: a path (a file or
+ * a directory, relative to the workspace root) or a glob with its input and output directories.
+ */
+export type NgDocViteAssetPattern = string | {
+    glob: string;
+    input: string;
+    output?: string;
+    ignore?: string[];
+};
+/**
+ * The Angular application a Vite configuration builds. `browser`, `server`, `polyfills`, `styles`
+ * and `assets` mean what they mean in an `angular.json` build target; the target's other options
+ * have a Vite or Analog equivalent, which the plugin names when one is passed. Relative paths
+ * resolve against `workspaceRoot`.
+ */
+export interface NgDocViteApplicationOptions {
+    /** Absolute workspace root (default: the current directory). */
+    workspaceRoot?: string;
+    /** The project's source root: a path asset lands at its path relative to it (default: the directory of `browser`). */
+    sourceRoot?: string;
+    /** The browser entry, for example `src/main.ts`. */
+    browser: string;
+    /**
+     * The server entry, for example `src/main.server.ts`, whose default export bootstraps the
+     * application for the server. It enables the server build and prerendering.
+     */
+    server?: string;
+    /**
+     * Modules imported before the application, for example `['zone.js']`. The server entry keeps
+     * only `zone.js` (as `zone.js/node`) and `@angular/localize/init`, as the Angular CLI does.
+     */
+    polyfills?: string[];
+    /** Global style sheets, in order. */
+    styles?: string[];
+    /** Files copied into the build and served by the development server. */
+    assets?: NgDocViteAssetPattern[];
+}
+/** The URL of the browser entry module that the index page loads. */
+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";
+interface ResolvedAsset {
+    input: string;
+    output: string;
+    glob: string;
+    ignore: string[];
+}
+/** What `buildNgDocViteApplication` reads from the plugin of a resolved configuration. */
+export interface NgDocViteApplicationApi {
+    readonly schemaVersion: 1;
+    readonly serverEntry?: string;
+}
+/**
+ * Checks the keys of the options: an Angular CLI build option the plugin does not take fails with
+ * its Vite or Analog equivalent; an option without an effect is returned for a warning.
+ */
+export declare function checkOptionKeys(options: object): string[];
+/** The polyfills of the server entry: Angular keeps only zone.js (for Node) and localize. */
+export declare function serverPolyfills(polyfills: readonly string[]): string[];
+/**
+ * Resolves Angular CLI asset entries; a path entry is expanded against the file system.
+ */
+export declare function resolveAssets(assets: readonly NgDocViteAssetPattern[], workspaceRoot: string, sourceRoot: string): Promise<ResolvedAsset[]>;
+/**
+ * Every asset file by its output name; a later entry wins over an earlier one, as in Angular.
+ */
+export declare function collectAssets(assets: readonly ResolvedAsset[]): Promise<Map<string, string>>;
+/**
+ * The asset files a development request can name, the last matching entry first. An entry's
+ * output prefix and glob can match a file it does not have, so the server serves the first
+ * candidate that exists: a later entry wins over an earlier one only with a file, as in
+ * `collectAssets` and the Angular CLI.
+ */
+export declare function matchAssets(assets: readonly ResolvedAsset[], base: string, url: string): Array<{
+    file: string;
+    relative: 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;
+/**
+ * Builds and serves an Angular application with Vite the way the Angular CLI application builder
+ * does: the index page loads the polyfills, global styles and browser entry; assets are served in
+ * development and copied into the build; `<base href>` follows Vite's `base`. With a `server`
+ * entry, `NG_DOC_SERVER_ENTRY` is a self-contained server bundle for prerendering.
+ *
+ * Use it next to `createNgDocVitePlugin`. The Vite `root` is the directory of `index.html`.
+ */
+export declare function createNgDocApplicationPlugin(options: NgDocViteApplicationOptions): Plugin;
+export {};

package/generator/vite/assets.d.ts

@@ -0,0 +1,11 @@
+import type { Connect, Rolldown } from 'vite';
+import type { BuildResult, PublishedGeneratorConfiguration } from '../contracts.js';
+export declare class GeneratedAssetInventory {
+    private assets;
+    update(result: Extract<BuildResult, {
+        status: 'success';
+    }>, configuration: PublishedGeneratorConfiguration): void;
+    middleware(base: string): Connect.NextHandleFunction;
+    emit(context: Rolldown.PluginContext, bundle: Rolldown.OutputBundle): Promise<void>;
+    size(): number;
+}

package/generator/vite/bounded-close.d.ts

@@ -0,0 +1,33 @@
+import type { ViteDevServer } from 'vite';
+/** How long Vite's own close may still run once NgDoc has released what it owns. */
+export declare const HOST_CLOSE_BOUND_MS = 5000;
+export interface BoundedCloseOptions {
+    /**
+     * Starts NgDoc's complete disposal (idempotent). Part of it waits on work that Vite owns, such
+     * as an in-flight component probe transform, so it is bounded together with Vite's close.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Settles once NgDoc's own processes, watchers and output lease are released. Called after
+     * `dispose()` has started. It is never bounded: resolving close before it would leave children.
+     */
+    released(): Promise<unknown>;
+    warn(message: string): void;
+    error(message: string): void;
+    boundMs?: number;
+}
+/**
+ * Makes `server.close()` release NgDoc first and settle even when Vite's own close never does.
+ *
+ * Vite 7's dependency optimizer never settled the processing promise of a dependency whose first
+ * optimization close cancelled, so a pending request for it kept `DevEnvironment.close()` waiting
+ * forever. Vite 8 settles those promises on close; the bound stays as a safety net for any other
+ * request or plugin hook that never settles, and costs nothing when close does.
+ *
+ * The replacement always waits for NgDoc to release its own resources. It then gives Vite's close
+ * and the rest of NgDoc's disposal `boundMs`. On timeout it reports one diagnostic and resolves;
+ * a later failure of either is still logged. Failures within the bound are rethrown.
+ * @param server - The development server whose `close` is replaced.
+ * @param options - NgDoc's disposal, release signal, loggers and optional bound.
+ */
+export declare function boundServerClose(server: Pick<ViteDevServer, 'close'>, options: BoundedCloseOptions): void;

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

@@ -0,0 +1,21 @@
+import type { Plugin } from 'vite';
+/**
+ * Lets Analog's component update endpoint answer only the requests that answer an update event
+ * Analog sent; every other request gets an empty module, which applies no update.
+ *
+ * Angular's HMR code for a component loads `@ng/component?c=<file>@<class>&t=<timestamp>` on each
+ * `angular:component-update` event, with the event's timestamp, and once more whenever the module
+ * is evaluated, with `Date.now()`. The module Vite serves is always the latest compilation, so the
+ * load-time request never has anything to apply. Analog's endpoint answers it with the file's last
+ * update as soon as Vite has ever invalidated the module, and it keeps one update per file, that of
+ * the file's last component. Vite invalidates every module when the dependency optimizer reloads
+ * the page after it found a dependency late (a template-derived import, a demo's dependency). From
+ * then on, until the server restarts, each load applied the last component's metadata to every
+ * other component of its file, with the wrong namespaces: `Cannot read properties of undefined
+ * (reading 'MatButton')`, or another component's template.
+ *
+ * Analog's SSR path answers the load-time request of every module the same way, without any
+ * invalidation; the gate covers it too.
+ * @returns A serve-only plugin that must run before Analog's live reload plugin.
+ */
+export declare function createComponentUpdateGate(): Plugin;

package/generator/vite/configuration.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactSnapshot, PublishedGeneratorConfiguration } from '../contracts.js';
+export declare function requirePublishedConfiguration(snapshot: ArtifactSnapshot): PublishedGeneratorConfiguration;
+export declare function sameRuntimeConfiguration(left: PublishedGeneratorConfiguration, right: PublishedGeneratorConfiguration): boolean;