@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/README.md

@@ -11,7 +11,7 @@ import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-type
 import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
 ```
 
-- The main entry is types only. Importing it at run time fails, on purpose.
+- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
 - `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

package/lib/packages/ngdpbase-types/index.d.ts

@@ -15,7 +15,7 @@
  * only, so the published entry carries no JavaScript.
  */
 export type { AddonModule, AddonManifest, AddonListing } from '../../src/managers/AddonsManager.js';
-export type { AddonHost, PersonSwitchSetter } from '../../src/utils/addonHost.js';
+export type { AddonHost, AddonIceDeclaration, PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export type { WikiEngine } from '../../src/types/WikiEngine.js';
 export type { ApiContext } from '../../src/context/ApiContext.js';
 export type { ActorContext } from '../../src/context/ActorContext.js';
@@ -28,8 +28,15 @@ export type { JobRunContext } from '../../src/managers/BackgroundJobManager.js';
 export type { default as DatabaseManager, AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
 export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
-export type { default as ExportManager } from '../../src/managers/ExportManager.js';
+export type { default as ExportManager, PdfOptions, PdfMargin, PdfPageSize, PdfUnavailableError } from '../../src/managers/ExportManager.js';
+export type { default as EmailManager, SendOptions, MailAttachment, AttachmentRefusedError } from '../../src/managers/EmailManager.js';
 export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';
+export type { default as PageManager } from '../../src/managers/PageManager.js';
+export type { PageAction } from '../../src/utils/pageUrl.js';
+export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
+export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
+export type { default as ImportManager } from '../../src/managers/ImportManager.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';

package/lib/packages/ngdpbase-types/testing.d.ts

@@ -4,7 +4,7 @@
 import ExportManager from '../../src/managers/ExportManager.js';
 import { type AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
 import { type SqliteHandle } from '../../src/providers/SqliteDatabaseProvider.js';
-import { buildAddonHost as buildHost, type AddonHost, type PersonSwitchSetter } from '../../src/utils/addonHost.js';
+import { buildAddonHost as buildHost, type AddonHost, type AddonIceDeclaration, type PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export { formatters } from '../../src/managers/PluginManager.js';
 /**
  * Core's `buildAddonHost`, with the audit registry bound to this add-on's
@@ -19,9 +19,13 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *   test (#1963); a site binds core's setter. Without one it refuses.
  * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
  *   names the system principal for `host.systemContext`; without one it is
- *   core's fallback principal
+ *   core's fallback principal. Its `ImportManager` (a real one, or a
+ *   stand-in) is where `host.registerShim` and `host.registerReceiver` register
+ * @param manifest - Optional: the add-on's manifest (the `ngdpbase` block of
+ *   its package.json); its `shims` and `receivers` are the names the host lets
+ *   it register (#1979)
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof buildHost>[3]): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof buildHost>[3], manifest?: AddonIceDeclaration | null): AddonHost;
 /** The add-on whose declaration a test database is checked against: its slug and its own `config/default-config.json`. */
 export interface AddonTestDatabaseDeclarer {
     slug: string;

package/lib/packages/ngdpbase-types/testing.js

@@ -18,11 +18,15 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *   test (#1963); a site binds core's setter. Without one it refuses.
  * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
  *   names the system principal for `host.systemContext`; without one it is
- *   core's fallback principal
+ *   core's fallback principal. Its `ImportManager` (a real one, or a
+ *   stand-in) is where `host.registerShim` and `host.registerReceiver` register
+ * @param manifest - Optional: the add-on's manifest (the `ngdpbase` block of
+ *   its package.json); its `shims` and `receivers` are the names the host lets
+ *   it register (#1979)
  */
-export function buildAddonHost(slug, addonDefaults, setEnabledForPerson, engine) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson, engine, manifest) {
     bindAuditEvents((key, fallback) => addonDefaults[key] ?? fallback);
-    return buildHost(slug, addonDefaults, setEnabledForPerson, engine);
+    return buildHost(slug, addonDefaults, setEnabledForPerson, engine, manifest);
 }
 /**
  * An add-on's database as `DatabaseManager.openAddonDatabase` returns it, in

package/lib/src/converters/DocxConverter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Word (.docx) converter (#1131) — the first BINARY source format.
+ *
+ * Deliberately thin: mammoth (pure JS, no native deps) turns the document
+ * into clean HTML, and ImportManager routes that HTML through the EXISTING
+ * html→NCM path — turndown, §2.4 link normalization, §2.1 table up-convert,
+ * §2.2 image localization, and the #1125 footnote transfer all come from
+ * the funnel, not from here. The converter's own contribution is the
+ * `convertBuffer` contract that text converters don't need.
+ *
+ * Known limitation, recorded on the issue: docx footnotes arrive as
+ * mammoth's anchor/list HTML rather than `[^id]` markdown, so they survive
+ * as ordinary links instead of sidecar records. Mapping them is a follow-up.
+ */
+import type { IContentConverter, ConversionResult } from './IContentConverter.js';
+export default class DocxConverter implements IContentConverter {
+    readonly formatId = "docx";
+    readonly formatName = "Word (.docx)";
+    readonly fileExtensions: string[];
+    /**
+     * Never claims by content (#879 extension-first): a docx read as UTF-8 is
+     * zip garbage, and probing it risks both false negatives and another
+     * converter mis-claiming. detectFormat's extension pass finds this
+     * converter; the content pass must stay silent.
+     */
+    canHandle(_content: string, _filename: string): boolean;
+    /** A docx has no meaningful text form — the binary contract is the only door. */
+    convert(_content: string): ConversionResult;
+    convertBuffer(buffer: Buffer): Promise<ConversionResult>;
+}

package/lib/src/converters/MarkdownConverter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Markdown Pass-Through Converter
+ *
+ * Imports `.md` and `.markdown` files into ngdpbase without format conversion.
+ * Parses existing YAML frontmatter and exposes it as metadata so ImportManager
+ * can preserve recognised fields (title, slug, uuid, audience, system-category,
+ * user-keywords, author, source-url, etc.) and generate fresh values for any
+ * that are missing (uuid, lastModified).
+ *
+ * @module MarkdownConverter
+ */
+import { IContentConverter, ConversionResult } from './IContentConverter.js';
+declare class MarkdownConverter implements IContentConverter {
+    readonly formatId = "markdown";
+    readonly formatName = "Markdown";
+    readonly fileExtensions: string[];
+    /**
+     * Parse frontmatter and return body content unchanged.
+     *
+     * Existing frontmatter fields are extracted as metadata so ImportManager's
+     * `buildFrontmatter` can honour them (e.g. preserve a uuid that already
+     * exists, carry over audience restrictions, etc.).
+     */
+    convert(content: string): ConversionResult;
+    /**
+     * Accepts .md / .markdown by extension; also matches content that starts
+     * with a YAML frontmatter block or a Markdown heading.
+     */
+    canHandle(content: string, filename: string): boolean;
+}
+export default MarkdownConverter;

package/lib/src/export/ChromeServicePdfProvider.d.ts

@@ -0,0 +1,52 @@
+import { type Transport } from '../http/guardedFetch.js';
+import type { Resolver } from '../http/guardedLookup.js';
+import type { EgressPolicy } from '../http/ssrf.js';
+import { type PdfPageSize, type ResolvedPdfOptions } from './pdfEngine.js';
+import type { PdfProvider, PdfRenderRequest, PdfRendered } from './PdfProvider.js';
+/** Gotenberg's HTML → PDF route, relative to the configured service URL. */
+export declare const GOTENBERG_HTML_ROUTE = "forms/chromium/convert/html";
+/**
+ * The named page sizes in inches, as Chromium's (and Playwright's) print uses
+ * them, so a service render and a local one get the same paper.
+ */
+export declare const PAPER_INCHES: Record<PdfPageSize, readonly [number, number]>;
+export interface ChromeServiceSettings {
+    /** `ngdpbase.export.pdf.provider.chrome-service.url` — the service's base URL. */
+    url: string;
+    /** The site's egress policy (`resolveEgressPolicy`). */
+    policy: EgressPolicy;
+    /** The largest answer accepted, in bytes. */
+    maxBytes: number;
+}
+/** Hooks for tests; a site passes nothing. */
+export interface ChromeServiceDeps {
+    transport?: Transport;
+    resolver?: Resolver;
+    normalize?: (pdf: Uint8Array, timeoutMs: number) => Promise<Uint8Array>;
+}
+/**
+ * The form fields for one render. Every margin is sent, `0` when the caller
+ * set none, because Gotenberg's own default margin is not zero and a local
+ * render's is.
+ *
+ * @param options - The validated options
+ */
+export declare function gotenbergFields(options: ResolvedPdfOptions): Array<[string, string]>;
+/**
+ * A `multipart/form-data` body: the fields, then the document as `files`
+ * named `index.html` (the name Gotenberg's HTML route requires).
+ *
+ * @param html - The document
+ * @param fields - Name and value pairs
+ * @param boundary - The part boundary
+ */
+export declare function multipartBody(html: string, fields: Array<[string, string]>, boundary: string): Buffer;
+/** The service URL with the route appended (a path on the URL is kept). */
+export declare function serviceEndpoint(base: string): string;
+export declare class ChromeServicePdfProvider implements PdfProvider {
+    private readonly settings;
+    private readonly deps;
+    readonly name: "chrome-service";
+    constructor(settings: ChromeServiceSettings, deps?: ChromeServiceDeps);
+    render({ html, options, timeoutMs }: PdfRenderRequest): Promise<PdfRendered>;
+}

package/lib/src/export/ChromeServicePdfProvider.js

@@ -0,0 +1,153 @@
+/**
+ * `chrome-service` (#1974): a separate Chromium service reached by URL, for a
+ * site whose own image carries no browser (the Docker image). It speaks
+ * Gotenberg's HTML route: `POST <url>/forms/chromium/convert/html`, a
+ * multipart form with the document as `files` (`index.html`) and the page
+ * settings as fields; the answer is the PDF.
+ *
+ * - Outbound through `guardedFetch` under the site's egress policy. A service
+ *   on the LAN or in the cluster is on a private address, which the policy
+ *   refuses until the operator allows its range
+ *   (`ngdpbase.security.egress.allowed-ranges`); loopback is never allowed.
+ * - The whole request is bounded by `ngdpbase.export.pdf.timeout-ms`, and the
+ *   answer by `ngdpbase.export.pdf.provider.chrome-service.max-bytes`.
+ * - The PDF goes through the same `normalizePdf` pass a local render gets, in
+ *   a child process, so the same HTML gives the same bytes for a given service
+ *   version.
+ *
+ * What the service's Chromium may load (remote images, files) is the
+ * service's own setting, not this request's; the setup guide says how to
+ * lock it down.
+ */
+import { randomUUID } from 'node:crypto';
+import { guardedFetch } from '../http/guardedFetch.js';
+import { PdfUnavailableError, normalizePdfInChild } from './pdfEngine.js';
+/** Gotenberg's HTML → PDF route, relative to the configured service URL. */
+export const GOTENBERG_HTML_ROUTE = 'forms/chromium/convert/html';
+/**
+ * The named page sizes in inches, as Chromium's (and Playwright's) print uses
+ * them, so a service render and a local one get the same paper.
+ */
+export const PAPER_INCHES = {
+    Letter: [8.5, 11],
+    Legal: [8.5, 14],
+    Tabloid: [11, 17],
+    Ledger: [17, 11],
+    A0: [33.1, 46.8],
+    A1: [23.4, 33.1],
+    A2: [16.54, 23.4],
+    A3: [11.7, 16.54],
+    A4: [8.27, 11.7],
+    A5: [5.83, 8.27],
+    A6: [4.13, 5.83]
+};
+/**
+ * The form fields for one render. Every margin is sent, `0` when the caller
+ * set none, because Gotenberg's own default margin is not zero and a local
+ * render's is.
+ *
+ * @param options - The validated options
+ */
+export function gotenbergFields(options) {
+    const [width, height] = PAPER_INCHES[options.format];
+    const margin = (side) => options.margin[side] ?? '0';
+    return [
+        ['paperWidth', `${width}in`],
+        ['paperHeight', `${height}in`],
+        ['marginTop', margin('top')],
+        ['marginRight', margin('right')],
+        ['marginBottom', margin('bottom')],
+        ['marginLeft', margin('left')],
+        ['preferCssPageSize', 'true'],
+        ['printBackground', String(options.printBackground)]
+    ];
+}
+/**
+ * A `multipart/form-data` body: the fields, then the document as `files`
+ * named `index.html` (the name Gotenberg's HTML route requires).
+ *
+ * @param html - The document
+ * @param fields - Name and value pairs
+ * @param boundary - The part boundary
+ */
+export function multipartBody(html, fields, boundary) {
+    const parts = [];
+    for (const [name, value] of fields) {
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`));
+    }
+    parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="files"; filename="index.html"\r\nContent-Type: text/html; charset=utf-8\r\n\r\n`));
+    parts.push(Buffer.from(html, 'utf8'));
+    parts.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+    return Buffer.concat(parts);
+}
+/** The service URL with the route appended (a path on the URL is kept). */
+export function serviceEndpoint(base) {
+    const url = new URL(base);
+    if (!url.pathname.endsWith('/'))
+        url.pathname += '/';
+    return new URL(GOTENBERG_HTML_ROUTE, url).toString();
+}
+export class ChromeServicePdfProvider {
+    settings;
+    deps;
+    name = 'chrome-service';
+    constructor(settings, deps = {}) {
+        this.settings = settings;
+        this.deps = deps;
+    }
+    async render({ html, options, timeoutMs }) {
+        const { url, policy, maxBytes } = this.settings;
+        if (!url)
+            throw new PdfUnavailableError('ngdpbase.export.pdf.provider.chrome-service.url is not set');
+        let endpoint;
+        try {
+            endpoint = serviceEndpoint(url);
+        }
+        catch {
+            throw new PdfUnavailableError('ngdpbase.export.pdf.provider.chrome-service.url is not a URL');
+        }
+        const where = new URL(endpoint).origin;
+        const boundary = `ngdpbase-pdf-${randomUUID()}`;
+        const body = multipartBody(html, gotenbergFields(options), boundary);
+        const started = Date.now();
+        let response;
+        try {
+            response = await withDeadline(guardedFetch(endpoint, {
+                policy,
+                method: 'POST',
+                body,
+                headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}`, Accept: 'application/pdf' },
+                timeoutMs,
+                maxBytes,
+                ...(this.deps.transport ? { transport: this.deps.transport } : {}),
+                ...(this.deps.resolver ? { resolver: this.deps.resolver } : {})
+            }), timeoutMs);
+        }
+        catch (err) {
+            const message = err.message;
+            // Too slow or too big: the service ran, and this render failed.
+            if (/timed out|too large/.test(message))
+                throw new Error(`PDF render failed: the PDF service at ${where} ${message}`, { cause: err });
+            // Refused by the egress policy, or nothing answering: no engine to use.
+            throw new PdfUnavailableError(`the PDF service at ${where} could not be reached: ${message}`, { cause: err });
+        }
+        if (response.status !== 200) {
+            const said = response.body.subarray(0, 200).toString('utf8').replace(/\s+/g, ' ').trim();
+            throw new Error(`PDF render failed: the PDF service at ${where} answered ${response.status}${said ? `: ${said}` : ''}`);
+        }
+        if (response.body.subarray(0, 5).toString('latin1') !== '%PDF-') {
+            throw new Error(`PDF render failed: the PDF service at ${where} answered, but not with a PDF`);
+        }
+        const remaining = Math.max(1, timeoutMs - (Date.now() - started));
+        const pdf = await (this.deps.normalize ?? normalizePdfInChild)(response.body, remaining);
+        return { pdf, engine: 'chrome-service' };
+    }
+}
+/** `guardedFetch`'s timeout is per socket wait; this bounds the whole request. */
+function withDeadline(work, timeoutMs) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}

package/lib/src/export/LocalChromePdfProvider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `local-chrome` (#1974): a Chromium already on the machine — the configured
+ * path (`ngdpbase.export.pdf.provider.local-chrome.chromium-path`), or one
+ * `resolveChromium` finds. Each render is its own child process
+ * (`pdfRenderWorker.ts`) with JavaScript off and every request refused except
+ * `data:` URIs, killed at the timeout.
+ */
+import { type ChromiumResolution, type PdfJob, type PdfJobResult } from './pdfEngine.js';
+import type { PdfProvider, PdfRenderRequest, PdfRendered } from './PdfProvider.js';
+/** Hooks for tests; a site passes nothing. */
+export interface LocalChromeDeps {
+    render?: (job: PdfJob) => Promise<PdfJobResult>;
+    resolve?: (configuredPath: string) => Promise<ChromiumResolution>;
+}
+export declare class LocalChromePdfProvider implements PdfProvider {
+    private readonly chromiumPath;
+    private readonly deps;
+    readonly name: "local-chrome";
+    /**
+     * @param chromiumPath - The configured Chromium ('' = find one)
+     * @param deps - Test hooks
+     */
+    constructor(chromiumPath: string, deps?: LocalChromeDeps);
+    render({ html, options, timeoutMs }: PdfRenderRequest): Promise<PdfRendered>;
+}

package/lib/src/export/LocalChromePdfProvider.js

@@ -0,0 +1,33 @@
+/**
+ * `local-chrome` (#1974): a Chromium already on the machine — the configured
+ * path (`ngdpbase.export.pdf.provider.local-chrome.chromium-path`), or one
+ * `resolveChromium` finds. Each render is its own child process
+ * (`pdfRenderWorker.ts`) with JavaScript off and every request refused except
+ * `data:` URIs, killed at the timeout.
+ */
+import { PdfUnavailableError, renderPdfInChild, resolveChromium } from './pdfEngine.js';
+export class LocalChromePdfProvider {
+    chromiumPath;
+    deps;
+    name = 'local-chrome';
+    /**
+     * @param chromiumPath - The configured Chromium ('' = find one)
+     * @param deps - Test hooks
+     */
+    constructor(chromiumPath, deps = {}) {
+        this.chromiumPath = chromiumPath;
+        this.deps = deps;
+    }
+    async render({ html, options, timeoutMs }) {
+        const engine = await (this.deps.resolve ?? ((p) => resolveChromium(p)))(this.chromiumPath);
+        if (!engine.ok)
+            throw new PdfUnavailableError(engine.reason);
+        const result = await (this.deps.render ?? renderPdfInChild)({ kind: 'render', html, executablePath: engine.executablePath, options, timeoutMs });
+        if (!result.ok) {
+            if (result.stage === 'launch')
+                throw new PdfUnavailableError(`Chromium at ${engine.executablePath} could not start: ${result.error}`);
+            throw new Error(`PDF render failed: ${result.error}`);
+        }
+        return { pdf: result.pdf, engine: `local-chrome:${engine.source}` };
+    }
+}

package/lib/src/export/PdfProvider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PdfProvider — how ExportManager turns HTML into PDF (#1974).
+ *
+ * `ngdpbase.export.pdf.provider` chooses one, as `ngdpbase.mail.provider` and
+ * `ngdpbase.database.provider` do for their managers:
+ *
+ * - `none` (default) — `NonePdfProvider`: no PDF; `htmlToPdf` throws
+ *   `PdfUnavailableError` and an add-on falls back to HTML.
+ * - `local-chrome` — `LocalChromePdfProvider`: a Chromium already on the
+ *   machine, run in a child process with no network.
+ * - `chrome-service` — `ChromeServicePdfProvider`: a separate Chromium service
+ *   reached by URL (Gotenberg's HTML route), through `guardedFetch`.
+ *
+ * A provider renders one document and returns the normalised bytes
+ * (`normalizePdf`), so the same HTML gives the same bytes for a given provider
+ * and engine version. It throws `PdfUnavailableError` when it has no engine to
+ * use (not set up, not reachable, cannot start) and a plain `Error` when the
+ * engine ran and the render failed. Another engine (e.g. WeasyPrint) is a new
+ * class here and one more name in `PDF_PROVIDERS`.
+ */
+import { type ResolvedPdfOptions } from './pdfEngine.js';
+/** The values `ngdpbase.export.pdf.provider` takes. */
+export declare const PDF_PROVIDERS: readonly ["none", "local-chrome", "chrome-service"];
+export type PdfProviderName = (typeof PDF_PROVIDERS)[number];
+/** One render, after the options are validated and the defaults filled. */
+export interface PdfRenderRequest {
+    html: string;
+    options: ResolvedPdfOptions;
+    /** The whole render, including any wait on a PDF service. */
+    timeoutMs: number;
+}
+export interface PdfRendered {
+    /** The PDF, normalised. */
+    pdf: Uint8Array;
+    /** What made it, for the log line (`local-chrome:system`, `chrome-service`). */
+    engine: string;
+}
+export interface PdfProvider {
+    readonly name: PdfProviderName;
+    render(request: PdfRenderRequest): Promise<PdfRendered>;
+}
+/**
+ * `none`: PDF export is off. Also stands in for a provider name that is not
+ * one, so a typo is reported the same way — unavailable, with the reason.
+ */
+export declare class NonePdfProvider implements PdfProvider {
+    private readonly reason;
+    readonly name: "none";
+    constructor(reason?: string);
+    render(): Promise<PdfRendered>;
+}

package/lib/src/export/PdfProvider.js

@@ -0,0 +1,37 @@
+/**
+ * PdfProvider — how ExportManager turns HTML into PDF (#1974).
+ *
+ * `ngdpbase.export.pdf.provider` chooses one, as `ngdpbase.mail.provider` and
+ * `ngdpbase.database.provider` do for their managers:
+ *
+ * - `none` (default) — `NonePdfProvider`: no PDF; `htmlToPdf` throws
+ *   `PdfUnavailableError` and an add-on falls back to HTML.
+ * - `local-chrome` — `LocalChromePdfProvider`: a Chromium already on the
+ *   machine, run in a child process with no network.
+ * - `chrome-service` — `ChromeServicePdfProvider`: a separate Chromium service
+ *   reached by URL (Gotenberg's HTML route), through `guardedFetch`.
+ *
+ * A provider renders one document and returns the normalised bytes
+ * (`normalizePdf`), so the same HTML gives the same bytes for a given provider
+ * and engine version. It throws `PdfUnavailableError` when it has no engine to
+ * use (not set up, not reachable, cannot start) and a plain `Error` when the
+ * engine ran and the render failed. Another engine (e.g. WeasyPrint) is a new
+ * class here and one more name in `PDF_PROVIDERS`.
+ */
+import { PdfUnavailableError } from './pdfEngine.js';
+/** The values `ngdpbase.export.pdf.provider` takes. */
+export const PDF_PROVIDERS = ['none', 'local-chrome', 'chrome-service'];
+/**
+ * `none`: PDF export is off. Also stands in for a provider name that is not
+ * one, so a typo is reported the same way — unavailable, with the reason.
+ */
+export class NonePdfProvider {
+    reason;
+    name = 'none';
+    constructor(reason = 'ngdpbase.export.pdf.provider is none: set it to local-chrome or chrome-service') {
+        this.reason = reason;
+    }
+    render() {
+        return Promise.reject(new PdfUnavailableError(this.reason));
+    }
+}

package/lib/src/export/pdfEngine.d.ts

@@ -0,0 +1,113 @@
+/** Page sizes Chromium knows by name. */
+export declare const PDF_PAGE_SIZES: readonly ["Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6"];
+export type PdfPageSize = (typeof PDF_PAGE_SIZES)[number];
+export interface PdfMargin {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+/**
+ * What a caller may set. An `@page` rule in the HTML (size, margin) wins over
+ * these, as it does when a browser prints.
+ */
+export interface PdfOptions {
+    /** Page size; default `ngdpbase.export.pdf.page-size`. */
+    format?: PdfPageSize;
+    /** Page margins, each a CSS length (`'20mm'`, `'0.5in'`); default none. */
+    margin?: PdfMargin;
+    /** Print background colours and images; default `true`. */
+    printBackground?: boolean;
+}
+/** Options after validation and defaults. */
+export interface ResolvedPdfOptions {
+    format: PdfPageSize;
+    margin: PdfMargin;
+    printBackground: boolean;
+}
+/** One local Chromium render, as the child receives it. */
+export interface PdfJob {
+    kind: 'render';
+    html: string;
+    executablePath: string;
+    options: ResolvedPdfOptions;
+    timeoutMs: number;
+}
+/** A PDF made elsewhere, to normalise in the child. */
+export interface PdfNormalizeJob {
+    kind: 'normalize';
+    pdf: Uint8Array;
+    timeoutMs: number;
+}
+/** Anything the child is asked to do. */
+export type PdfChildJob = PdfJob | PdfNormalizeJob;
+/** What the child sends back. `launch` means Chromium could not start: the engine is unavailable. */
+export type PdfJobResult = {
+    ok: true;
+    pdf: Uint8Array;
+} | {
+    ok: false;
+    stage: 'launch' | 'render';
+    error: string;
+};
+/**
+ * No PDF engine: `playwright-core` is not installed, no Chromium was found, or
+ * it could not start. An add-on catches it by `code` (it cannot import core
+ * values) and falls back to HTML.
+ */
+export declare class PdfUnavailableError extends Error {
+    readonly code = "PDF_UNAVAILABLE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Validate a caller's options and fill the defaults. Throws on anything
+ * Chromium would misread, so a typo is an error rather than a different page.
+ *
+ * @param options - The caller's options
+ * @param defaultFormat - `ngdpbase.export.pdf.page-size`
+ */
+export declare function resolvePdfOptions(options: PdfOptions | undefined, defaultFormat: string): ResolvedPdfOptions;
+/** Where Chromium or Chrome usually is, per platform. Checked after the configured path and Playwright's own. */
+export declare const SYSTEM_CHROMIUM_PATHS: Record<string, string[]>;
+export type ChromiumResolution = {
+    ok: true;
+    executablePath: string;
+    source: 'configured' | 'playwright' | 'system';
+} | {
+    ok: false;
+    reason: string;
+};
+/** Hooks for tests; a site passes nothing. */
+export interface ResolveDeps {
+    exists?: (p: string) => boolean;
+    platform?: string;
+    playwrightInstalled?: () => boolean;
+    /** Playwright's own Chromium, or null when it cannot say. */
+    playwrightChromium?: () => Promise<string | null>;
+}
+/** Whether `playwright-core` is installed (it is an optional dependency). */
+export declare function playwrightInstalled(): boolean;
+/**
+ * Find a Chromium to render with. Read on every call, so installing Chromium
+ * or setting the path takes effect without a restart.
+ *
+ * @param configuredPath - `ngdpbase.export.pdf.provider.local-chrome.chromium-path` ('' = find one)
+ */
+export declare function resolveChromium(configuredPath: string, deps?: ResolveDeps): Promise<ChromiumResolution>;
+export declare function childEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Render one job in a child process. Resolves with the child's answer; rejects
+ * only when the child timed out, crashed or never answered.
+ *
+ * @param job - The render
+ */
+export declare function renderPdfInChild(job: PdfJob): Promise<PdfJobResult>;
+/**
+ * Normalise a PDF in a child process (`normalizePdf`, the same pass a local
+ * render gets). Rejects when the bytes are not a PDF pdf-lib can read, or the
+ * child times out.
+ *
+ * @param pdf - A PDF a PDF service returned
+ * @param timeoutMs - The child is killed after this
+ */
+export declare function normalizePdfInChild(pdf: Uint8Array, timeoutMs: number): Promise<Uint8Array>;