@jwilleke/ngdpbase-types 5.26.0 → 5.28.0

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,14 +28,20 @@ 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, IceOriginalChoices, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
+export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
+export type { User, UserPreferences } from '../../src/types/User.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';
 export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
+export type { default as RoleManager } from '../../src/managers/RoleManager.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/context/ActorContext.d.ts

@@ -13,8 +13,8 @@
  * the call arrived under, and the address it came from. What does not: roles.
  * Authority is resolved at the moment of each decision, never carried.
  */
-import type { PermissionSubject } from '../managers/UserManager.js';
-import type { JobContext } from './JobContext.js';
+import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
+import { type JobContext } from './JobContext.js';
 export type ActorContext = PermissionSubject | JobContext;
 /**
  * The fields an audit record takes from a context.
@@ -35,6 +35,19 @@ export interface ActorAttribution {
     metadata: Record<string, unknown>;
 }
 export declare function isJobContext(ctx: ActorContext): ctx is JobContext;
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export declare function decisionSubject<S extends PermissionSubject | JobSubject>(input: ActorContext | S | null | undefined): PermissionSubject | JobSubject | S | null | undefined;
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

package/lib/src/context/ActorContext.js

@@ -1,8 +1,28 @@
+import { toPermissionSubject } from './JobContext.js';
 import { attributedTo } from './bootActions.js';
 import { proxyAttribution } from '../utils/proxyClaim.js';
 export function isJobContext(ctx) {
     return 'origin' in ctx && 'requestedAt' in ctx;
 }
+/**
+ * The one place a context becomes the subject a decision reads (#2022).
+ *
+ * Called by the deciders — `PolicyDecisionPoint` (`decide`, `permits`,
+ * `holds`) and `PolicyInformationPoint`'s page questions — and by nobody
+ * else: a caller hands them its context as given. A `JobContext` carries
+ * identity, never authority, so it becomes a `JobSubject` whose roles policy
+ * resolves now, keeping its token, share and proxy claims
+ * (`toPermissionSubject`). Anything else is already a subject and passes
+ * through. The object guard is #1173's: `'x' in 'jim'` throws. Not part of
+ * the add-on API; `npm run lint:context` holds callers to it.
+ */
+export function decisionSubject(input) {
+    if (typeof input !== 'object' || input === null)
+        return input;
+    // A JobSubject is not an ActorContext, and is not a job context either.
+    const ctx = input;
+    return isJobContext(ctx) ? toPermissionSubject(ctx) : input;
+}
 /**
  * Who acted, for the record — read from the context, never guessed.
  *

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));
+    }
+}