@formfeed/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1,47 @@
+import type { ResolvedDrawing } from './drawings.js';
+/**
+ * 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[];
+};

package/types/lib/office/starter-pptx.d.cts

@@ -0,0 +1,6 @@
+import type { EngineId } from '../types.cjs';
+/** The starter presentation for an engine, with the sample data that fills it. */
+export declare function starterPresentation(engine: EngineId): {
+    bytes: Uint8Array;
+    sampleData: Record<string, unknown>;
+};

package/types/lib/office/starter-pptx.d.ts

@@ -0,0 +1,6 @@
+import type { EngineId } from '../types.js';
+/** The starter presentation for an engine, with the sample data that fills it. */
+export declare function starterPresentation(engine: EngineId): {
+    bytes: Uint8Array;
+    sampleData: Record<string, unknown>;
+};

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

@@ -0,0 +1,24 @@
+import type { EngineId } from '../types.cjs';
+/** The tags of one engine: a value, a value through a helper, and a loop over the lines. */
+export declare function starterTags(engine: EngineId): {
+    number: string;
+    customer: string;
+    date: string;
+    loopOpen: string;
+    line: string;
+    lineTotal: string;
+    loopClose: string;
+    total: string;
+    ifOpen: string;
+    note: string;
+    ifClose: string;
+    code: string;
+    codeFit: string;
+};
+/** The starter document for an engine, with the sample data that fills it. */
+export declare function starterDocument(engine: EngineId): {
+    bytes: Uint8Array;
+    sampleData: Record<string, unknown>;
+};
+/** The data the starter files are filled with; a fresh copy each time. */
+export declare function starterSampleData(): Record<string, unknown>;

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

@@ -0,0 +1,24 @@
+import type { EngineId } from '../types.js';
+/** The tags of one engine: a value, a value through a helper, and a loop over the lines. */
+export declare function starterTags(engine: EngineId): {
+    number: string;
+    customer: string;
+    date: string;
+    loopOpen: string;
+    line: string;
+    lineTotal: string;
+    loopClose: string;
+    total: string;
+    ifOpen: string;
+    note: string;
+    ifClose: string;
+    code: string;
+    codeFit: string;
+};
+/** The starter document for an engine, with the sample data that fills it. */
+export declare function starterDocument(engine: EngineId): {
+    bytes: Uint8Array;
+    sampleData: Record<string, unknown>;
+};
+/** The data the starter files are filled with; a fresh copy each time. */
+export declare function starterSampleData(): Record<string, unknown>;

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

@@ -0,0 +1,51 @@
+import type { OfficeDiagnostic } from './tags.cjs';
+import { type XmlToken } from './xml.cjs';
+/**
+ * Structural tags (spec 22 §4.3 step 5). A block tag alone in its paragraph stands for the paragraph:
+ * a loop repeats the paragraphs between its tags, not the text inside one. If that paragraph is also
+ * the only content of its table row, the tag stands for the row, so a loop repeats the rows between.
+ *
+ * The rewrite happens on the part's XML before it becomes template text: the paragraph or row is
+ * replaced by a `<ff:tag>` element holding only the tag. `toTemplateSource` reads that element's text
+ * like a text element, and `fromTemplateOutput` removes the element again after rendering. Structure
+ * the file format needs survives: a paragraph that carries a section break stays (empty), and a cell
+ * never ends up without a paragraph.
+ */
+export declare const STRUCTURAL_ELEMENT = "ff:tag";
+export interface StructuredPart {
+    xml: string;
+    diagnostics: OfficeDiagnostic[];
+}
+export interface Span {
+    name: string;
+    start: number;
+    end: number;
+    parent: Span | null;
+    children: Span[];
+}
+type Role = 'open' | 'close' | 'middle' | 'single';
+/** What a tag does to structure, or null when the text is not exactly one tag. */
+export declare function blockRole(text: string): {
+    role: Role;
+    keyword: string;
+} | null;
+/**
+ * Text boxes carry a VML copy of their text in `mc:Fallback`, which would be filled on its own and
+ * loop twice. A fallback holding a tag is removed; Word 2010 and later and LibreOffice read the choice.
+ */
+export declare function dropTaggedFallbacks(xml: string, part?: string): string;
+export declare function applyStructure(xml: string, part: string): StructuredPart;
+/**
+ * A loop over an empty list can leave a table without rows, which Word and PowerPoint refuse (spec 22
+ * §4.3 step 5): such a Word table is removed, and so is the graphic frame of such a slide table.
+ */
+export declare function removeEmptyTables(xml: string): string;
+/** Builds the element tree; `start`/`end` are token indexes of the open and close tags. */
+export declare function buildSpans(tokens: XmlToken[]): Span;
+/** Joins the tokens back, with the token ranges replaced; an empty range inserts before `start`. */
+export declare function rewrite(tokens: XmlToken[], replacements: Array<{
+    start: number;
+    end: number;
+    text: string;
+}>): string;
+export {};

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

@@ -0,0 +1,51 @@
+import type { OfficeDiagnostic } from './tags.js';
+import { type XmlToken } from './xml.js';
+/**
+ * Structural tags (spec 22 §4.3 step 5). A block tag alone in its paragraph stands for the paragraph:
+ * a loop repeats the paragraphs between its tags, not the text inside one. If that paragraph is also
+ * the only content of its table row, the tag stands for the row, so a loop repeats the rows between.
+ *
+ * The rewrite happens on the part's XML before it becomes template text: the paragraph or row is
+ * replaced by a `<ff:tag>` element holding only the tag. `toTemplateSource` reads that element's text
+ * like a text element, and `fromTemplateOutput` removes the element again after rendering. Structure
+ * the file format needs survives: a paragraph that carries a section break stays (empty), and a cell
+ * never ends up without a paragraph.
+ */
+export declare const STRUCTURAL_ELEMENT = "ff:tag";
+export interface StructuredPart {
+    xml: string;
+    diagnostics: OfficeDiagnostic[];
+}
+export interface Span {
+    name: string;
+    start: number;
+    end: number;
+    parent: Span | null;
+    children: Span[];
+}
+type Role = 'open' | 'close' | 'middle' | 'single';
+/** What a tag does to structure, or null when the text is not exactly one tag. */
+export declare function blockRole(text: string): {
+    role: Role;
+    keyword: string;
+} | null;
+/**
+ * Text boxes carry a VML copy of their text in `mc:Fallback`, which would be filled on its own and
+ * loop twice. A fallback holding a tag is removed; Word 2010 and later and LibreOffice read the choice.
+ */
+export declare function dropTaggedFallbacks(xml: string, part?: string): string;
+export declare function applyStructure(xml: string, part: string): StructuredPart;
+/**
+ * A loop over an empty list can leave a table without rows, which Word and PowerPoint refuse (spec 22
+ * §4.3 step 5): such a Word table is removed, and so is the graphic frame of such a slide table.
+ */
+export declare function removeEmptyTables(xml: string): string;
+/** Builds the element tree; `start`/`end` are token indexes of the open and close tags. */
+export declare function buildSpans(tokens: XmlToken[]): Span;
+/** Joins the tokens back, with the token ranges replaced; an empty range inserts before `start`. */
+export declare function rewrite(tokens: XmlToken[], replacements: Array<{
+    start: number;
+    end: number;
+    text: string;
+}>): string;
+export {};

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

@@ -0,0 +1,51 @@
+import { type TemplateSource } from './template-text.cjs';
+/**
+ * Normalising the tags Word leaves behind (spec 22 §4.3 step 4).
+ *
+ * Word splits typed text into several runs — spell-check marks, revision ids, a changed font — so
+ * `{{ customer.name }}` often sits in three `<w:r>` elements, and the template source that comes out
+ * of `toTemplateSource` has markup placeholders inside the tag. Here a tag's characters move into the
+ * run where the tag starts (which keeps that run's formatting) by dropping the run boundaries in
+ * between, and Word's autocorrect inside the tag is undone, because `{{ date(x, "short") }}` becomes
+ * curly quotes as the customer types and would otherwise be a syntax error nobody can see.
+ *
+ * A tag that crosses a paragraph, a hyperlink, a content control, a field or a tracked change is not
+ * merged: moving the text would move it out of its element. It reports `office-tag-spans-elements`.
+ */
+export type OfficeDiagnosticCode = 'office-tag-spans-elements' | 'office-tag-autocorrected' | 'office-tag-in-field' | 'office-block-unbalanced' | 'office-reference-in-loop' | 'office-font-substituted' | 'unsupported-in-office';
+export interface OfficeDiagnostic {
+    severity: 'error' | 'warning' | 'info';
+    code: OfficeDiagnosticCode;
+    message: string;
+    /** Part the diagnostic belongs to, `word/document.xml`. */
+    part: string;
+    /** 1-based paragraph in that part, as the editor lists it. */
+    paragraph: number;
+    /** The tag as it reads after normalisation, for the message. */
+    text: string;
+}
+export interface NormalisedTags {
+    template: TemplateSource;
+    diagnostics: OfficeDiagnostic[];
+}
+export declare function normaliseTags(template: TemplateSource, part: string): NormalisedTags;
+/** A tag as the office template page lists it (spec 22 §6). */
+export interface OfficeTag {
+    part: string;
+    paragraph: number;
+    /** The tag as the engine reads it, on one line. */
+    text: string;
+    /** `output` for `{{ }}`, `block` for `{% %}` and Handlebars blocks, `comment` for `{# #}`. */
+    kind: 'output' | 'block' | 'comment';
+}
+/** Every tag of a (normalised) part with its paragraph. */
+export declare function listTags(template: TemplateSource, part: string): OfficeTag[];
+/** The 1-based paragraph an offset of the template source sits in (engine diagnostics). */
+export declare function paragraphAtSource(template: TemplateSource, offset: number): number;
+/** Undoes what Word's autocorrect does to a tag while it is typed. */
+export declare function undoAutocorrect(tag: string): string;
+/** Tags in text, delimiters included; unclosed openers are ignored (the engine reports them). */
+export declare function findTags(text: string): Array<{
+    start: number;
+    end: number;
+}>;

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

@@ -0,0 +1,51 @@
+import { type TemplateSource } from './template-text.js';
+/**
+ * Normalising the tags Word leaves behind (spec 22 §4.3 step 4).
+ *
+ * Word splits typed text into several runs — spell-check marks, revision ids, a changed font — so
+ * `{{ customer.name }}` often sits in three `<w:r>` elements, and the template source that comes out
+ * of `toTemplateSource` has markup placeholders inside the tag. Here a tag's characters move into the
+ * run where the tag starts (which keeps that run's formatting) by dropping the run boundaries in
+ * between, and Word's autocorrect inside the tag is undone, because `{{ date(x, "short") }}` becomes
+ * curly quotes as the customer types and would otherwise be a syntax error nobody can see.
+ *
+ * A tag that crosses a paragraph, a hyperlink, a content control, a field or a tracked change is not
+ * merged: moving the text would move it out of its element. It reports `office-tag-spans-elements`.
+ */
+export type OfficeDiagnosticCode = 'office-tag-spans-elements' | 'office-tag-autocorrected' | 'office-tag-in-field' | 'office-block-unbalanced' | 'office-reference-in-loop' | 'office-font-substituted' | 'unsupported-in-office';
+export interface OfficeDiagnostic {
+    severity: 'error' | 'warning' | 'info';
+    code: OfficeDiagnosticCode;
+    message: string;
+    /** Part the diagnostic belongs to, `word/document.xml`. */
+    part: string;
+    /** 1-based paragraph in that part, as the editor lists it. */
+    paragraph: number;
+    /** The tag as it reads after normalisation, for the message. */
+    text: string;
+}
+export interface NormalisedTags {
+    template: TemplateSource;
+    diagnostics: OfficeDiagnostic[];
+}
+export declare function normaliseTags(template: TemplateSource, part: string): NormalisedTags;
+/** A tag as the office template page lists it (spec 22 §6). */
+export interface OfficeTag {
+    part: string;
+    paragraph: number;
+    /** The tag as the engine reads it, on one line. */
+    text: string;
+    /** `output` for `{{ }}`, `block` for `{% %}` and Handlebars blocks, `comment` for `{# #}`. */
+    kind: 'output' | 'block' | 'comment';
+}
+/** Every tag of a (normalised) part with its paragraph. */
+export declare function listTags(template: TemplateSource, part: string): OfficeTag[];
+/** The 1-based paragraph an offset of the template source sits in (engine diagnostics). */
+export declare function paragraphAtSource(template: TemplateSource, offset: number): number;
+/** Undoes what Word's autocorrect does to a tag while it is typed. */
+export declare function undoAutocorrect(tag: string): string;
+/** Tags in text, delimiters included; unclosed openers are ignored (the engine reports them). */
+export declare function findTags(text: string): Array<{
+    start: number;
+    end: number;
+}>;

package/types/lib/office/template-text.d.cts

@@ -0,0 +1,59 @@
+/**
+ * How an office part becomes template source and back (spec 22 §4.3 steps 5–7).
+ *
+ * Only the characters of text elements (`w:t`, `a:t`) are template text, decoded. Every run of markup
+ * between them becomes one placeholder, `U+E000 <nonce> <index> U+E001`, so the engine sees plain text
+ * with opaque markers and renders with its escaping switched off. On the way back every text segment is
+ * escaped and every placeholder restored. Whatever an expression prints therefore lands as text: `safe`,
+ * `{{{ }}}`, `raw`, `{% echo %}` and `capture` cannot put markup into the document, and nothing is
+ * escaped twice. The nonce is random per render, so data cannot forge a placeholder.
+ */
+export type TextFlavour = 'wordprocessing' | 'drawing';
+/**
+ * One run of markup between two pieces of text. What it contains decides whether a tag may span it:
+ * run boundaries inside a paragraph may be merged away, a paragraph or hyperlink boundary may not
+ * (`office/tags.ts`).
+ */
+export interface MarkupPiece {
+    raw: string;
+    /** Paragraphs (`w:p`, `a:p`) that open in this piece; the index of the paragraph a tag sits in. */
+    paragraphOpens: number;
+    /** A paragraph starts or ends here, so text on both sides is not in the same paragraph. */
+    paragraphBoundary: boolean;
+    /**
+     * Something other than a plain run boundary: a hyperlink, a content control, a tracked change, a
+     * field, an alternate-content branch. Merging across it would move text out of its element.
+     */
+    containerBoundary: boolean;
+    /**
+     * The piece ends inside a text element, so text the template prints after it is document text.
+     * Only the last piece of a part ends outside one.
+     */
+    endsInText?: boolean;
+}
+export interface TemplateSource {
+    /** The part as template text: decoded text of the text elements, placeholders for the markup. */
+    source: string;
+    markup: MarkupPiece[];
+    nonce: string;
+    flavour: TextFlavour;
+}
+export interface FilledPart {
+    xml: string;
+    /** Characters XML does not allow that values contained and that were removed. */
+    removedCharacters: number;
+}
+/** The placeholder of markup piece `index`, as it appears in the template source. */
+export declare function placeholderFor(nonce: string, index: number): string;
+/** Matches any placeholder of this template, with the piece index in group 1. */
+export declare function placeholderPattern(nonce: string): RegExp;
+export declare function createNonce(random?: () => number): string;
+export declare function toTemplateSource(xml: string, flavour: TextFlavour, nonce: string, part?: string): TemplateSource;
+/** Restores the markup into rendered output and turns line breaks and tabs from data into elements. */
+export declare function fromTemplateOutput(output: string, template: TemplateSource, part?: string): FilledPart;
+/**
+ * Line breaks and tabs inside text elements become elements, and text elements with leading or
+ * trailing whitespace get `xml:space="preserve"`. Text of other elements (field codes, a table style
+ * id) is markup and stays as it is.
+ */
+export declare function layoutText(xml: string, flavour: TextFlavour, part?: string): string;

package/types/lib/office/template-text.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How an office part becomes template source and back (spec 22 §4.3 steps 5–7).
+ *
+ * Only the characters of text elements (`w:t`, `a:t`) are template text, decoded. Every run of markup
+ * between them becomes one placeholder, `U+E000 <nonce> <index> U+E001`, so the engine sees plain text
+ * with opaque markers and renders with its escaping switched off. On the way back every text segment is
+ * escaped and every placeholder restored. Whatever an expression prints therefore lands as text: `safe`,
+ * `{{{ }}}`, `raw`, `{% echo %}` and `capture` cannot put markup into the document, and nothing is
+ * escaped twice. The nonce is random per render, so data cannot forge a placeholder.
+ */
+export type TextFlavour = 'wordprocessing' | 'drawing';
+/**
+ * One run of markup between two pieces of text. What it contains decides whether a tag may span it:
+ * run boundaries inside a paragraph may be merged away, a paragraph or hyperlink boundary may not
+ * (`office/tags.ts`).
+ */
+export interface MarkupPiece {
+    raw: string;
+    /** Paragraphs (`w:p`, `a:p`) that open in this piece; the index of the paragraph a tag sits in. */
+    paragraphOpens: number;
+    /** A paragraph starts or ends here, so text on both sides is not in the same paragraph. */
+    paragraphBoundary: boolean;
+    /**
+     * Something other than a plain run boundary: a hyperlink, a content control, a tracked change, a
+     * field, an alternate-content branch. Merging across it would move text out of its element.
+     */
+    containerBoundary: boolean;
+    /**
+     * The piece ends inside a text element, so text the template prints after it is document text.
+     * Only the last piece of a part ends outside one.
+     */
+    endsInText?: boolean;
+}
+export interface TemplateSource {
+    /** The part as template text: decoded text of the text elements, placeholders for the markup. */
+    source: string;
+    markup: MarkupPiece[];
+    nonce: string;
+    flavour: TextFlavour;
+}
+export interface FilledPart {
+    xml: string;
+    /** Characters XML does not allow that values contained and that were removed. */
+    removedCharacters: number;
+}
+/** The placeholder of markup piece `index`, as it appears in the template source. */
+export declare function placeholderFor(nonce: string, index: number): string;
+/** Matches any placeholder of this template, with the piece index in group 1. */
+export declare function placeholderPattern(nonce: string): RegExp;
+export declare function createNonce(random?: () => number): string;
+export declare function toTemplateSource(xml: string, flavour: TextFlavour, nonce: string, part?: string): TemplateSource;
+/** Restores the markup into rendered output and turns line breaks and tabs from data into elements. */
+export declare function fromTemplateOutput(output: string, template: TemplateSource, part?: string): FilledPart;
+/**
+ * Line breaks and tabs inside text elements become elements, and text elements with leading or
+ * trailing whitespace get `xml:space="preserve"`. Text of other elements (field codes, a table style
+ * id) is markup and stays as it is.
+ */
+export declare function layoutText(xml: string, flavour: TextFlavour, part?: string): string;

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

@@ -0,0 +1,44 @@
+/**
+ * A small XML tokenizer for office parts (spec 22 §4.3). Not a DOM: the rewrite has to keep every byte
+ * it does not change (a DOM round trip reorders namespace declarations and quoting), and the engine runs
+ * in browsers and Node without `DOMParser`. OOXML parts are machine-written XML without DTDs, which
+ * keeps this small; anything outside that shape is refused rather than guessed at.
+ */
+export type XmlToken = {
+    kind: 'open';
+    raw: string;
+    name: string;
+    selfClosing: boolean;
+} | {
+    kind: 'close';
+    raw: string;
+    name: string;
+} | {
+    kind: 'text';
+    raw: string;
+} | {
+    kind: 'cdata';
+    raw: string;
+} | {
+    kind: 'comment';
+    raw: string;
+} | {
+    kind: 'pi';
+    raw: string;
+};
+/** Splits XML into tokens whose `raw` strings concatenate back to the input exactly. */
+export declare function tokenize(xml: string, part?: string): XmlToken[];
+/**
+ * Throws unless the tokens form one well-formed element: balanced tags, one root, valid entity
+ * references in text and attributes, no characters XML 1.0 forbids.
+ */
+export declare function assertWellFormed(tokens: readonly XmlToken[], part?: string): void;
+/** Text content as characters: entity references resolved. */
+export declare function decodeText(raw: string): string;
+/** Characters as text content. `>` is escaped too, so `]]>` can never appear. */
+export declare function escapeText(text: string): string;
+/** Removes the characters XML 1.0 forbids; `removed` counts them for the render's warnings. */
+export declare function stripForbidden(text: string): {
+    text: string;
+    removed: number;
+};

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

@@ -0,0 +1,44 @@
+/**
+ * A small XML tokenizer for office parts (spec 22 §4.3). Not a DOM: the rewrite has to keep every byte
+ * it does not change (a DOM round trip reorders namespace declarations and quoting), and the engine runs
+ * in browsers and Node without `DOMParser`. OOXML parts are machine-written XML without DTDs, which
+ * keeps this small; anything outside that shape is refused rather than guessed at.
+ */
+export type XmlToken = {
+    kind: 'open';
+    raw: string;
+    name: string;
+    selfClosing: boolean;
+} | {
+    kind: 'close';
+    raw: string;
+    name: string;
+} | {
+    kind: 'text';
+    raw: string;
+} | {
+    kind: 'cdata';
+    raw: string;
+} | {
+    kind: 'comment';
+    raw: string;
+} | {
+    kind: 'pi';
+    raw: string;
+};
+/** Splits XML into tokens whose `raw` strings concatenate back to the input exactly. */
+export declare function tokenize(xml: string, part?: string): XmlToken[];
+/**
+ * Throws unless the tokens form one well-formed element: balanced tags, one root, valid entity
+ * references in text and attributes, no characters XML 1.0 forbids.
+ */
+export declare function assertWellFormed(tokens: readonly XmlToken[], part?: string): void;
+/** Text content as characters: entity references resolved. */
+export declare function decodeText(raw: string): string;
+/** Characters as text content. `>` is escaped too, so `]]>` can never appear. */
+export declare function escapeText(text: string): string;
+/** Removes the characters XML 1.0 forbids; `removed` counts them for the render's warnings. */
+export declare function stripForbidden(text: string): {
+    text: string;
+    removed: number;
+};

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

@@ -0,0 +1,49 @@
+/**
+ * A ZIP reader and writer for office containers (spec 22 §4.3 step 1). fflate's `unzipSync` inflates
+ * every entry, media included, and its `zipSync` compresses them all again; this reader parses the
+ * central directory itself, inflates only the parts a caller asks for (capped while inflating), and
+ * the writer copies every other entry as its original compressed bytes. Written for untrusted input:
+ * every offset is bounds-checked and every rule of §2.1 that concerns the container is applied here.
+ */
+export interface ZipEntry {
+    readonly name: string;
+    /** 0 stored, 8 deflate. */
+    readonly method: number;
+    readonly crc32: number;
+    readonly compressedSize: number;
+    /** As declared; `read()` verifies it. */
+    readonly size: number;
+    readonly dosTime: number;
+    readonly dosDate: number;
+    /** The compressed bytes, a view into the archive. */
+    readonly raw: Uint8Array;
+}
+export interface ZipArchive {
+    readonly entries: readonly ZipEntry[];
+    get(name: string): ZipEntry | undefined;
+}
+export interface ZipLimits {
+    maxEntries: number;
+    maxDeclaredBytes: number;
+}
+export declare function isZip(bytes: Uint8Array): boolean;
+/** Name rules: no absolute paths, `..`, backslashes, drive letters or control characters. */
+export declare function isSafeEntryName(name: string): boolean;
+export declare function readZip(bytes: Uint8Array, limits?: ZipLimits): ZipArchive;
+/** The entry's bytes, inflated with a hard cap and checked against its CRC. */
+export declare function readEntry(entry: ZipEntry, maxBytes?: number): Uint8Array;
+export declare function readText(entry: ZipEntry, maxBytes?: number): string;
+/** XML parts may be UTF-8 or UTF-16 (OOXML allows both); a BOM decides. */
+export declare function decodeXml(bytes: Uint8Array): string;
+/** One entry of a new archive: an entry copied as it is, or new bytes to deflate. */
+export type ZipWriteEntry = ZipEntry | {
+    name: string;
+    data: Uint8Array;
+    store?: boolean;
+};
+/**
+ * Writes an archive in the given order. Copied entries keep their compressed bytes and timestamps;
+ * new entries get 1980-01-01 00:00, so equal inputs produce equal bytes (reproducible renders).
+ */
+export declare function writeZip(entries: readonly ZipWriteEntry[]): Uint8Array;
+export declare function crc32(data: Uint8Array): number;

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

@@ -0,0 +1,49 @@
+/**
+ * A ZIP reader and writer for office containers (spec 22 §4.3 step 1). fflate's `unzipSync` inflates
+ * every entry, media included, and its `zipSync` compresses them all again; this reader parses the
+ * central directory itself, inflates only the parts a caller asks for (capped while inflating), and
+ * the writer copies every other entry as its original compressed bytes. Written for untrusted input:
+ * every offset is bounds-checked and every rule of §2.1 that concerns the container is applied here.
+ */
+export interface ZipEntry {
+    readonly name: string;
+    /** 0 stored, 8 deflate. */
+    readonly method: number;
+    readonly crc32: number;
+    readonly compressedSize: number;
+    /** As declared; `read()` verifies it. */
+    readonly size: number;
+    readonly dosTime: number;
+    readonly dosDate: number;
+    /** The compressed bytes, a view into the archive. */
+    readonly raw: Uint8Array;
+}
+export interface ZipArchive {
+    readonly entries: readonly ZipEntry[];
+    get(name: string): ZipEntry | undefined;
+}
+export interface ZipLimits {
+    maxEntries: number;
+    maxDeclaredBytes: number;
+}
+export declare function isZip(bytes: Uint8Array): boolean;
+/** Name rules: no absolute paths, `..`, backslashes, drive letters or control characters. */
+export declare function isSafeEntryName(name: string): boolean;
+export declare function readZip(bytes: Uint8Array, limits?: ZipLimits): ZipArchive;
+/** The entry's bytes, inflated with a hard cap and checked against its CRC. */
+export declare function readEntry(entry: ZipEntry, maxBytes?: number): Uint8Array;
+export declare function readText(entry: ZipEntry, maxBytes?: number): string;
+/** XML parts may be UTF-8 or UTF-16 (OOXML allows both); a BOM decides. */
+export declare function decodeXml(bytes: Uint8Array): string;
+/** One entry of a new archive: an entry copied as it is, or new bytes to deflate. */
+export type ZipWriteEntry = ZipEntry | {
+    name: string;
+    data: Uint8Array;
+    store?: boolean;
+};
+/**
+ * Writes an archive in the given order. Copied entries keep their compressed bytes and timestamps;
+ * new entries get 1980-01-01 00:00, so equal inputs produce equal bytes (reproducible renders).
+ */
+export declare function writeZip(entries: readonly ZipWriteEntry[]): Uint8Array;
+export declare function crc32(data: Uint8Array): number;

package/types/lib/output.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Output formats of a render and the one rule for the format a request gets when it names none.
+ * Imported without the renderers as `@formfeed/engine/output` (the gateway), so it depends on
+ * nothing.
+ */
+/** The API's `output` values. JPEG is `jpg` here; settings spell it `jpeg`. */
+export declare const outputFormats: readonly ["pdf", "png", "jpg", "webp", "docx", "pptx"];
+export type OutputFormat = (typeof outputFormats)[number];
+export type ImageOutput = 'png' | 'jpg' | 'webp';
+/** Template kinds whose template is a Word or PowerPoint file (spec 22 §4.1). */
+export declare const officeKinds: readonly ["docx", "pptx"];
+export type OfficeKind = (typeof officeKinds)[number];
+export declare function isOutputFormat(value: unknown): value is OutputFormat;
+export declare function isOfficeKind(value: unknown): value is OfficeKind;
+/**
+ * The outputs a source may request (spec 22 §4.1): an office template its own format or a PDF;
+ * everything else (PDF and image templates, ad-hoc HTML, URLs) PDF or an image.
+ */
+export declare function outputsForKind(kind: string | null | undefined): readonly OutputFormat[];
+/** `settings.image.format` as an output; `jpg` is accepted too, anything else is PNG. */
+export declare function imageOutput(settings: unknown): ImageOutput;
+/**
+ * The output of a render that names none: a PDF template renders a PDF, an image template the format
+ * of its `settings.image.format` (PNG without one), an office template `settings.office.output` (its
+ * own format without one). Settings are the template's with the request's merged over them, so a
+ * request can pick the format without naming `output`. Sources without a kind (ad-hoc HTML, URLs)
+ * render PDFs.
+ */
+export declare function defaultOutput(kind: string | null | undefined, ...settings: unknown[]): OutputFormat;