@formfeed/engine 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
   "license": "MIT",
   "type": "module",

package/types/index.d.cts

@@ -3,21 +3,31 @@ export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.c
 export { defaultLimits, depthGuard, enforceLimits } from './lib/limits.cjs';
 export { DefaultHelperRegistry, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, imageMarkup, qrSvg, toDate, toNumber, } from './lib/helpers/index.cjs';
 export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, getEngine, handlebarsEngine, jinja2Engine, liquidEngine, liquidBuiltinFilters, nunjucksBuiltinFilters, } from './lib/engines/index.cjs';
-export { inferSchema, schemaPaths } from './lib/schema.cjs';
-export { mergeSampleData, snippets, snippetsFor } from './lib/snippets.cjs';
-export { importApitemplate, slugFromName } from './lib/import/apitemplate.cjs';
-export type { ApitemplateExport } from './lib/import/apitemplate.cjs';
+export { diffSchemas, inferSchema, inferSchemaFromDataSets, schemaPaths } from './lib/schema.cjs';
+export { defaultOutput, imageOutput, isOfficeKind, isOutputFormat, officeKinds, outputFormats, outputsForKind, type OfficeKind, type OutputFormat, } from './lib/output.cjs';
+export { brandCss, emptyBrand, layeredPartials, normalisePartialName } from './lib/brand.cjs';
+export type { BrandContext, SharedPartial } from './lib/brand.cjs';
+export { mergeSampleData, mergeSnippetCss, mergeSnippetI18n, partialInclude, snippets, snippetsFor, snippetText, } from './lib/snippets.cjs';
+export { apitemplateRegions, importApitemplate, importApitemplateFromApi, isApitemplateHtmlTemplate, isApitemplateRegion, slugFromName, splitApitemplateCss, } from './lib/import/apitemplate.cjs';
+export type { ApitemplateApiTemplate, ApitemplateExport, ApitemplateListItem, ApitemplateRegion } from './lib/import/apitemplate.cjs';
 export type { ImportNote, ImportResult, ImportSource } from './lib/import/common.cjs';
 export { importPdfmonkey, strftimeToDateFns } from './lib/import/pdfmonkey.cjs';
 export type { PdfmonkeyImportOptions, PdfmonkeySettings, PdfmonkeyTemplate } from './lib/import/pdfmonkey.cjs';
 export { importJsreport, jsreportTemplates, readJsreportExport } from './lib/import/jsreport.cjs';
 export type { JsreportBundle, JsreportImportOptions, JsreportTemplate } from './lib/import/jsreport.cjs';
 export { convertScss, isScss } from './lib/import/scss.cjs';
-export type { Snippet } from './lib/snippets.cjs';
-export type { JsonSchema } from './lib/schema.cjs';
-export { assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.cjs';
+export type { Snippet, SnippetGroup } from './lib/snippets.cjs';
+export type { JsonSchema, SchemaChange, SchemaChangeKind, SchemaDiff } from './lib/schema.cjs';
+export { DEFAULT_CHROME_PADDING, assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.cjs';
 export type { ChartSpec, ImageOptions } from './lib/helpers/index.cjs';
-export { flowDocument, pagedDocument, pageNumberSpans, paperOf } from './lib/preview.cjs';
+export { flowDocument, pagedDocument, pageNumberSpans, paperOf, zoomGestureScript } from './lib/preview.cjs';
 export type { PagedOptions, RenderedDraft } from './lib/preview.cjs';
-export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.cjs';
+export { annotateSourcePositions, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.cjs';
+export type { SourceFile, SourceLocation } from './lib/source-positions.cjs';
+export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.cjs';
 export { resolvePath, scanBlocks, jinjaTags, liquidTags, } from './lib/analysis/tags.cjs';
+export { OFFICE_FILLED_MAX_BYTES, OfficeTemplateError, analyzeOffice, officeTextParts, renderOffice, type OfficeAnalysis, type OfficeAnalysisDiagnostic, type OfficeRenderOptions, type OfficeRenderResult, } from './lib/office/render.cjs';
+export type { OfficeTag } from './lib/office/tags.cjs';
+export { starterDocument } from './lib/office/starter.cjs';
+export { starterPresentation } from './lib/office/starter-pptx.cjs';
+export { officeDrawingLimits, type OfficeImageHost } from './lib/office/drawings.cjs';

package/types/index.d.ts

@@ -3,21 +3,31 @@ export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.j
 export { defaultLimits, depthGuard, enforceLimits } from './lib/limits.js';
 export { DefaultHelperRegistry, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, imageMarkup, qrSvg, toDate, toNumber, } from './lib/helpers/index.js';
 export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, getEngine, handlebarsEngine, jinja2Engine, liquidEngine, liquidBuiltinFilters, nunjucksBuiltinFilters, } from './lib/engines/index.js';
-export { inferSchema, schemaPaths } from './lib/schema.js';
-export { mergeSampleData, snippets, snippetsFor } from './lib/snippets.js';
-export { importApitemplate, slugFromName } from './lib/import/apitemplate.js';
-export type { ApitemplateExport } from './lib/import/apitemplate.js';
+export { diffSchemas, inferSchema, inferSchemaFromDataSets, schemaPaths } from './lib/schema.js';
+export { defaultOutput, imageOutput, isOfficeKind, isOutputFormat, officeKinds, outputFormats, outputsForKind, type OfficeKind, type OutputFormat, } from './lib/output.js';
+export { brandCss, emptyBrand, layeredPartials, normalisePartialName } from './lib/brand.js';
+export type { BrandContext, SharedPartial } from './lib/brand.js';
+export { mergeSampleData, mergeSnippetCss, mergeSnippetI18n, partialInclude, snippets, snippetsFor, snippetText, } from './lib/snippets.js';
+export { apitemplateRegions, importApitemplate, importApitemplateFromApi, isApitemplateHtmlTemplate, isApitemplateRegion, slugFromName, splitApitemplateCss, } from './lib/import/apitemplate.js';
+export type { ApitemplateApiTemplate, ApitemplateExport, ApitemplateListItem, ApitemplateRegion } from './lib/import/apitemplate.js';
 export type { ImportNote, ImportResult, ImportSource } from './lib/import/common.js';
 export { importPdfmonkey, strftimeToDateFns } from './lib/import/pdfmonkey.js';
 export type { PdfmonkeyImportOptions, PdfmonkeySettings, PdfmonkeyTemplate } from './lib/import/pdfmonkey.js';
 export { importJsreport, jsreportTemplates, readJsreportExport } from './lib/import/jsreport.js';
 export type { JsreportBundle, JsreportImportOptions, JsreportTemplate } from './lib/import/jsreport.js';
 export { convertScss, isScss } from './lib/import/scss.js';
-export type { Snippet } from './lib/snippets.js';
-export type { JsonSchema } from './lib/schema.js';
-export { assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.js';
+export type { Snippet, SnippetGroup } from './lib/snippets.js';
+export type { JsonSchema, SchemaChange, SchemaChangeKind, SchemaDiff } from './lib/schema.js';
+export { DEFAULT_CHROME_PADDING, assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.js';
 export type { ChartSpec, ImageOptions } from './lib/helpers/index.js';
-export { flowDocument, pagedDocument, pageNumberSpans, paperOf } from './lib/preview.js';
+export { flowDocument, pagedDocument, pageNumberSpans, paperOf, zoomGestureScript } from './lib/preview.js';
 export type { PagedOptions, RenderedDraft } from './lib/preview.js';
-export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.js';
+export { annotateSourcePositions, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.js';
+export type { SourceFile, SourceLocation } from './lib/source-positions.js';
+export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.js';
 export { resolvePath, scanBlocks, jinjaTags, liquidTags, } from './lib/analysis/tags.js';
+export { OFFICE_FILLED_MAX_BYTES, OfficeTemplateError, analyzeOffice, officeTextParts, renderOffice, type OfficeAnalysis, type OfficeAnalysisDiagnostic, type OfficeRenderOptions, type OfficeRenderResult, } from './lib/office/render.js';
+export type { OfficeTag } from './lib/office/tags.js';
+export { starterDocument } from './lib/office/starter.js';
+export { starterPresentation } from './lib/office/starter-pptx.js';
+export { officeDrawingLimits, type OfficeImageHost } from './lib/office/drawings.js';

package/types/lib/assemble.d.cts

@@ -1,5 +1,13 @@
+import type { BrandContext } from './brand.cjs';
 import type { EngineId, RenderContext } from './types.cjs';
 /** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
+export interface HeaderFooterSettings {
+    html?: string;
+    height?: string;
+    padding?: string;
+}
+/** The side padding Formfeed gives header and footer unless the template sets its own. */
+export declare const DEFAULT_CHROME_PADDING = "0 10mm";
 export interface TemplateSettings {
     paper?: {
         format?: string;
@@ -14,14 +22,12 @@ export interface TemplateSettings {
         bottom?: string;
         left?: string;
     };
-    header?: {
-        html?: string;
-        height?: string;
-    } | null;
-    footer?: {
-        html?: string;
-        height?: string;
-    } | null;
+    /**
+     * Header and footer span the full page width, as Chromium prints them; `padding` is the space
+     * inside that box (CSS shorthand, default `0 10mm`, `0` for designs that run edge to edge).
+     */
+    header?: HeaderFooterSettings | null;
+    footer?: HeaderFooterSettings | null;
     printBackground?: boolean;
     scale?: number;
     preferCssPageSize?: boolean;
@@ -52,6 +58,10 @@ export interface TemplateSettings {
         transparent?: boolean;
         clipSelector?: string | null;
     };
+    /** Office templates (spec 22 §4.1): the output when a request names none. */
+    office?: {
+        output?: 'docx' | 'pptx' | 'pdf';
+    };
     locale?: string;
     timezone?: string;
     currency?: string;
@@ -67,7 +77,10 @@ export declare function defaultSettings(): Required<Pick<TemplateSettings, 'pape
 export declare function mergeSettings(...layers: Array<TemplateSettings | null | undefined>): TemplateSettings;
 /** `@page` size expression from the paper settings. */
 export declare function pageSize(settings: TemplateSettings): string;
-/** Default print reset of spec 05 §5. */
+/**
+ * Default print reset of spec 05 §5. Its element rules sit in `:where()`, so any rule of the template
+ * wins over them, as it did when the template's styles simply came later.
+ */
 export declare function printReset(settings: TemplateSettings, kind?: TemplateKind): string;
 /** An organisation font (spec 05 §6) reachable by URL from the preview frame or the worker. */
 export interface FontFace {
@@ -113,6 +126,8 @@ export interface AssembleInput extends AssembleExtras {
     kind?: TemplateKind;
     /** Base URL for relative asset references (`<base href>`); omitted when undefined. */
     assetBaseUrl?: string;
+    /** Brand kit whose `--brand-*` variables go before the reset and the template CSS (spec 18 §2.2). */
+    brand?: BrandContext;
     /** Preview marks the document so the preview frame can style it; print is what Chromium gets. */
     mode?: 'preview' | 'print';
     title?: string;

package/types/lib/assemble.d.ts

@@ -1,5 +1,13 @@
+import type { BrandContext } from './brand.js';
 import type { EngineId, RenderContext } from './types.js';
 /** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
+export interface HeaderFooterSettings {
+    html?: string;
+    height?: string;
+    padding?: string;
+}
+/** The side padding Formfeed gives header and footer unless the template sets its own. */
+export declare const DEFAULT_CHROME_PADDING = "0 10mm";
 export interface TemplateSettings {
     paper?: {
         format?: string;
@@ -14,14 +22,12 @@ export interface TemplateSettings {
         bottom?: string;
         left?: string;
     };
-    header?: {
-        html?: string;
-        height?: string;
-    } | null;
-    footer?: {
-        html?: string;
-        height?: string;
-    } | null;
+    /**
+     * Header and footer span the full page width, as Chromium prints them; `padding` is the space
+     * inside that box (CSS shorthand, default `0 10mm`, `0` for designs that run edge to edge).
+     */
+    header?: HeaderFooterSettings | null;
+    footer?: HeaderFooterSettings | null;
     printBackground?: boolean;
     scale?: number;
     preferCssPageSize?: boolean;
@@ -52,6 +58,10 @@ export interface TemplateSettings {
         transparent?: boolean;
         clipSelector?: string | null;
     };
+    /** Office templates (spec 22 §4.1): the output when a request names none. */
+    office?: {
+        output?: 'docx' | 'pptx' | 'pdf';
+    };
     locale?: string;
     timezone?: string;
     currency?: string;
@@ -67,7 +77,10 @@ export declare function defaultSettings(): Required<Pick<TemplateSettings, 'pape
 export declare function mergeSettings(...layers: Array<TemplateSettings | null | undefined>): TemplateSettings;
 /** `@page` size expression from the paper settings. */
 export declare function pageSize(settings: TemplateSettings): string;
-/** Default print reset of spec 05 §5. */
+/**
+ * Default print reset of spec 05 §5. Its element rules sit in `:where()`, so any rule of the template
+ * wins over them, as it did when the template's styles simply came later.
+ */
 export declare function printReset(settings: TemplateSettings, kind?: TemplateKind): string;
 /** An organisation font (spec 05 §6) reachable by URL from the preview frame or the worker. */
 export interface FontFace {
@@ -113,6 +126,8 @@ export interface AssembleInput extends AssembleExtras {
     kind?: TemplateKind;
     /** Base URL for relative asset references (`<base href>`); omitted when undefined. */
     assetBaseUrl?: string;
+    /** Brand kit whose `--brand-*` variables go before the reset and the template CSS (spec 18 §2.2). */
+    brand?: BrandContext;
     /** Preview marks the document so the preview frame can style it; print is what Chromium gets. */
     mode?: 'preview' | 'print';
     title?: string;

package/types/lib/brand.d.cts

@@ -0,0 +1,46 @@
+import type { PartialResolver } from './types.cjs';
+/**
+ * The organisation's brand kit as a template sees it (spec 18 §2.1): `brand.colors.primary`,
+ * `brand.logo.mark`, `brand.legal_footer`. Unset values are `null`; `colors` is always an object.
+ */
+export interface BrandContext {
+    version: number;
+    name: string | null;
+    colors: Record<string, string>;
+    fonts: {
+        heading: string | null;
+        body: string | null;
+    };
+    font_size: string | null;
+    logo: {
+        primary: string | null;
+        inverse: string | null;
+        mark: string | null;
+    };
+    legal_footer: string | null;
+}
+/** The `brand` of an organisation that has set nothing, and of local renders without a pulled kit. */
+export declare function emptyBrand(): BrandContext;
+/**
+ * The `--brand-*` custom properties of spec 18 §2.2. Values are validated again here, because the
+ * stylesheet sits in a `<style>` element and a kit from a pulled file or an old cache is still input.
+ */
+export declare function brandCss(brand: BrandContext | undefined): string;
+/** The family names a kit names, so `fontFaceCss` injects their faces even behind `var(--brand-font-*)`. */
+export declare function brandFontFamilies(brand: BrandContext | undefined): string;
+/**
+ * The name a shared partial is matched by (spec 18 §2.3): lowercase, one template file extension
+ * removed. `@formfeed/api-types` and the database (`private.normalise_partial_name`) keep copies.
+ */
+export declare function normalisePartialName(name: string): string;
+/** A shared partial as hosts pass it: its source and the version a render records. */
+export interface SharedPartial {
+    source: string;
+    version: number;
+}
+/**
+ * One resolver over both kinds of partial: the version's own by exact name first, then the
+ * organisation's shared ones by normalised name. `onShared` hears every shared partial that was
+ * actually read, which is what the render-worker records for reproducibility.
+ */
+export declare function layeredPartials(own: Record<string, string> | undefined, shared: Record<string, SharedPartial> | undefined, onShared?: (name: string, partial: SharedPartial) => void): PartialResolver;

package/types/lib/brand.d.ts

@@ -0,0 +1,46 @@
+import type { PartialResolver } from './types.js';
+/**
+ * The organisation's brand kit as a template sees it (spec 18 §2.1): `brand.colors.primary`,
+ * `brand.logo.mark`, `brand.legal_footer`. Unset values are `null`; `colors` is always an object.
+ */
+export interface BrandContext {
+    version: number;
+    name: string | null;
+    colors: Record<string, string>;
+    fonts: {
+        heading: string | null;
+        body: string | null;
+    };
+    font_size: string | null;
+    logo: {
+        primary: string | null;
+        inverse: string | null;
+        mark: string | null;
+    };
+    legal_footer: string | null;
+}
+/** The `brand` of an organisation that has set nothing, and of local renders without a pulled kit. */
+export declare function emptyBrand(): BrandContext;
+/**
+ * The `--brand-*` custom properties of spec 18 §2.2. Values are validated again here, because the
+ * stylesheet sits in a `<style>` element and a kit from a pulled file or an old cache is still input.
+ */
+export declare function brandCss(brand: BrandContext | undefined): string;
+/** The family names a kit names, so `fontFaceCss` injects their faces even behind `var(--brand-font-*)`. */
+export declare function brandFontFamilies(brand: BrandContext | undefined): string;
+/**
+ * The name a shared partial is matched by (spec 18 §2.3): lowercase, one template file extension
+ * removed. `@formfeed/api-types` and the database (`private.normalise_partial_name`) keep copies.
+ */
+export declare function normalisePartialName(name: string): string;
+/** A shared partial as hosts pass it: its source and the version a render records. */
+export interface SharedPartial {
+    source: string;
+    version: number;
+}
+/**
+ * One resolver over both kinds of partial: the version's own by exact name first, then the
+ * organisation's shared ones by normalised name. `onShared` hears every shared partial that was
+ * actually read, which is what the render-worker records for reproducibility.
+ */
+export declare function layeredPartials(own: Record<string, string> | undefined, shared: Record<string, SharedPartial> | undefined, onShared?: (name: string, partial: SharedPartial) => void): PartialResolver;

package/types/lib/helpers/document.d.cts

@@ -10,7 +10,31 @@ export interface ChartSpec {
     options?: Record<string, unknown>;
     width?: number | string;
     height?: number | string;
+    /** Plain data instead of `data`: one label per point, with `values` or several `series`. */
+    labels?: unknown[];
+    values?: unknown[];
+    /** Name of the single `values` series; without one the legend is hidden. */
+    label?: string;
+    /** Colour of the single series; a list colours pie and doughnut slices one by one. */
+    color?: string | string[];
+    series?: ChartSeries[];
 }
+export interface ChartSeries {
+    label?: string;
+    values?: unknown[];
+    color?: string | string[];
+}
+/** Colours for series and slices that name none. */
+export declare const CHART_PALETTE: string[];
+/**
+ * Chart.js `data` from plain data, so a template can chart `{ labels, values }` from a request
+ * without the caller knowing Chart.js. Values become numbers (anything else a gap); a series
+ * without a colour takes the next palette colour, and each slice of a pie or doughnut its own.
+ */
+export declare function chartDataFromPlain(spec: ChartSpec): {
+    datasets: Record<string, unknown>[];
+    labels: unknown[];
+};
 export interface ImageOptions {
     width?: number | string;
     height?: number | string;

package/types/lib/helpers/document.d.ts

@@ -10,7 +10,31 @@ export interface ChartSpec {
     options?: Record<string, unknown>;
     width?: number | string;
     height?: number | string;
+    /** Plain data instead of `data`: one label per point, with `values` or several `series`. */
+    labels?: unknown[];
+    values?: unknown[];
+    /** Name of the single `values` series; without one the legend is hidden. */
+    label?: string;
+    /** Colour of the single series; a list colours pie and doughnut slices one by one. */
+    color?: string | string[];
+    series?: ChartSeries[];
 }
+export interface ChartSeries {
+    label?: string;
+    values?: unknown[];
+    color?: string | string[];
+}
+/** Colours for series and slices that name none. */
+export declare const CHART_PALETTE: string[];
+/**
+ * Chart.js `data` from plain data, so a template can chart `{ labels, values }` from a request
+ * without the caller knowing Chart.js. Values become numbers (anything else a gap); a series
+ * without a colour takes the next palette colour, and each slice of a pie or doughnut its own.
+ */
+export declare function chartDataFromPlain(spec: ChartSpec): {
+    datasets: Record<string, unknown>[];
+    labels: unknown[];
+};
 export interface ImageOptions {
     width?: number | string;
     height?: number | string;

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

@@ -4,6 +4,7 @@ export { DefaultHelperRegistry } from './registry.cjs';
 export { escapeHtml, toDate, toNumber } from './format.cjs';
 export { epcPayload, qrSvg } from './codes.cjs';
 export { chartMarkup, chartPayload, imageMarkup } from './document.cjs';
+export { officeUnsupported, officeUnsupportedHelpers } from './office.cjs';
 export type { ChartSpec, ImageOptions } from './document.cjs';
 /** Helpers shipped with the product (spec 05 §2), identical in all three engines. */
 export declare const builtinHelpers: HelperDefinition[];

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

@@ -4,6 +4,7 @@ export { DefaultHelperRegistry } from './registry.js';
 export { escapeHtml, toDate, toNumber } from './format.js';
 export { epcPayload, qrSvg } from './codes.js';
 export { chartMarkup, chartPayload, imageMarkup } from './document.js';
+export { officeUnsupported, officeUnsupportedHelpers } from './office.js';
 export type { ChartSpec, ImageOptions } from './document.js';
 /** Helpers shipped with the product (spec 05 §2), identical in all three engines. */
 export declare const builtinHelpers: HelperDefinition[];

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

@@ -0,0 +1,4 @@
+/** Helpers that return HTML and have no office form yet (spec 22 §4.4). */
+export declare const officeUnsupportedHelpers: ReadonlySet<string>;
+/** The message those helpers fail with in office mode. */
+export declare function officeUnsupported(name: string): string;

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

@@ -0,0 +1,4 @@
+/** Helpers that return HTML and have no office form yet (spec 22 §4.4). */
+export declare const officeUnsupportedHelpers: ReadonlySet<string>;
+/** The message those helpers fail with in office mode. */
+export declare function officeUnsupported(name: string): string;

package/types/lib/import/apitemplate.d.cts

@@ -18,4 +18,64 @@ export interface ApitemplateExport {
     /** Their template format; JPEG and PNG become image templates. */
     format?: string | null;
 }
+/**
+ * apitemplate.io puts its CSS field into the document head as is, so it often carries `<link>`,
+ * `<script>` and `<style>` tags. Formfeed wraps CSS in a `<style>` element, where such tags break
+ * the stylesheet and never load: style blocks become CSS, the rest of the markup goes to the head.
+ */
+export declare function splitApitemplateCss(source: string): {
+    css: string;
+    head: string;
+};
 export declare function importApitemplate(input: ApitemplateExport): ImportResult;
+/**
+ * apitemplate.io's regional API hosts (their "Regional API endpoints"). The key works in the
+ * region its account lives in; the importer only ever contacts these hosts.
+ */
+export declare const apitemplateRegions: {
+    readonly default: "https://rest.apitemplate.io";
+    readonly de: "https://rest-de.apitemplate.io";
+    readonly us: "https://rest-us.apitemplate.io";
+    readonly au: "https://rest-au.apitemplate.io";
+    readonly alt: "https://rest-alt.apitemplate.io";
+    readonly 'alt-de': "https://rest-alt-de.apitemplate.io";
+    readonly 'alt-us': "https://rest-alt-us.apitemplate.io";
+};
+export type ApitemplateRegion = keyof typeof apitemplateRegions;
+export declare function isApitemplateRegion(value: unknown): value is ApitemplateRegion;
+/** One entry of `GET /v2/list-templates`. */
+export interface ApitemplateListItem {
+    template_id: string;
+    name?: string | null;
+    status?: string | null;
+    /** `PDF` or `JPEG`. */
+    format?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    group_name?: string | null;
+}
+/**
+ * `GET /v2/get-template` (experimental on their side): the HTML body, CSS, print settings and the
+ * editor's sample JSON (`sample_json`, not in their API reference but in the answer).
+ */
+export interface ApitemplateApiTemplate {
+    status?: string | null;
+    template_id?: string | null;
+    body?: string | null;
+    css?: string | null;
+    /** A JSON string in their API; an object is accepted too. */
+    settings?: string | Record<string, unknown> | null;
+    /** The JSON of their editor's JSON tab, as a string; an object is accepted too. */
+    sample_json?: string | Record<string, unknown> | null;
+}
+/**
+ * Only PDF templates carry HTML; apitemplate.io's image templates are layer designs that
+ * `get-template` does not return.
+ */
+export declare function isApitemplateHtmlTemplate(item: Pick<ApitemplateListItem, 'format'>): boolean;
+/**
+ * Converts a template read through apitemplate.io's API, sample JSON included. A template without
+ * a body (an image template, or an editor the API does not serve) becomes a result with an error
+ * and no HTML, which callers skip.
+ */
+export declare function importApitemplateFromApi(item: ApitemplateListItem, template: ApitemplateApiTemplate): ImportResult;

package/types/lib/import/apitemplate.d.ts

@@ -18,4 +18,64 @@ export interface ApitemplateExport {
     /** Their template format; JPEG and PNG become image templates. */
     format?: string | null;
 }
+/**
+ * apitemplate.io puts its CSS field into the document head as is, so it often carries `<link>`,
+ * `<script>` and `<style>` tags. Formfeed wraps CSS in a `<style>` element, where such tags break
+ * the stylesheet and never load: style blocks become CSS, the rest of the markup goes to the head.
+ */
+export declare function splitApitemplateCss(source: string): {
+    css: string;
+    head: string;
+};
 export declare function importApitemplate(input: ApitemplateExport): ImportResult;
+/**
+ * apitemplate.io's regional API hosts (their "Regional API endpoints"). The key works in the
+ * region its account lives in; the importer only ever contacts these hosts.
+ */
+export declare const apitemplateRegions: {
+    readonly default: "https://rest.apitemplate.io";
+    readonly de: "https://rest-de.apitemplate.io";
+    readonly us: "https://rest-us.apitemplate.io";
+    readonly au: "https://rest-au.apitemplate.io";
+    readonly alt: "https://rest-alt.apitemplate.io";
+    readonly 'alt-de': "https://rest-alt-de.apitemplate.io";
+    readonly 'alt-us': "https://rest-alt-us.apitemplate.io";
+};
+export type ApitemplateRegion = keyof typeof apitemplateRegions;
+export declare function isApitemplateRegion(value: unknown): value is ApitemplateRegion;
+/** One entry of `GET /v2/list-templates`. */
+export interface ApitemplateListItem {
+    template_id: string;
+    name?: string | null;
+    status?: string | null;
+    /** `PDF` or `JPEG`. */
+    format?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    group_name?: string | null;
+}
+/**
+ * `GET /v2/get-template` (experimental on their side): the HTML body, CSS, print settings and the
+ * editor's sample JSON (`sample_json`, not in their API reference but in the answer).
+ */
+export interface ApitemplateApiTemplate {
+    status?: string | null;
+    template_id?: string | null;
+    body?: string | null;
+    css?: string | null;
+    /** A JSON string in their API; an object is accepted too. */
+    settings?: string | Record<string, unknown> | null;
+    /** The JSON of their editor's JSON tab, as a string; an object is accepted too. */
+    sample_json?: string | Record<string, unknown> | null;
+}
+/**
+ * Only PDF templates carry HTML; apitemplate.io's image templates are layer designs that
+ * `get-template` does not return.
+ */
+export declare function isApitemplateHtmlTemplate(item: Pick<ApitemplateListItem, 'format'>): boolean;
+/**
+ * Converts a template read through apitemplate.io's API, sample JSON included. A template without
+ * a body (an image template, or an editor the API does not serve) becomes a result with an error
+ * and no HTML, which callers skip.
+ */
+export declare function importApitemplateFromApi(item: ApitemplateListItem, template: ApitemplateApiTemplate): ImportResult;

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

@@ -0,0 +1,36 @@
+import { type ZipArchive } from './zip.cjs';
+/**
+ * What a customer file is, decided from its bytes (spec 22 §3.2). Gotenberg picks LibreOffice's
+ * import filter by extension, so the worker sends every file under the extension found here and the
+ * customer's own file name never reaches the sidecar.
+ */
+export declare const officeFormats: readonly ["docx", "xlsx", "pptx", "odt", "ods", "odp", "doc", "xls", "ppt", "rtf", "html"];
+export type OfficeFormat = (typeof officeFormats)[number];
+export type OoxmlFormat = 'docx' | 'xlsx' | 'pptx';
+export type OdfFormat = 'odt' | 'ods' | 'odp';
+export declare const officeContentTypes: Record<OfficeFormat, string>;
+export interface DetectedOffice {
+    format: OfficeFormat;
+    /** The parsed container for ZIP-based formats, so callers do not read it twice. */
+    archive: ZipArchive | null;
+}
+export declare function detectOfficeFormat(bytes: Uint8Array): DetectedOffice;
+/**
+ * VBA projects in OOXML; Basic modules and scripts in ODF. LibreOffice may write the library
+ * descriptors `Basic/script-lc.xml` and `script-lb.xml` into documents without any macro, so only a
+ * module beside them counts.
+ */
+export declare function isMacroPart(name: string): boolean;
+/** A DOCTYPE anywhere in the text (entity expansion); the text is already decoded, UTF-16 included. */
+export declare function hasDoctype(xml: string): boolean;
+/**
+ * HTML: a BOM, whitespace, comments and an XML declaration may come first, then `<!DOCTYPE html>` or
+ * `<html>`. Deliberately narrow, so an SVG, an XML file or a text file is still refused.
+ */
+export declare function isHtml(bytes: Uint8Array): boolean;
+/**
+ * Legacy binary formats and encrypted OOXML share the Compound File container. Its directory names
+ * the streams, and they tell the formats apart: `EncryptionInfo` is an encrypted OOXML package,
+ * `WordDocument` a Word 97–2003 file, `Workbook` or `Book` Excel, `PowerPoint Document` PowerPoint.
+ */
+export declare function cfbStreamNames(bytes: Uint8Array): string[];

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

@@ -0,0 +1,36 @@
+import { type ZipArchive } from './zip.js';
+/**
+ * What a customer file is, decided from its bytes (spec 22 §3.2). Gotenberg picks LibreOffice's
+ * import filter by extension, so the worker sends every file under the extension found here and the
+ * customer's own file name never reaches the sidecar.
+ */
+export declare const officeFormats: readonly ["docx", "xlsx", "pptx", "odt", "ods", "odp", "doc", "xls", "ppt", "rtf", "html"];
+export type OfficeFormat = (typeof officeFormats)[number];
+export type OoxmlFormat = 'docx' | 'xlsx' | 'pptx';
+export type OdfFormat = 'odt' | 'ods' | 'odp';
+export declare const officeContentTypes: Record<OfficeFormat, string>;
+export interface DetectedOffice {
+    format: OfficeFormat;
+    /** The parsed container for ZIP-based formats, so callers do not read it twice. */
+    archive: ZipArchive | null;
+}
+export declare function detectOfficeFormat(bytes: Uint8Array): DetectedOffice;
+/**
+ * VBA projects in OOXML; Basic modules and scripts in ODF. LibreOffice may write the library
+ * descriptors `Basic/script-lc.xml` and `script-lb.xml` into documents without any macro, so only a
+ * module beside them counts.
+ */
+export declare function isMacroPart(name: string): boolean;
+/** A DOCTYPE anywhere in the text (entity expansion); the text is already decoded, UTF-16 included. */
+export declare function hasDoctype(xml: string): boolean;
+/**
+ * HTML: a BOM, whitespace, comments and an XML declaration may come first, then `<!DOCTYPE html>` or
+ * `<html>`. Deliberately narrow, so an SVG, an XML file or a text file is still refused.
+ */
+export declare function isHtml(bytes: Uint8Array): boolean;
+/**
+ * Legacy binary formats and encrypted OOXML share the Compound File container. Its directory names
+ * the streams, and they tell the formats apart: `EncryptionInfo` is an encrypted OOXML package,
+ * `WordDocument` a Word 97–2003 file, `Workbook` or `Book` Excel, `PowerPoint Document` PowerPoint.
+ */
+export declare function cfbStreamNames(bytes: Uint8Array): string[];