@formfeed/engine 0.2.0 → 0.3.0

package/types/lib/office/drawings.d.cts

@@ -0,0 +1,120 @@
+import type { OfficeDrawingRequest } from '../types.cjs';
+import { OfficeError } from './errors.cjs';
+export declare const officeDrawingLimits: {
+    /** Drawings per render. */
+    maxDrawings: number;
+    /** Image bytes placed per render. */
+    maxImageBytes: number;
+    /** Largest raster edge in pixels. */
+    maxPixels: number;
+};
+/** What renders images for the post pass: the render-worker or the browser. */
+export interface OfficeImageHost {
+    /** Reads an image URL (never called for `data:` URLs, which are decoded here). */
+    fetch(url: string): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+    }>;
+    /**
+     * Turns SVG or another format into a PNG. With `size`, the picture is drawn at that many pixels;
+     * without, at its natural size.
+     */
+    toPng(input: {
+        bytes: Uint8Array;
+        contentType: string;
+    }, size?: {
+        width: number;
+        height: number;
+    }): Promise<Uint8Array>;
+}
+/** Collects the drawing requests of one render and hands out their placeholders. */
+export declare class DrawingCollector {
+    readonly nonce: string;
+    readonly requests: OfficeDrawingRequest[];
+    /** Set when a template asked for more drawings than allowed; the engines wrap the error thrown. */
+    exceeded: OfficeError | null;
+    constructor(nonce: string);
+    readonly register: (request: OfficeDrawingRequest) => string;
+    pattern(): RegExp;
+    /** Indexes of the drawings a filled part uses, in order. */
+    usedIn(xml: string): number[];
+}
+/** A drawing ready to place. */
+export type ResolvedDrawing = {
+    kind: 'picture';
+    media: string;
+    widthEmu: number;
+    heightEmu: number;
+    alt: string; /** A size was asked for. */
+    sized: boolean;
+} | {
+    kind: 'page-break';
+} | {
+    kind: 'nothing';
+};
+export interface PreparedMedia {
+    name: string;
+    bytes: Uint8Array;
+    extension: 'png' | 'jpeg';
+}
+/** A size option in EMU: a number is pixels at 96 dpi, a string may carry `px`, `pt`, `mm`, `cm` or `in`. */
+export declare function toEmu(value: number | string | undefined): number | null;
+/** Natural size in pixels of a PNG, JPEG, GIF or SVG; null when it cannot be read. */
+export declare function imageSize(bytes: Uint8Array, contentType: string): {
+    width: number;
+    height: number;
+} | null;
+/** Width and height of an SVG from its attributes, else from its viewBox. */
+export declare function svgSize(svg: string): {
+    width: number;
+    height: number;
+} | null;
+/** Decodes a `data:` URL; null for anything else. */
+export declare function decodeDataUrl(url: string): {
+    bytes: Uint8Array;
+    contentType: string;
+} | null;
+/**
+ * Turns the requests into pictures: fetched or decoded, converted to PNG where Word needs it, sized
+ * (the given size, else the natural size at 96 dpi, never wider than `maxWidthEmu`), and shared when
+ * the same picture appears again. A picture that cannot be read becomes nothing and a warning.
+ */
+export declare class DrawingResolver {
+    private readonly requests;
+    private readonly host;
+    private readonly mediaPrefix;
+    readonly media: PreparedMedia[];
+    readonly warnings: string[];
+    private readonly resolved;
+    private readonly byKey;
+    private imageBytes;
+    constructor(requests: readonly OfficeDrawingRequest[], host: OfficeImageHost | undefined, mediaPrefix: string);
+    resolve(index: number, maxWidthEmu: number): Promise<ResolvedDrawing>;
+    private resolveOne;
+    private prepare;
+}
+/** The text width of a Word part's last section in EMU; 16 cm when it names none. */
+export declare function textWidthEmu(xml: string): number;
+/** A picture in a run, as Word writes one (`wp:inline`); namespaces are declared on the elements. */
+export declare function inlinePicture(picture: Extract<ResolvedDrawing, {
+    kind: 'picture';
+}>, rId: string, id: number): string;
+/** The highest drawing id of a part, so new pictures start after it. */
+export declare function highestDrawingId(xml: string): number;
+/**
+ * Replaces the drawing placeholders of a filled Word part. A placeholder inside `w:t` splits its run:
+ * the text before stays in the run, the picture (or page break) gets a run of its own with the same
+ * run properties, and the text after continues in a copy of the run.
+ */
+export declare function placeDrawings(xml: string, pattern: RegExp, markupFor: (index: number) => string): string;
+/** Adds image relationships to a part's `.rels` (created when the part has none). */
+export declare function withRelationships(rels: string | null, relationships: Array<{
+    id: string;
+    target: string;
+}>): string;
+/** Relationship ids a `.rels` already uses. */
+export declare function relationshipIds(rels: string | null): Set<string>;
+/** `[Content_Types].xml` with defaults for the picture formats it lacks. */
+export declare function withImageTypes(contentTypes: string, extensions: ReadonlySet<'png' | 'jpeg'>): string;
+/** `word/document.xml` → `word/_rels/document.xml.rels`. */
+export declare function relsPathOf(part: string): string;

package/types/lib/office/drawings.d.ts

@@ -0,0 +1,120 @@
+import type { OfficeDrawingRequest } from '../types.js';
+import { OfficeError } from './errors.js';
+export declare const officeDrawingLimits: {
+    /** Drawings per render. */
+    maxDrawings: number;
+    /** Image bytes placed per render. */
+    maxImageBytes: number;
+    /** Largest raster edge in pixels. */
+    maxPixels: number;
+};
+/** What renders images for the post pass: the render-worker or the browser. */
+export interface OfficeImageHost {
+    /** Reads an image URL (never called for `data:` URLs, which are decoded here). */
+    fetch(url: string): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+    }>;
+    /**
+     * Turns SVG or another format into a PNG. With `size`, the picture is drawn at that many pixels;
+     * without, at its natural size.
+     */
+    toPng(input: {
+        bytes: Uint8Array;
+        contentType: string;
+    }, size?: {
+        width: number;
+        height: number;
+    }): Promise<Uint8Array>;
+}
+/** Collects the drawing requests of one render and hands out their placeholders. */
+export declare class DrawingCollector {
+    readonly nonce: string;
+    readonly requests: OfficeDrawingRequest[];
+    /** Set when a template asked for more drawings than allowed; the engines wrap the error thrown. */
+    exceeded: OfficeError | null;
+    constructor(nonce: string);
+    readonly register: (request: OfficeDrawingRequest) => string;
+    pattern(): RegExp;
+    /** Indexes of the drawings a filled part uses, in order. */
+    usedIn(xml: string): number[];
+}
+/** A drawing ready to place. */
+export type ResolvedDrawing = {
+    kind: 'picture';
+    media: string;
+    widthEmu: number;
+    heightEmu: number;
+    alt: string; /** A size was asked for. */
+    sized: boolean;
+} | {
+    kind: 'page-break';
+} | {
+    kind: 'nothing';
+};
+export interface PreparedMedia {
+    name: string;
+    bytes: Uint8Array;
+    extension: 'png' | 'jpeg';
+}
+/** A size option in EMU: a number is pixels at 96 dpi, a string may carry `px`, `pt`, `mm`, `cm` or `in`. */
+export declare function toEmu(value: number | string | undefined): number | null;
+/** Natural size in pixels of a PNG, JPEG, GIF or SVG; null when it cannot be read. */
+export declare function imageSize(bytes: Uint8Array, contentType: string): {
+    width: number;
+    height: number;
+} | null;
+/** Width and height of an SVG from its attributes, else from its viewBox. */
+export declare function svgSize(svg: string): {
+    width: number;
+    height: number;
+} | null;
+/** Decodes a `data:` URL; null for anything else. */
+export declare function decodeDataUrl(url: string): {
+    bytes: Uint8Array;
+    contentType: string;
+} | null;
+/**
+ * Turns the requests into pictures: fetched or decoded, converted to PNG where Word needs it, sized
+ * (the given size, else the natural size at 96 dpi, never wider than `maxWidthEmu`), and shared when
+ * the same picture appears again. A picture that cannot be read becomes nothing and a warning.
+ */
+export declare class DrawingResolver {
+    private readonly requests;
+    private readonly host;
+    private readonly mediaPrefix;
+    readonly media: PreparedMedia[];
+    readonly warnings: string[];
+    private readonly resolved;
+    private readonly byKey;
+    private imageBytes;
+    constructor(requests: readonly OfficeDrawingRequest[], host: OfficeImageHost | undefined, mediaPrefix: string);
+    resolve(index: number, maxWidthEmu: number): Promise<ResolvedDrawing>;
+    private resolveOne;
+    private prepare;
+}
+/** The text width of a Word part's last section in EMU; 16 cm when it names none. */
+export declare function textWidthEmu(xml: string): number;
+/** A picture in a run, as Word writes one (`wp:inline`); namespaces are declared on the elements. */
+export declare function inlinePicture(picture: Extract<ResolvedDrawing, {
+    kind: 'picture';
+}>, rId: string, id: number): string;
+/** The highest drawing id of a part, so new pictures start after it. */
+export declare function highestDrawingId(xml: string): number;
+/**
+ * Replaces the drawing placeholders of a filled Word part. A placeholder inside `w:t` splits its run:
+ * the text before stays in the run, the picture (or page break) gets a run of its own with the same
+ * run properties, and the text after continues in a copy of the run.
+ */
+export declare function placeDrawings(xml: string, pattern: RegExp, markupFor: (index: number) => string): string;
+/** Adds image relationships to a part's `.rels` (created when the part has none). */
+export declare function withRelationships(rels: string | null, relationships: Array<{
+    id: string;
+    target: string;
+}>): string;
+/** Relationship ids a `.rels` already uses. */
+export declare function relationshipIds(rels: string | null): Set<string>;
+/** `[Content_Types].xml` with defaults for the picture formats it lacks. */
+export declare function withImageTypes(contentTypes: string, extensions: ReadonlySet<'png' | 'jpeg'>): string;
+/** `word/document.xml` → `word/_rels/document.xml.rels`. */
+export declare function relsPathOf(part: string): string;

package/types/lib/office/errors.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Failures of the office container code (spec 22 §2.1, §8). The codes are the API's problem codes, so
+ * the gateway and the worker pass them on unchanged.
+ */
+export type OfficeErrorCode = 'file_type_unsupported' | 'source_encrypted' | 'office_document_invalid' | 'office_document_too_large';
+export declare class OfficeError extends Error {
+    readonly code: OfficeErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: OfficeErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** Limits of spec 22 §2.1 and §4.3. */
+export declare const officeLimits: {
+    /** Entries in one container. */
+    readonly maxEntries: 2000;
+    /** Sum of the uncompressed sizes the central directory declares. */
+    readonly maxDeclaredBytes: number;
+    /** One part we inflate; enforced while inflating, because the declared size can lie. */
+    readonly maxPartBytes: number;
+    /** A conversion upload or a template file. */
+    readonly maxFileBytes: number;
+};

package/types/lib/office/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Failures of the office container code (spec 22 §2.1, §8). The codes are the API's problem codes, so
+ * the gateway and the worker pass them on unchanged.
+ */
+export type OfficeErrorCode = 'file_type_unsupported' | 'source_encrypted' | 'office_document_invalid' | 'office_document_too_large';
+export declare class OfficeError extends Error {
+    readonly code: OfficeErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: OfficeErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** Limits of spec 22 §2.1 and §4.3. */
+export declare const officeLimits: {
+    /** Entries in one container. */
+    readonly maxEntries: 2000;
+    /** Sum of the uncompressed sizes the central directory declares. */
+    readonly maxDeclaredBytes: number;
+    /** One part we inflate; enforced while inflating, because the declared size can lie. */
+    readonly maxPartBytes: number;
+    /** A conversion upload or a template file. */
+    readonly maxFileBytes: number;
+};

package/types/lib/office/fonts.d.cts

@@ -0,0 +1,21 @@
+import type { OfficeDiagnostic } from './tags.cjs';
+import { type ZipArchive } from './zip.cjs';
+/**
+ * Fonts an office document uses and whether the converter has them (spec 22 §4.6). A converted
+ * document renders only with fonts the sidecar has or the document embeds; the list of installed
+ * families is passed in (`OFFICE_FONT_FAMILIES` in `@formfeed/api-types`, generated from the image),
+ * so the engine stays free of that dependency.
+ */
+export interface DocumentFont {
+    name: string;
+    embedded: boolean;
+}
+/** Office fonts LibreOffice replaces with a family of the same metrics, so lines break the same. */
+export declare const METRIC_COMPATIBLE: Readonly<Record<string, string>>;
+export declare function documentFonts(archive: ZipArchive): DocumentFont[];
+/**
+ * One diagnostic per font the converter will replace: info when a metric-compatible family stands
+ * in, a warning otherwise, because the layout will differ (Aptos, Office's default since 2024, has no
+ * free substitute).
+ */
+export declare function fontDiagnostics(fonts: readonly DocumentFont[], installed: readonly string[], part?: string): OfficeDiagnostic[];

package/types/lib/office/fonts.d.ts

@@ -0,0 +1,21 @@
+import type { OfficeDiagnostic } from './tags.js';
+import { type ZipArchive } from './zip.js';
+/**
+ * Fonts an office document uses and whether the converter has them (spec 22 §4.6). A converted
+ * document renders only with fonts the sidecar has or the document embeds; the list of installed
+ * families is passed in (`OFFICE_FONT_FAMILIES` in `@formfeed/api-types`, generated from the image),
+ * so the engine stays free of that dependency.
+ */
+export interface DocumentFont {
+    name: string;
+    embedded: boolean;
+}
+/** Office fonts LibreOffice replaces with a family of the same metrics, so lines break the same. */
+export declare const METRIC_COMPATIBLE: Readonly<Record<string, string>>;
+export declare function documentFonts(archive: ZipArchive): DocumentFont[];
+/**
+ * One diagnostic per font the converter will replace: info when a metric-compatible family stands
+ * in, a warning otherwise, because the layout will differ (Aptos, Office's default since 2024, has no
+ * free substitute).
+ */
+export declare function fontDiagnostics(fonts: readonly DocumentFont[], installed: readonly string[], part?: string): OfficeDiagnostic[];

package/types/lib/office/ids.d.cts

@@ -0,0 +1 @@
+export declare function makeIdsUnique(xml: string): string;

package/types/lib/office/ids.d.ts

@@ -0,0 +1 @@
+export declare function makeIdsUnique(xml: string): string;

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

@@ -0,0 +1,18 @@
+/**
+ * `@formfeed/engine/office`: the office container code of spec 22 (ZIP, format detection, the checks
+ * and the sanitiser of §2.1). No template engine is imported here, so the gateway Worker can use it
+ * without bundling Nunjucks, Liquid or Handlebars.
+ */
+export { OfficeError, officeLimits, type OfficeErrorCode } from './errors.cjs';
+export { cfbStreamNames, detectOfficeFormat, hasDoctype, isHtml, isMacroPart, officeContentTypes, officeFormats, type DetectedOffice, type OdfFormat, type OfficeFormat, type OoxmlFormat, } from './detect.cjs';
+export { parseAttributes, remoteResourceCount, removeExternalRelationships, sanitiseForConversion, type RemovedRelationship, type SanitisedDocument, } from './sanitise.cjs';
+export { STRUCTURAL_ELEMENT, applyStructure, blockRole, dropTaggedFallbacks, type StructuredPart } from './structure.cjs';
+export { makeIdsUnique } from './ids.cjs';
+export { starterDocument } from './starter.cjs';
+export { starterPresentation } from './starter-pptx.cjs';
+export { officeDrawingLimits, type OfficeImageHost } from './drawings.cjs';
+export { METRIC_COMPATIBLE, documentFonts, fontDiagnostics, type DocumentFont } from './fonts.cjs';
+export { findTags, listTags, normaliseTags, paragraphAtSource, undoAutocorrect, type NormalisedTags, type OfficeDiagnostic, type OfficeDiagnosticCode, type OfficeTag, } from './tags.cjs';
+export { createNonce, fromTemplateOutput, layoutText, toTemplateSource, type FilledPart, type TemplateSource, type TextFlavour, } from './template-text.cjs';
+export { assertWellFormed, decodeText, escapeText, stripForbidden, tokenize, type XmlToken } from './xml.cjs';
+export { crc32, decodeXml, isSafeEntryName, isZip, readEntry, readText, readZip, writeZip, type ZipArchive, type ZipEntry, type ZipLimits, type ZipWriteEntry, } from './zip.cjs';

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

@@ -0,0 +1,18 @@
+/**
+ * `@formfeed/engine/office`: the office container code of spec 22 (ZIP, format detection, the checks
+ * and the sanitiser of §2.1). No template engine is imported here, so the gateway Worker can use it
+ * without bundling Nunjucks, Liquid or Handlebars.
+ */
+export { OfficeError, officeLimits, type OfficeErrorCode } from './errors.js';
+export { cfbStreamNames, detectOfficeFormat, hasDoctype, isHtml, isMacroPart, officeContentTypes, officeFormats, type DetectedOffice, type OdfFormat, type OfficeFormat, type OoxmlFormat, } from './detect.js';
+export { parseAttributes, remoteResourceCount, removeExternalRelationships, sanitiseForConversion, type RemovedRelationship, type SanitisedDocument, } from './sanitise.js';
+export { STRUCTURAL_ELEMENT, applyStructure, blockRole, dropTaggedFallbacks, type StructuredPart } from './structure.js';
+export { makeIdsUnique } from './ids.js';
+export { starterDocument } from './starter.js';
+export { starterPresentation } from './starter-pptx.js';
+export { officeDrawingLimits, type OfficeImageHost } from './drawings.js';
+export { METRIC_COMPATIBLE, documentFonts, fontDiagnostics, type DocumentFont } from './fonts.js';
+export { findTags, listTags, normaliseTags, paragraphAtSource, undoAutocorrect, type NormalisedTags, type OfficeDiagnostic, type OfficeDiagnosticCode, type OfficeTag, } from './tags.js';
+export { createNonce, fromTemplateOutput, layoutText, toTemplateSource, type FilledPart, type TemplateSource, type TextFlavour, } from './template-text.js';
+export { assertWellFormed, decodeText, escapeText, stripForbidden, tokenize, type XmlToken } from './xml.js';
+export { crc32, decodeXml, isSafeEntryName, isZip, readEntry, readText, readZip, writeZip, type ZipArchive, type ZipEntry, type ZipLimits, type ZipWriteEntry, } from './zip.js';

package/types/lib/office/render.d.cts

@@ -0,0 +1,79 @@
+import { EngineSyntaxError, RenderError } from '../errors.cjs';
+import type { EngineId, RenderContext, VariableRef } from '../types.cjs';
+import { type OfficeImageHost } from './drawings.cjs';
+import { type DocumentFont } from './fonts.cjs';
+import { type OfficeDiagnostic, type OfficeTag } from './tags.cjs';
+/**
+ * Fills an office template (spec 22 §4.3): the office counterpart of `renderVersion`, the same code in
+ * the browser (quick preview) and the render-worker. Imports the template engines, so it lives in the
+ * main entry, not in `@formfeed/engine/office`.
+ */
+export interface OfficeRenderOptions {
+    engine: EngineId;
+    data: unknown;
+    /** Locale, helpers and limits as for HTML templates; `mode` is set to `office` here. */
+    context: RenderContext;
+    /** For tests: the source of the placeholder nonce. */
+    random?: () => number;
+    /**
+     * Loads and draws pictures for `image`, `qrcode`, `barcode` and `epcQr` (spec 22 §4.4): the
+     * render-worker's asset cache and Chromium, or the browser's fetch and canvas. Without one, only
+     * PNG and JPEG data URLs are placed and everything else becomes a warning.
+     */
+    images?: OfficeImageHost;
+}
+export interface OfficeRenderResult {
+    bytes: Uint8Array;
+    format: 'docx' | 'pptx';
+    warnings: string[];
+    /** Info and warnings; errors throw `OfficeTemplateError` instead. */
+    diagnostics: OfficeDiagnostic[];
+}
+/**
+ * A template that cannot be filled as written; the diagnostics say where. An engine's syntax or
+ * runtime error travels as `cause`, so callers can tell the two apart.
+ */
+export declare class OfficeTemplateError extends Error {
+    readonly diagnostics: OfficeDiagnostic[];
+    readonly part?: string | undefined;
+    readonly cause?: (EngineSyntaxError | RenderError) | undefined;
+    constructor(message: string, diagnostics: OfficeDiagnostic[], part?: string | undefined, cause?: (EngineSyntaxError | RenderError) | undefined);
+    /** `template_syntax_error` or `template_runtime_error`, as the API reports it. */
+    get code(): 'template_syntax_error' | 'template_runtime_error';
+}
+/** Filled parts together may not exceed this before zipping (spec 22 §4.3 step 6). */
+export declare const OFFICE_FILLED_MAX_BYTES: number;
+/** A diagnostic of the office template page: the office checks' codes, or an engine's. */
+export type OfficeAnalysisDiagnostic = Omit<OfficeDiagnostic, 'code'> & {
+    code: string;
+};
+export interface OfficeAnalysis {
+    format: 'docx' | 'pptx';
+    /** Every tag, in part and document order. */
+    tags: OfficeTag[];
+    /** Structure, tag and engine diagnostics, and the fonts the converter replaces. */
+    diagnostics: OfficeAnalysisDiagnostic[];
+    /** Data paths the template reads, for the schema and data panels. */
+    variables: Array<Pick<VariableRef, 'path' | 'kind'>>;
+    fonts: DocumentFont[];
+}
+/**
+ * `analyze` over an office template (spec 22 §4.3, §6): what the office template page lists. The
+ * engine analyses each part's template text, and its positions are turned into paragraphs, because
+ * a line of the extracted text means nothing to someone looking at the document. Throws `OfficeError`
+ * for a file that is not a Word or PowerPoint template.
+ */
+export declare function analyzeOffice(file: Uint8Array, options: {
+    engine: EngineId;
+    sampleData?: unknown;
+    installedFonts?: readonly string[];
+}): OfficeAnalysis;
+/**
+ * The parts a template can fill (body, headers, footers and notes of Word; slides and notes of
+ * PowerPoint) with their XML, in archive order: what the dev kit's snapshots compare.
+ */
+export declare function officeTextParts(file: Uint8Array): Array<{
+    name: string;
+    xml: string;
+}>;
+export declare function renderOffice(file: Uint8Array, options: OfficeRenderOptions): Promise<OfficeRenderResult>;

package/types/lib/office/render.d.ts

@@ -0,0 +1,79 @@
+import { EngineSyntaxError, RenderError } from '../errors.js';
+import type { EngineId, RenderContext, VariableRef } from '../types.js';
+import { type OfficeImageHost } from './drawings.js';
+import { type DocumentFont } from './fonts.js';
+import { type OfficeDiagnostic, type OfficeTag } from './tags.js';
+/**
+ * Fills an office template (spec 22 §4.3): the office counterpart of `renderVersion`, the same code in
+ * the browser (quick preview) and the render-worker. Imports the template engines, so it lives in the
+ * main entry, not in `@formfeed/engine/office`.
+ */
+export interface OfficeRenderOptions {
+    engine: EngineId;
+    data: unknown;
+    /** Locale, helpers and limits as for HTML templates; `mode` is set to `office` here. */
+    context: RenderContext;
+    /** For tests: the source of the placeholder nonce. */
+    random?: () => number;
+    /**
+     * Loads and draws pictures for `image`, `qrcode`, `barcode` and `epcQr` (spec 22 §4.4): the
+     * render-worker's asset cache and Chromium, or the browser's fetch and canvas. Without one, only
+     * PNG and JPEG data URLs are placed and everything else becomes a warning.
+     */
+    images?: OfficeImageHost;
+}
+export interface OfficeRenderResult {
+    bytes: Uint8Array;
+    format: 'docx' | 'pptx';
+    warnings: string[];
+    /** Info and warnings; errors throw `OfficeTemplateError` instead. */
+    diagnostics: OfficeDiagnostic[];
+}
+/**
+ * A template that cannot be filled as written; the diagnostics say where. An engine's syntax or
+ * runtime error travels as `cause`, so callers can tell the two apart.
+ */
+export declare class OfficeTemplateError extends Error {
+    readonly diagnostics: OfficeDiagnostic[];
+    readonly part?: string | undefined;
+    readonly cause?: (EngineSyntaxError | RenderError) | undefined;
+    constructor(message: string, diagnostics: OfficeDiagnostic[], part?: string | undefined, cause?: (EngineSyntaxError | RenderError) | undefined);
+    /** `template_syntax_error` or `template_runtime_error`, as the API reports it. */
+    get code(): 'template_syntax_error' | 'template_runtime_error';
+}
+/** Filled parts together may not exceed this before zipping (spec 22 §4.3 step 6). */
+export declare const OFFICE_FILLED_MAX_BYTES: number;
+/** A diagnostic of the office template page: the office checks' codes, or an engine's. */
+export type OfficeAnalysisDiagnostic = Omit<OfficeDiagnostic, 'code'> & {
+    code: string;
+};
+export interface OfficeAnalysis {
+    format: 'docx' | 'pptx';
+    /** Every tag, in part and document order. */
+    tags: OfficeTag[];
+    /** Structure, tag and engine diagnostics, and the fonts the converter replaces. */
+    diagnostics: OfficeAnalysisDiagnostic[];
+    /** Data paths the template reads, for the schema and data panels. */
+    variables: Array<Pick<VariableRef, 'path' | 'kind'>>;
+    fonts: DocumentFont[];
+}
+/**
+ * `analyze` over an office template (spec 22 §4.3, §6): what the office template page lists. The
+ * engine analyses each part's template text, and its positions are turned into paragraphs, because
+ * a line of the extracted text means nothing to someone looking at the document. Throws `OfficeError`
+ * for a file that is not a Word or PowerPoint template.
+ */
+export declare function analyzeOffice(file: Uint8Array, options: {
+    engine: EngineId;
+    sampleData?: unknown;
+    installedFonts?: readonly string[];
+}): OfficeAnalysis;
+/**
+ * The parts a template can fill (body, headers, footers and notes of Word; slides and notes of
+ * PowerPoint) with their XML, in archive order: what the dev kit's snapshots compare.
+ */
+export declare function officeTextParts(file: Uint8Array): Array<{
+    name: string;
+    xml: string;
+}>;
+export declare function renderOffice(file: Uint8Array, options: OfficeRenderOptions): Promise<OfficeRenderResult>;

package/types/lib/office/sanitise.d.cts

@@ -0,0 +1,35 @@
+import { type OfficeFormat } from './detect.cjs';
+/**
+ * Prepares a customer document for LibreOffice (spec 22 §2.1). Detection and the container checks
+ * run first; then every XML part is checked for a DOCTYPE, and OOXML relationship parts lose their
+ * external relationships except hyperlinks, so nothing in the document asks LibreOffice to load a
+ * remote or local resource. The sidecar refuses such loads as well; this is the layer we control.
+ */
+export interface RemovedRelationship {
+    part: string;
+    id: string;
+    type: string;
+    target: string;
+}
+export interface SanitisedDocument {
+    format: OfficeFormat;
+    /** The input itself when nothing had to change. */
+    bytes: Uint8Array;
+    removed: RemovedRelationship[];
+    /** What the customer should know about the conversion, for the render's warnings. */
+    notes: string[];
+}
+/** How many remote resources an HTML document references; they stay empty in the PDF. */
+export declare function remoteResourceCount(html: string): number;
+export declare function sanitiseForConversion(bytes: Uint8Array): SanitisedDocument;
+/**
+ * Removes every `<Relationship TargetMode="External">` whose type is not a hyperlink. An allowlist,
+ * not a list of loading types: a type we do not know is not one we let LibreOffice resolve.
+ * References to a removed id stay in the source part; LibreOffice skips a relationship it cannot
+ * find, which the sidecar tests keep proven.
+ */
+export declare function removeExternalRelationships(xml: string): {
+    xml: string;
+    removed: Omit<RemovedRelationship, 'part'>[];
+};
+export declare function parseAttributes(source: string): Record<string, string>;

package/types/lib/office/sanitise.d.ts

@@ -0,0 +1,35 @@
+import { type OfficeFormat } from './detect.js';
+/**
+ * Prepares a customer document for LibreOffice (spec 22 §2.1). Detection and the container checks
+ * run first; then every XML part is checked for a DOCTYPE, and OOXML relationship parts lose their
+ * external relationships except hyperlinks, so nothing in the document asks LibreOffice to load a
+ * remote or local resource. The sidecar refuses such loads as well; this is the layer we control.
+ */
+export interface RemovedRelationship {
+    part: string;
+    id: string;
+    type: string;
+    target: string;
+}
+export interface SanitisedDocument {
+    format: OfficeFormat;
+    /** The input itself when nothing had to change. */
+    bytes: Uint8Array;
+    removed: RemovedRelationship[];
+    /** What the customer should know about the conversion, for the render's warnings. */
+    notes: string[];
+}
+/** How many remote resources an HTML document references; they stay empty in the PDF. */
+export declare function remoteResourceCount(html: string): number;
+export declare function sanitiseForConversion(bytes: Uint8Array): SanitisedDocument;
+/**
+ * Removes every `<Relationship TargetMode="External">` whose type is not a hyperlink. An allowlist,
+ * not a list of loading types: a type we do not know is not one we let LibreOffice resolve.
+ * References to a removed id stay in the source part; LibreOffice skips a relationship it cannot
+ * find, which the sidecar tests keep proven.
+ */
+export declare function removeExternalRelationships(xml: string): {
+    xml: string;
+    removed: Omit<RemovedRelationship, 'part'>[];
+};
+export declare function parseAttributes(source: string): Record<string, string>;

package/types/lib/office/slides.d.cts

@@ -0,0 +1,47 @@
+import type { ResolvedDrawing } from './drawings.cjs';
+/**
+ * Pictures on slides (spec 22 §10 step 7). A slide cannot hold a picture inside text, so a drawing
+ * placeholder in a text box becomes a picture shape (`p:pic`) beside it:
+ *
+ * - a text box that holds nothing but drawings is replaced by them, placed in its box, so a member
+ *   draws a box where the code goes and types `{{ qrcode(url) }}` into it;
+ * - otherwise the placeholder is removed from the text and the picture is placed over the box, in
+ *   front of the text;
+ * - a picture without a size of its own is fitted into the box, keeping its aspect; several pictures
+ *   share the box from top to bottom. A box that grows with its text (`a:spAutoFit`, PowerPoint's
+ *   default for text boxes) is only as high as one line, so there the width alone decides;
+ * - a shape whose position comes from the slide layout (no `a:xfrm` of its own) puts the pictures in
+ *   the middle of the slide.
+ */
+export interface SlideBox {
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+}
+/** `p:sldSz` of `ppt/presentation.xml`; 16:9 at 33.867 cm by 19.05 cm when it names none. */
+export declare function slideSize(presentation: string | null): {
+    cx: number;
+    cy: number;
+};
+/** A picture shape, with the namespaces it uses declared on itself. */
+export declare function slidePicture(picture: Extract<ResolvedDrawing, {
+    kind: 'picture';
+}>, rId: string, id: number, box: SlideBox): string;
+/** Where each picture goes: its own size or fitted into its share of the box, centred in it. */
+export declare function layoutPictures(pictures: ReadonlyArray<Extract<ResolvedDrawing, {
+    kind: 'picture';
+}>>, box: SlideBox, growsWithText?: boolean): SlideBox[];
+/**
+ * Replaces the drawing placeholders of a filled slide (or notes) part with picture shapes. `picture`
+ * returns the placed markup for a resolved drawing, with its relationship and id.
+ */
+export declare function placeSlidePictures(xml: string, pattern: RegExp, drawingFor: (index: number) => ResolvedDrawing | undefined, pictureMarkup: (picture: Extract<ResolvedDrawing, {
+    kind: 'picture';
+}>, box: SlideBox) => string, slide: {
+    cx: number;
+    cy: number;
+}): {
+    xml: string;
+    warnings: string[];
+};