@formfeed/engine 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/engine",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,8 @@
     "marked": "^18.0.11",
     "n2words": "^6.1.2",
     "nunjucks": "^3.2.4",
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "zod": "^4.5.4"
   },
   "keywords": [
     "formfeed",

package/types/frame/audit.d.cts

@@ -0,0 +1,15 @@
+import { type AuditOptions, type AuditReport } from '../lib/accessibility/index.cjs';
+/**
+ * An element's start tag as the author would recognise it, without what the editor added to it and,
+ * on a page of the paged preview, without what Paged.js did: a finding once read
+ * `<h3 data-ref="0add6264-…">`.
+ */
+export declare function startTag(element: Element): string;
+export declare function audit(win: Window, options?: AuditOptions): AuditReport;
+/** How many columns each row spans, counting cells that reach down from the rows above. */
+export declare function rowWidths(rows: HTMLTableRowElement[]): number[];
+/**
+ * The words of a computed `content` value, or '' when it generates none: its strings, and its
+ * counters as they are written, because the number they come to is not in the style.
+ */
+export declare function generatedText(content: string | null | undefined): string;

package/types/frame/audit.d.ts

@@ -0,0 +1,15 @@
+import { type AuditOptions, type AuditReport } from '../lib/accessibility/index.js';
+/**
+ * An element's start tag as the author would recognise it, without what the editor added to it and,
+ * on a page of the paged preview, without what Paged.js did: a finding once read
+ * `<h3 data-ref="0add6264-…">`.
+ */
+export declare function startTag(element: Element): string;
+export declare function audit(win: Window, options?: AuditOptions): AuditReport;
+/** How many columns each row spans, counting cells that reach down from the rows above. */
+export declare function rowWidths(rows: HTMLTableRowElement[]): number[];
+/**
+ * The words of a computed `content` value, or '' when it generates none: its strings, and its
+ * counters as they are written, because the number they come to is not in the style.
+ */
+export declare function generatedText(content: string | null | undefined): string;

package/types/frame/audit.entry.d.cts

@@ -0,0 +1 @@
+export {};

package/types/frame/audit.entry.d.ts

@@ -0,0 +1 @@
+export {};

package/types/frame/text-edit.d.cts

@@ -9,7 +9,14 @@
  * in place, chips are atomic, and Enter, Tab or leaving the element commit
  * (`formfeed:edit-commit`), Escape cancels. The frame never writes the template: it only sends what
  * the user typed. Ctrl+B, Ctrl+I and Ctrl+U format nothing here; on the design stage they are passed
- * on (`formfeed:edit-style`), where they switch the style of the whole layer.
+ * on (`formfeed:edit-style`), where they switch the style of the whole layer. A session the editor
+ * asks for is not opened once the user has left this window for the app (`formfeed:edit-cancel`):
+ * opening it takes the focus, and that belongs to where the user went.
+ *
+ * A preview document says which one it is (`doc`, from its `formfeed:document` meta) and when its
+ * elements are in place (`formfeed:edit-ready`). The editor renders a moment before the frame takes
+ * the new document, and a click in that moment is about a document on its way out: the editor waits
+ * for the next one and has the frame ask for the same text there (`formfeed:edit-open`).
  */
 /** An item as the frame shows it: chips carry the text to display. */
 export type FrameItem = {

package/types/frame/text-edit.d.ts

@@ -9,7 +9,14 @@
  * in place, chips are atomic, and Enter, Tab or leaving the element commit
  * (`formfeed:edit-commit`), Escape cancels. The frame never writes the template: it only sends what
  * the user typed. Ctrl+B, Ctrl+I and Ctrl+U format nothing here; on the design stage they are passed
- * on (`formfeed:edit-style`), where they switch the style of the whole layer.
+ * on (`formfeed:edit-style`), where they switch the style of the whole layer. A session the editor
+ * asks for is not opened once the user has left this window for the app (`formfeed:edit-cancel`):
+ * opening it takes the focus, and that belongs to where the user went.
+ *
+ * A preview document says which one it is (`doc`, from its `formfeed:document` meta) and when its
+ * elements are in place (`formfeed:edit-ready`). The editor renders a moment before the frame takes
+ * the new document, and a click in that moment is about a document on its way out: the editor waits
+ * for the next one and has the frame ask for the same text there (`formfeed:edit-open`).
  */
 /** An item as the frame shows it: chips carry the text to display. */
 export type FrameItem = {

package/types/index.d.cts

@@ -25,11 +25,18 @@ export { canvasDocument, flowDocument, pagedDocument, pageNumberSpans, paperOf,
 export type { PagedOptions, PreviewOptions, PreviewOverflow, RenderedDraft, } from './lib/preview.cjs';
 export { annotateSourcePositions, editAttribute, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.cjs';
 export type { AnnotateOptions, SourceFile, SourceLocation, } from './lib/source-positions.cjs';
-export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, translationItems, translationText, } from './lib/source-edit.cjs';
+export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, regionPosition, translationItems, translationText, } from './lib/source-edit.cjs';
 export type { ApplyResult, ChipKind, EditableRegion, EditItem, RegionChip, RegionLookup, RegionPart, RegionRefusal, } from './lib/source-edit.cjs';
 export { resolveTranslation, translationTarget } from './lib/translation.cjs';
 export { DESIGN_LIMITS, DESIGN_VERSION, dataPathPattern, defaultLayer, designBytes, designOutputHash, designStarters, emitDesign, emptyDesign, genericFamily, googleFont, googleFonts, googleFontsUrl, imageIsEmpty, layerIdPattern, nearestWeight, nextLayerId, parseDesign, } from './lib/design/index.cjs';
 export type { BarcodeLayer, BarcodeSymbology, Binding, CanvasSize, DesignDocument, DesignLayer, DesignStarter, EmittedDesign, FontChoice, GoogleFont, ImageLayer, ImageSource, LayerBase, LayerType, Paint, ParsedDesign, QrLayer, Shadow, ShapeLayer, Stroke, TextFormat, TextItem, TextLayer, TextStyle, } from './lib/design/index.cjs';
+export { CII_GUIDELINES, CODE_LIST_RELEASE, DISPLAY_TERMS, EINVOICE_FLAVOURS, EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILES, EINVOICE_PROFILE_NAMES, EINVOICE_SPEC_VERSIONS, EINVOICE_XML_NAME, INVOICE_DATA_KEY, VAT_CATEGORIES, capMessages, checkInvoice, defaultEinvoiceOptions, displayCheck, displayMissingText, einvoiceOptionsSchema, einvoiceResult, einvoiceXml, htmlText, invoiceAmountText, invoiceLineOf, invoicePathSegments, invoiceSchema, invoiceSkeleton, invoiceToCii, locateJsonPath, resolveEinvoiceOptions, shownAmounts, } from './lib/einvoice/index.cjs';
+export type { CheckOptions, DisplayCheck, DisplayValue, EinvoiceDisplay, EinvoiceFlavour, EinvoiceMessage, EinvoiceOptions, EinvoiceOptionsInput, EinvoiceProfile, EinvoiceResult, EinvoiceValidation, EinvoiceXml, Identifier, Invoice, InvoiceAddress, InvoiceAllowance, InvoiceBreakdown, InvoiceCheck, InvoiceInput, InvoiceLine, InvoiceParty, InvoiceProblem, InvoiceProblemCode, InvoiceTax, JsonLocation, ResolvedEinvoice, VatCategory, } from './lib/einvoice/index.cjs';
+export { ACCESSIBILITY_HEADER_LENGTH, ACCESSIBILITY_MAX_ELEMENTS, ACCESSIBILITY_MAX_FAILURES, AUDIT_CODES, AUDIT_RULES, AUDIT_SEVERITY, AUDIT_SNIPPET_LENGTH, AUDIT_TITLES, PDFUA_STANDARD, UA_CHECKS, UA_REFUSALS, accessibilityHeader, accessibilityHeaderValue, accessibilityResult, auditMessage, isUaSetting, resolveUa, } from './lib/accessibility/index.cjs';
+export type { AccessibilityFailure, AccessibilityResult, AccessibilityWarning, AuditArgs, AuditCode, AuditFinding, AuditLink, AuditOptions, AuditReport, AuditSeverity, UaCheck, UaOptions, UaSetting, ValidatorFailure, ValidatorVerdict, } from './lib/accessibility/index.cjs';
+export { staticAudit, staticAuditDiagnostics, } from './lib/accessibility/static.cjs';
+export type { StaticAuditDiagnostic, StaticAuditInput, } from './lib/accessibility/static.cjs';
+export { auditRuntime } from './lib/generated/frames.cjs';
 export { encodeTemplateText } from './lib/source-edit.cjs';
 export type { Dictionaries } from './lib/translation.cjs';
 export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.cjs';

package/types/index.d.ts

@@ -25,11 +25,18 @@ export { canvasDocument, flowDocument, pagedDocument, pageNumberSpans, paperOf,
 export type { PagedOptions, PreviewOptions, PreviewOverflow, RenderedDraft, } from './lib/preview.js';
 export { annotateSourcePositions, editAttribute, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.js';
 export type { AnnotateOptions, SourceFile, SourceLocation, } from './lib/source-positions.js';
-export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, translationItems, translationText, } from './lib/source-edit.js';
+export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, regionPosition, translationItems, translationText, } from './lib/source-edit.js';
 export type { ApplyResult, ChipKind, EditableRegion, EditItem, RegionChip, RegionLookup, RegionPart, RegionRefusal, } from './lib/source-edit.js';
 export { resolveTranslation, translationTarget } from './lib/translation.js';
 export { DESIGN_LIMITS, DESIGN_VERSION, dataPathPattern, defaultLayer, designBytes, designOutputHash, designStarters, emitDesign, emptyDesign, genericFamily, googleFont, googleFonts, googleFontsUrl, imageIsEmpty, layerIdPattern, nearestWeight, nextLayerId, parseDesign, } from './lib/design/index.js';
 export type { BarcodeLayer, BarcodeSymbology, Binding, CanvasSize, DesignDocument, DesignLayer, DesignStarter, EmittedDesign, FontChoice, GoogleFont, ImageLayer, ImageSource, LayerBase, LayerType, Paint, ParsedDesign, QrLayer, Shadow, ShapeLayer, Stroke, TextFormat, TextItem, TextLayer, TextStyle, } from './lib/design/index.js';
+export { CII_GUIDELINES, CODE_LIST_RELEASE, DISPLAY_TERMS, EINVOICE_FLAVOURS, EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILES, EINVOICE_PROFILE_NAMES, EINVOICE_SPEC_VERSIONS, EINVOICE_XML_NAME, INVOICE_DATA_KEY, VAT_CATEGORIES, capMessages, checkInvoice, defaultEinvoiceOptions, displayCheck, displayMissingText, einvoiceOptionsSchema, einvoiceResult, einvoiceXml, htmlText, invoiceAmountText, invoiceLineOf, invoicePathSegments, invoiceSchema, invoiceSkeleton, invoiceToCii, locateJsonPath, resolveEinvoiceOptions, shownAmounts, } from './lib/einvoice/index.js';
+export type { CheckOptions, DisplayCheck, DisplayValue, EinvoiceDisplay, EinvoiceFlavour, EinvoiceMessage, EinvoiceOptions, EinvoiceOptionsInput, EinvoiceProfile, EinvoiceResult, EinvoiceValidation, EinvoiceXml, Identifier, Invoice, InvoiceAddress, InvoiceAllowance, InvoiceBreakdown, InvoiceCheck, InvoiceInput, InvoiceLine, InvoiceParty, InvoiceProblem, InvoiceProblemCode, InvoiceTax, JsonLocation, ResolvedEinvoice, VatCategory, } from './lib/einvoice/index.js';
+export { ACCESSIBILITY_HEADER_LENGTH, ACCESSIBILITY_MAX_ELEMENTS, ACCESSIBILITY_MAX_FAILURES, AUDIT_CODES, AUDIT_RULES, AUDIT_SEVERITY, AUDIT_SNIPPET_LENGTH, AUDIT_TITLES, PDFUA_STANDARD, UA_CHECKS, UA_REFUSALS, accessibilityHeader, accessibilityHeaderValue, accessibilityResult, auditMessage, isUaSetting, resolveUa, } from './lib/accessibility/index.js';
+export type { AccessibilityFailure, AccessibilityResult, AccessibilityWarning, AuditArgs, AuditCode, AuditFinding, AuditLink, AuditOptions, AuditReport, AuditSeverity, UaCheck, UaOptions, UaSetting, ValidatorFailure, ValidatorVerdict, } from './lib/accessibility/index.js';
+export { staticAudit, staticAuditDiagnostics, } from './lib/accessibility/static.js';
+export type { StaticAuditDiagnostic, StaticAuditInput, } from './lib/accessibility/static.js';
+export { auditRuntime } from './lib/generated/frames.js';
 export { encodeTemplateText } from './lib/source-edit.js';
 export type { Dictionaries } from './lib/translation.js';
 export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.js';

package/types/lib/accessibility/index.d.cts

@@ -0,0 +1,201 @@
+/**
+ * `@formfeed/engine/accessibility` (plan 21): what `pdf.ua` asks for, what the audit finds in a
+ * document before it is rendered, and the report a render keeps of what the validator said. No
+ * template engine is imported here and nothing of Node, so the gateway Worker, the render-worker,
+ * the editor and the CLI all read the same names.
+ *
+ * PDF/UA-1 is ISO 14289-1. A machine can decide about two thirds of it; whether an alternative text
+ * describes its image, or the reading order makes sense, stays with a person. So nothing here says
+ * "accessible": the setting is named after the standard, and the report after what was checked.
+ */
+/** The standard a render with `pdf.ua` is held to, as the report names it. */
+export declare const PDFUA_STANDARD = "PDF/UA-1";
+/**
+ * What happens to a file that fails validation: `strict` fails the render and delivers nothing,
+ * `report` delivers the file without the PDF/UA identifier and puts the verdict on the render.
+ */
+export declare const UA_CHECKS: readonly ["strict", "report"];
+export type UaCheck = (typeof UA_CHECKS)[number];
+export interface UaOptions {
+    check: UaCheck;
+}
+/** `pdf.ua` as a template's settings or a request write it. */
+export type UaSetting = boolean | {
+    check?: UaCheck;
+} | null;
+/**
+ * `pdf.ua` as a render takes it: `true` is `{ check: 'strict' }`, and anything that is not a
+ * declaration is off. A customer who asked for a conforming file and silently got another would
+ * find out from their own customer, so strict is what a bare `true` means.
+ */
+export declare function resolveUa(setting: unknown): UaOptions | null;
+/**
+ * What `pdf.ua` cannot go with, in the words every place that refuses it uses (the gateway before a
+ * render costs anything, the worker for whoever calls it directly, `formfeed validate`, the API's
+ * template validation). Merged pages lose their tags while the validator still passes the file;
+ * the tags of Word and PowerPoint documents are LibreOffice's and not measured yet. An e-invoice
+ * is not among them: its PDF/A-3 keeps the tags, and the file is held to both standards (plan 22).
+ */
+export declare const UA_REFUSALS: {
+    readonly office: "pdf.ua is not available for Word and PowerPoint templates yet";
+    readonly merge: "pdf.ua cannot be combined with post.merge_after: the tags of merged documents do not survive the merge";
+};
+/** Whether a `pdf.ua` value is one the API takes: a boolean, null, or `{ check }` and nothing else. */
+export declare function isUaSetting(value: unknown): value is UaSetting;
+/**
+ * What the audit looks for (plan 21 §6): one finding per fault we measured in Chromium's output,
+ * not a general accessibility linter. Much of such a linter is about landmarks, focus and widgets,
+ * which a printed page does not have, and it knows nothing of header and footer templates or of
+ * what Chromium leaves untagged.
+ */
+export declare const AUDIT_CODES: readonly ["document-title", "image-alt", "figure-name", "heading-order", "table-rows", "table-cell-empty", "masked-text", "filtered-text", "document-language", "table-headers", "link-name", "generated-text", "fixed-text", "running-text"];
+export type AuditCode = (typeof AUDIT_CODES)[number];
+export type AuditSeverity = 'error' | 'warning';
+/**
+ * An error is a fault the validator will fail the file for; a warning is one no rule catches and a
+ * reader hears all the same.
+ */
+export declare const AUDIT_SEVERITY: Record<AuditCode, AuditSeverity>;
+/**
+ * The rules of veraPDF's PDF/UA-1 profile a finding fails when it is left as it is, by clause and
+ * test number. The other way round it says which elements a failed rule is about: the validator
+ * names objects of the file, the audit the tags of the template.
+ */
+export declare const AUDIT_RULES: Record<AuditCode, readonly string[]>;
+/**
+ * A code in a few words, for a list that names the elements beside it: a render's warnings carry the
+ * code and the elements, not a sentence each. The CLI and the MCP server print these; the app has
+ * its own, per locale.
+ */
+export declare const AUDIT_TITLES: Record<AuditCode, string>;
+/** The values a finding's sentence is built from. */
+export type AuditArgs = Record<string, string | number>;
+export interface AuditFinding {
+    code: AuditCode;
+    severity: AuditSeverity;
+    /**
+     * `data-ff-src` of the nearest tag that carries one: the template's own position, which only the
+     * editor's previews write. Null anywhere else, and for a finding about the document as a whole.
+     */
+    src: string | null;
+    /** The element's start tag, cut to 120 characters; empty for a finding about the document. */
+    snippet: string;
+    args: AuditArgs;
+}
+/** A link and the name a screen reader says for it (plan 21 §4, decision 7). */
+export interface AuditLink {
+    /** An absolute URL, or `#name` for a place in the document. */
+    href: string;
+    name: string;
+}
+export interface AuditReport {
+    findings: AuditFinding[];
+    /** The body's links in document order. */
+    links: AuditLink[];
+    /** The links of the header and footer templates. */
+    templateLinks: AuditLink[];
+}
+export interface AuditOptions {
+    /** Whether findings are wanted, or only the links' names (a tagged PDF without `pdf.ua`). */
+    findings?: boolean;
+    /**
+     * Header and footer templates where they are not elements of the document: Chromium prints them
+     * in a page of their own, so the render-worker hands them over as text.
+     */
+    header?: string;
+    footer?: string;
+    /** How many pages the document has, where the host knows (the paged preview). */
+    pages?: number;
+    /** The height of one page's content in CSS pixels, to tell whether there is more than one. */
+    pageHeight?: number;
+    /** Whether the settings name a locale, which stands in for a missing `lang`. */
+    locale?: boolean;
+}
+/** Longest snippet a finding carries. */
+export declare const AUDIT_SNIPPET_LENGTH = 120;
+/**
+ * A finding as an English sentence that says what is wrong and what to do about it. The editor
+ * words the same findings per locale from `args`; the API, the CLI and the worker's log use these.
+ */
+export declare function auditMessage(finding: Pick<AuditFinding, 'code' | 'args'>): string;
+/** How many failed rules a render keeps, and how many elements of each. */
+export declare const ACCESSIBILITY_MAX_FAILURES = 20;
+export declare const ACCESSIBILITY_MAX_ELEMENTS = 5;
+/** One rule of the validator a file failed. */
+export interface AccessibilityFailure {
+    /** Clause and test number of veraPDF's PDF/UA-1 profile, `7.3-1`. */
+    rule: string;
+    /** The audit's finding the rule is about, where it maps to one. */
+    code?: AuditCode;
+    /** How many checks of the rule failed. */
+    count: number;
+    /** The finding's sentence, else the validator's own. */
+    message: string;
+    /** The elements the audit found for it: start tags of the document, at most five. */
+    elements: string[];
+}
+/** What a reader will stumble over although no rule fails for it. */
+export interface AccessibilityWarning {
+    code: AuditCode;
+    count: number;
+    /** Start tags, or the text itself for `running-text` and `generated-text`. */
+    elements: string[];
+}
+/**
+ * `accessibility` on a render (plan 21 §7): `null` unless `pdf.ua` was set. `conformant` is the
+ * validator's word on the machine-checkable rules of PDF/UA-1, no more: a passed check does not
+ * make a document accessible.
+ */
+export interface AccessibilityResult {
+    standard: typeof PDFUA_STANDARD;
+    check: UaCheck;
+    conformant: boolean;
+    /** The validator and its version: its rule set moves between releases. */
+    validator: string;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    failures: AccessibilityFailure[];
+    warnings: AccessibilityWarning[];
+    /** More rules failed than the render keeps. */
+    truncated?: boolean;
+}
+/** One failed rule as the validator reports it. */
+export interface ValidatorFailure {
+    /** Clause and test number, `7.3-1`. */
+    rule: string;
+    description: string;
+    /** How many checks of the rule failed. */
+    checks: number;
+}
+/** What the validator said about a file, before the audit's findings are joined to it. */
+export interface ValidatorVerdict {
+    validator: string;
+    compliant: boolean;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    failures: ValidatorFailure[];
+}
+/**
+ * The report a render keeps: the validator's verdict, with the audit's findings joined to the rules
+ * they explain. The rule and its count are the validator's; the code, the sentence and the elements
+ * are the audit's where one of its findings fails that rule, else the validator's own description.
+ * Findings that fail no rule are the warnings.
+ */
+export declare function accessibilityResult(options: UaOptions, verdict: ValidatorVerdict, findings: readonly AuditFinding[]): AccessibilityResult;
+/** What the binary answer says in `X-Formfeed-PDF-UA`. */
+export declare function accessibilityHeader(result: Pick<AccessibilityResult, 'conformant'>): 'conformant' | 'not-conformant';
+/** How long the report may be as a header value: proxies refuse a response whose headers grow past a few kilobytes. */
+export declare const ACCESSIBILITY_HEADER_LENGTH = 8000;
+/**
+ * The report as a response header carries it: the editor's true render reads the file from the body
+ * and the verdict from `X-Formfeed-Accessibility`, percent-encoded because an element's text is not
+ * always ASCII. A report that is too long for a header loses what the template check lists anyway,
+ * in this order: all but one element of each entry, every element, the warnings, then the failures
+ * from the last. The verdict, the validator and the counts always arrive, and `truncated` says that
+ * something did not.
+ */
+export declare function accessibilityHeaderValue(result: AccessibilityResult, limit?: number): string;

package/types/lib/accessibility/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * `@formfeed/engine/accessibility` (plan 21): what `pdf.ua` asks for, what the audit finds in a
+ * document before it is rendered, and the report a render keeps of what the validator said. No
+ * template engine is imported here and nothing of Node, so the gateway Worker, the render-worker,
+ * the editor and the CLI all read the same names.
+ *
+ * PDF/UA-1 is ISO 14289-1. A machine can decide about two thirds of it; whether an alternative text
+ * describes its image, or the reading order makes sense, stays with a person. So nothing here says
+ * "accessible": the setting is named after the standard, and the report after what was checked.
+ */
+/** The standard a render with `pdf.ua` is held to, as the report names it. */
+export declare const PDFUA_STANDARD = "PDF/UA-1";
+/**
+ * What happens to a file that fails validation: `strict` fails the render and delivers nothing,
+ * `report` delivers the file without the PDF/UA identifier and puts the verdict on the render.
+ */
+export declare const UA_CHECKS: readonly ["strict", "report"];
+export type UaCheck = (typeof UA_CHECKS)[number];
+export interface UaOptions {
+    check: UaCheck;
+}
+/** `pdf.ua` as a template's settings or a request write it. */
+export type UaSetting = boolean | {
+    check?: UaCheck;
+} | null;
+/**
+ * `pdf.ua` as a render takes it: `true` is `{ check: 'strict' }`, and anything that is not a
+ * declaration is off. A customer who asked for a conforming file and silently got another would
+ * find out from their own customer, so strict is what a bare `true` means.
+ */
+export declare function resolveUa(setting: unknown): UaOptions | null;
+/**
+ * What `pdf.ua` cannot go with, in the words every place that refuses it uses (the gateway before a
+ * render costs anything, the worker for whoever calls it directly, `formfeed validate`, the API's
+ * template validation). Merged pages lose their tags while the validator still passes the file;
+ * the tags of Word and PowerPoint documents are LibreOffice's and not measured yet. An e-invoice
+ * is not among them: its PDF/A-3 keeps the tags, and the file is held to both standards (plan 22).
+ */
+export declare const UA_REFUSALS: {
+    readonly office: "pdf.ua is not available for Word and PowerPoint templates yet";
+    readonly merge: "pdf.ua cannot be combined with post.merge_after: the tags of merged documents do not survive the merge";
+};
+/** Whether a `pdf.ua` value is one the API takes: a boolean, null, or `{ check }` and nothing else. */
+export declare function isUaSetting(value: unknown): value is UaSetting;
+/**
+ * What the audit looks for (plan 21 §6): one finding per fault we measured in Chromium's output,
+ * not a general accessibility linter. Much of such a linter is about landmarks, focus and widgets,
+ * which a printed page does not have, and it knows nothing of header and footer templates or of
+ * what Chromium leaves untagged.
+ */
+export declare const AUDIT_CODES: readonly ["document-title", "image-alt", "figure-name", "heading-order", "table-rows", "table-cell-empty", "masked-text", "filtered-text", "document-language", "table-headers", "link-name", "generated-text", "fixed-text", "running-text"];
+export type AuditCode = (typeof AUDIT_CODES)[number];
+export type AuditSeverity = 'error' | 'warning';
+/**
+ * An error is a fault the validator will fail the file for; a warning is one no rule catches and a
+ * reader hears all the same.
+ */
+export declare const AUDIT_SEVERITY: Record<AuditCode, AuditSeverity>;
+/**
+ * The rules of veraPDF's PDF/UA-1 profile a finding fails when it is left as it is, by clause and
+ * test number. The other way round it says which elements a failed rule is about: the validator
+ * names objects of the file, the audit the tags of the template.
+ */
+export declare const AUDIT_RULES: Record<AuditCode, readonly string[]>;
+/**
+ * A code in a few words, for a list that names the elements beside it: a render's warnings carry the
+ * code and the elements, not a sentence each. The CLI and the MCP server print these; the app has
+ * its own, per locale.
+ */
+export declare const AUDIT_TITLES: Record<AuditCode, string>;
+/** The values a finding's sentence is built from. */
+export type AuditArgs = Record<string, string | number>;
+export interface AuditFinding {
+    code: AuditCode;
+    severity: AuditSeverity;
+    /**
+     * `data-ff-src` of the nearest tag that carries one: the template's own position, which only the
+     * editor's previews write. Null anywhere else, and for a finding about the document as a whole.
+     */
+    src: string | null;
+    /** The element's start tag, cut to 120 characters; empty for a finding about the document. */
+    snippet: string;
+    args: AuditArgs;
+}
+/** A link and the name a screen reader says for it (plan 21 §4, decision 7). */
+export interface AuditLink {
+    /** An absolute URL, or `#name` for a place in the document. */
+    href: string;
+    name: string;
+}
+export interface AuditReport {
+    findings: AuditFinding[];
+    /** The body's links in document order. */
+    links: AuditLink[];
+    /** The links of the header and footer templates. */
+    templateLinks: AuditLink[];
+}
+export interface AuditOptions {
+    /** Whether findings are wanted, or only the links' names (a tagged PDF without `pdf.ua`). */
+    findings?: boolean;
+    /**
+     * Header and footer templates where they are not elements of the document: Chromium prints them
+     * in a page of their own, so the render-worker hands them over as text.
+     */
+    header?: string;
+    footer?: string;
+    /** How many pages the document has, where the host knows (the paged preview). */
+    pages?: number;
+    /** The height of one page's content in CSS pixels, to tell whether there is more than one. */
+    pageHeight?: number;
+    /** Whether the settings name a locale, which stands in for a missing `lang`. */
+    locale?: boolean;
+}
+/** Longest snippet a finding carries. */
+export declare const AUDIT_SNIPPET_LENGTH = 120;
+/**
+ * A finding as an English sentence that says what is wrong and what to do about it. The editor
+ * words the same findings per locale from `args`; the API, the CLI and the worker's log use these.
+ */
+export declare function auditMessage(finding: Pick<AuditFinding, 'code' | 'args'>): string;
+/** How many failed rules a render keeps, and how many elements of each. */
+export declare const ACCESSIBILITY_MAX_FAILURES = 20;
+export declare const ACCESSIBILITY_MAX_ELEMENTS = 5;
+/** One rule of the validator a file failed. */
+export interface AccessibilityFailure {
+    /** Clause and test number of veraPDF's PDF/UA-1 profile, `7.3-1`. */
+    rule: string;
+    /** The audit's finding the rule is about, where it maps to one. */
+    code?: AuditCode;
+    /** How many checks of the rule failed. */
+    count: number;
+    /** The finding's sentence, else the validator's own. */
+    message: string;
+    /** The elements the audit found for it: start tags of the document, at most five. */
+    elements: string[];
+}
+/** What a reader will stumble over although no rule fails for it. */
+export interface AccessibilityWarning {
+    code: AuditCode;
+    count: number;
+    /** Start tags, or the text itself for `running-text` and `generated-text`. */
+    elements: string[];
+}
+/**
+ * `accessibility` on a render (plan 21 §7): `null` unless `pdf.ua` was set. `conformant` is the
+ * validator's word on the machine-checkable rules of PDF/UA-1, no more: a passed check does not
+ * make a document accessible.
+ */
+export interface AccessibilityResult {
+    standard: typeof PDFUA_STANDARD;
+    check: UaCheck;
+    conformant: boolean;
+    /** The validator and its version: its rule set moves between releases. */
+    validator: string;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    failures: AccessibilityFailure[];
+    warnings: AccessibilityWarning[];
+    /** More rules failed than the render keeps. */
+    truncated?: boolean;
+}
+/** One failed rule as the validator reports it. */
+export interface ValidatorFailure {
+    /** Clause and test number, `7.3-1`. */
+    rule: string;
+    description: string;
+    /** How many checks of the rule failed. */
+    checks: number;
+}
+/** What the validator said about a file, before the audit's findings are joined to it. */
+export interface ValidatorVerdict {
+    validator: string;
+    compliant: boolean;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    failures: ValidatorFailure[];
+}
+/**
+ * The report a render keeps: the validator's verdict, with the audit's findings joined to the rules
+ * they explain. The rule and its count are the validator's; the code, the sentence and the elements
+ * are the audit's where one of its findings fails that rule, else the validator's own description.
+ * Findings that fail no rule are the warnings.
+ */
+export declare function accessibilityResult(options: UaOptions, verdict: ValidatorVerdict, findings: readonly AuditFinding[]): AccessibilityResult;
+/** What the binary answer says in `X-Formfeed-PDF-UA`. */
+export declare function accessibilityHeader(result: Pick<AccessibilityResult, 'conformant'>): 'conformant' | 'not-conformant';
+/** How long the report may be as a header value: proxies refuse a response whose headers grow past a few kilobytes. */
+export declare const ACCESSIBILITY_HEADER_LENGTH = 8000;
+/**
+ * The report as a response header carries it: the editor's true render reads the file from the body
+ * and the verdict from `X-Formfeed-Accessibility`, percent-encoded because an element's text is not
+ * always ASCII. A report that is too long for a header loses what the template check lists anyway,
+ * in this order: all but one element of each entry, every element, the warnings, then the failures
+ * from the last. The verdict, the validator and the counts always arrive, and `truncated` says that
+ * something did not.
+ */
+export declare function accessibilityHeaderValue(result: AccessibilityResult, limit?: number): string;

package/types/lib/accessibility/static.d.cts

@@ -0,0 +1,40 @@
+import type { EngineId } from '../types.cjs';
+import { type AuditFinding, type UaOptions } from './index.cjs';
+/**
+ * The half of the audit that needs no rendered page (plan 21 §6): what a template's source and
+ * settings already say. `formfeed validate`, the MCP server's validation and the editor report it
+ * before any preview has run: a document without a title, and an image written without `alt`.
+ * Everything else depends on what the data makes of the template and is the frame script's.
+ *
+ * A finding names its place as a preview would (`body:<line>:<column>`), so the editor shows one
+ * problem where both halves found the same tag.
+ */
+export interface StaticAuditInput {
+    engine: EngineId;
+    /** The body template. */
+    html: string;
+    /** The template's head, where a `<title>` may stand. */
+    head?: string;
+    /** `pdf.metadata.title` of the settings. */
+    title?: string | null;
+}
+/** A static finding as the lists outside the editor show it. */
+export interface StaticAuditDiagnostic {
+    severity: 'error' | 'warning';
+    /** `accessibility-<code>` of the finding. */
+    code: string;
+    message: string;
+    /** Where in the body template; absent for a finding about the document as a whole (its title). */
+    location?: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * The static findings of a template that declares `pdf.ua`, for the callers that list a template's
+ * problems without a preview: `formfeed validate` and the API's template validation. A fault the
+ * validator fails the file for is an error where the declaration is strict, since every render of
+ * the template then fails for it, and a warning where it only reports.
+ */
+export declare function staticAuditDiagnostics(input: StaticAuditInput, ua: UaOptions): StaticAuditDiagnostic[];
+export declare function staticAudit(input: StaticAuditInput): AuditFinding[];

package/types/lib/accessibility/static.d.ts

@@ -0,0 +1,40 @@
+import type { EngineId } from '../types.js';
+import { type AuditFinding, type UaOptions } from './index.js';
+/**
+ * The half of the audit that needs no rendered page (plan 21 §6): what a template's source and
+ * settings already say. `formfeed validate`, the MCP server's validation and the editor report it
+ * before any preview has run: a document without a title, and an image written without `alt`.
+ * Everything else depends on what the data makes of the template and is the frame script's.
+ *
+ * A finding names its place as a preview would (`body:<line>:<column>`), so the editor shows one
+ * problem where both halves found the same tag.
+ */
+export interface StaticAuditInput {
+    engine: EngineId;
+    /** The body template. */
+    html: string;
+    /** The template's head, where a `<title>` may stand. */
+    head?: string;
+    /** `pdf.metadata.title` of the settings. */
+    title?: string | null;
+}
+/** A static finding as the lists outside the editor show it. */
+export interface StaticAuditDiagnostic {
+    severity: 'error' | 'warning';
+    /** `accessibility-<code>` of the finding. */
+    code: string;
+    message: string;
+    /** Where in the body template; absent for a finding about the document as a whole (its title). */
+    location?: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * The static findings of a template that declares `pdf.ua`, for the callers that list a template's
+ * problems without a preview: `formfeed validate` and the API's template validation. A fault the
+ * validator fails the file for is an error where the declaration is strict, since every render of
+ * the template then fails for it, and a warning where it only reports.
+ */
+export declare function staticAuditDiagnostics(input: StaticAuditInput, ua: UaOptions): StaticAuditDiagnostic[];
+export declare function staticAudit(input: StaticAuditInput): AuditFinding[];