@formfeed/engine 0.2.0 → 0.3.1

package/types/lib/output.d.ts

@@ -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;

package/types/lib/preview.d.cts

@@ -1,4 +1,4 @@
-import type { TemplateKind, TemplateSettings } from './assemble.cjs';
+import { type TemplateKind, type TemplateSettings } from './assemble.cjs';
 /**
  * Preview documents shared by the web editor and `formfeed dev` (spec 06 §3, spec 15 §4): the
  * assembled document of `renderVersion` wrapped for the screen. Flow mode shows one page-wide
@@ -16,8 +16,20 @@ export declare function paperOf(settings: TemplateSettings): {
     width: string;
     height: string;
 };
-/** Chromium's header/footer placeholders replaced for the screen. */
+/**
+ * Chromium's header/footer placeholders filled for the screen. Like Chromium, any element whose class
+ * list names the placeholder counts, whatever else it carries (the editor adds `data-ff-src`), and
+ * the element stays so its styling applies.
+ */
 export declare const pageNumberSpans: (html: string, page: string, total: string) => string;
+/**
+ * Zoom gestures inside a preview frame: Ctrl+wheel (a touchpad pinch arrives as one too) and
+ * Ctrl+plus/minus/0 would zoom the whole app, and the sandboxed frame's events never reach the app,
+ * so the frame cancels them and asks the parent by message:
+ * `{ type: 'formfeed:zoom', deltaY, deltaMode }` or `{ type: 'formfeed:zoom', step: 'in' | 'out' | 'reset' }`.
+ * The office quick preview's frame uses the same script.
+ */
+export declare const zoomGestureScript = "<script>\n(function () {\n  var say = function (message) { try { parent.postMessage(message, '*'); } catch (e) {} };\n  window.addEventListener('wheel', function (event) {\n    if (!event.ctrlKey && !event.metaKey) return;\n    event.preventDefault();\n    say({ type: 'formfeed:zoom', deltaY: event.deltaY, deltaMode: event.deltaMode });\n  }, { passive: false });\n  window.addEventListener('keydown', function (event) {\n    if (!(event.ctrlKey || event.metaKey) || event.altKey) return;\n    var step = event.key === '+' || event.key === '=' ? 'in' : event.key === '-' ? 'out' : event.key === '0' ? 'reset' : null;\n    if (!step) return;\n    event.preventDefault();\n    say({ type: 'formfeed:zoom', step: step });\n  });\n})();\n</script>";
 export declare function flowDocument(draft: RenderedDraft): string;
 export interface PagedOptions {
     /** URL of the Paged.js polyfill the frame can load. */

package/types/lib/preview.d.ts

@@ -1,4 +1,4 @@
-import type { TemplateKind, TemplateSettings } from './assemble.js';
+import { type TemplateKind, type TemplateSettings } from './assemble.js';
 /**
  * Preview documents shared by the web editor and `formfeed dev` (spec 06 §3, spec 15 §4): the
  * assembled document of `renderVersion` wrapped for the screen. Flow mode shows one page-wide
@@ -16,8 +16,20 @@ export declare function paperOf(settings: TemplateSettings): {
     width: string;
     height: string;
 };
-/** Chromium's header/footer placeholders replaced for the screen. */
+/**
+ * Chromium's header/footer placeholders filled for the screen. Like Chromium, any element whose class
+ * list names the placeholder counts, whatever else it carries (the editor adds `data-ff-src`), and
+ * the element stays so its styling applies.
+ */
 export declare const pageNumberSpans: (html: string, page: string, total: string) => string;
+/**
+ * Zoom gestures inside a preview frame: Ctrl+wheel (a touchpad pinch arrives as one too) and
+ * Ctrl+plus/minus/0 would zoom the whole app, and the sandboxed frame's events never reach the app,
+ * so the frame cancels them and asks the parent by message:
+ * `{ type: 'formfeed:zoom', deltaY, deltaMode }` or `{ type: 'formfeed:zoom', step: 'in' | 'out' | 'reset' }`.
+ * The office quick preview's frame uses the same script.
+ */
+export declare const zoomGestureScript = "<script>\n(function () {\n  var say = function (message) { try { parent.postMessage(message, '*'); } catch (e) {} };\n  window.addEventListener('wheel', function (event) {\n    if (!event.ctrlKey && !event.metaKey) return;\n    event.preventDefault();\n    say({ type: 'formfeed:zoom', deltaY: event.deltaY, deltaMode: event.deltaMode });\n  }, { passive: false });\n  window.addEventListener('keydown', function (event) {\n    if (!(event.ctrlKey || event.metaKey) || event.altKey) return;\n    var step = event.key === '+' || event.key === '=' ? 'in' : event.key === '-' ? 'out' : event.key === '0' ? 'reset' : null;\n    if (!step) return;\n    event.preventDefault();\n    say({ type: 'formfeed:zoom', step: step });\n  });\n})();\n</script>";
 export declare function flowDocument(draft: RenderedDraft): string;
 export interface PagedOptions {
     /** URL of the Paged.js polyfill the frame can load. */

package/types/lib/schema-diff.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Compares two data schemas from the caller's point of view (spec 19 §3.1): the caller sends data,
+ * the template reads it. A change is breaking when data that fitted the previous schema may no
+ * longer fit the next one. Keywords this module does not analyse compare by deep equality and count
+ * as breaking when they differ, so the check asks rather than waves a change through.
+ *
+ * Worker-safe (no Node APIs): the gateway runs it before publishing and before moving a channel.
+ */
+export type SchemaChangeKind = 'field-added-required' | 'field-added-optional' | 'field-removed' | 'field-became-required' | 'field-became-optional' | 'type-narrowed' | 'type-widened' | 'enum-values-removed' | 'enum-values-added' | 'enum-added' | 'enum-removed' | 'const-changed' | 'constraint-tightened' | 'constraint-relaxed' | 'additional-properties-closed' | 'additional-properties-opened' | 'keyword-changed';
+export interface SchemaChange {
+    /** Dotted field path (`customer.email`, `items[]`); empty for the root. */
+    path: string;
+    /** JSON pointer into the next schema (or the previous one for a removal). */
+    pointer: string;
+    kind: SchemaChangeKind;
+    breaking: boolean;
+    message: string;
+}
+export interface SchemaDiff {
+    breaking: SchemaChange[];
+    safe: SchemaChange[];
+}
+/**
+ * The changes from `previous` to `next`, split into breaking and safe. `null` on either side means
+ * "no schema": nothing to compare, so the result is empty.
+ */
+export declare function diffSchemas(previous: unknown, next: unknown): SchemaDiff;

package/types/lib/schema-diff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Compares two data schemas from the caller's point of view (spec 19 §3.1): the caller sends data,
+ * the template reads it. A change is breaking when data that fitted the previous schema may no
+ * longer fit the next one. Keywords this module does not analyse compare by deep equality and count
+ * as breaking when they differ, so the check asks rather than waves a change through.
+ *
+ * Worker-safe (no Node APIs): the gateway runs it before publishing and before moving a channel.
+ */
+export type SchemaChangeKind = 'field-added-required' | 'field-added-optional' | 'field-removed' | 'field-became-required' | 'field-became-optional' | 'type-narrowed' | 'type-widened' | 'enum-values-removed' | 'enum-values-added' | 'enum-added' | 'enum-removed' | 'const-changed' | 'constraint-tightened' | 'constraint-relaxed' | 'additional-properties-closed' | 'additional-properties-opened' | 'keyword-changed';
+export interface SchemaChange {
+    /** Dotted field path (`customer.email`, `items[]`); empty for the root. */
+    path: string;
+    /** JSON pointer into the next schema (or the previous one for a removal). */
+    pointer: string;
+    kind: SchemaChangeKind;
+    breaking: boolean;
+    message: string;
+}
+export interface SchemaDiff {
+    breaking: SchemaChange[];
+    safe: SchemaChange[];
+}
+/**
+ * The changes from `previous` to `next`, split into breaking and safe. `null` on either side means
+ * "no schema": nothing to compare, so the result is empty.
+ */
+export declare function diffSchemas(previous: unknown, next: unknown): SchemaDiff;

package/types/lib/schema.d.cts

@@ -13,6 +13,12 @@ export interface JsonSchema {
     additionalProperties?: boolean;
 }
 export declare function inferSchema(sample: unknown): JsonSchema;
+/**
+ * One schema over several data sets (spec 19 §2.5): a field is required only when every set has
+ * it, the way array elements are merged. The editor's "Store as contract" uses it, so a field that
+ * only one data set carries becomes optional.
+ */
+export declare function inferSchemaFromDataSets(samples: unknown[]): JsonSchema;
 /** Flat list of dotted paths with their types, for completion items in the editor. */
 export declare function schemaPaths(schema: JsonSchema, prefix?: string[]): Array<{
     path: string[];
@@ -20,3 +26,5 @@ export declare function schemaPaths(schema: JsonSchema, prefix?: string[]): Arra
     format?: string;
     example?: unknown;
 }>;
+export { diffSchemas } from './schema-diff.cjs';
+export type { SchemaChange, SchemaChangeKind, SchemaDiff } from './schema-diff.cjs';

package/types/lib/schema.d.ts

@@ -13,6 +13,12 @@ export interface JsonSchema {
     additionalProperties?: boolean;
 }
 export declare function inferSchema(sample: unknown): JsonSchema;
+/**
+ * One schema over several data sets (spec 19 §2.5): a field is required only when every set has
+ * it, the way array elements are merged. The editor's "Store as contract" uses it, so a field that
+ * only one data set carries becomes optional.
+ */
+export declare function inferSchemaFromDataSets(samples: unknown[]): JsonSchema;
 /** Flat list of dotted paths with their types, for completion items in the editor. */
 export declare function schemaPaths(schema: JsonSchema, prefix?: string[]): Array<{
     path: string[];
@@ -20,3 +26,5 @@ export declare function schemaPaths(schema: JsonSchema, prefix?: string[]): Arra
     format?: string;
     example?: unknown;
 }>;
+export { diffSchemas } from './schema-diff.js';
+export type { SchemaChange, SchemaChangeKind, SchemaDiff } from './schema-diff.js';

package/types/lib/snippets.d.cts

@@ -3,20 +3,57 @@ import type { EngineId } from './types.cjs';
  * Snippet library (spec 06 §2): building blocks in every engine's syntax with the sample data keys
  * they expect, so inserting one also completes the data panel.
  */
+export type SnippetGroup = 'letter' | 'invoice' | 'page' | 'report';
 export interface Snippet {
     id: string;
     title: string;
     description: string;
+    /** Where the library lists the block. */
+    group: SnippetGroup;
+    /** Document kinds the block makes sense in; absent means both (page breaks and footers are PDF only). */
+    kinds?: Array<'pdf' | 'image'>;
+    /**
+     * The document the block belongs in; absent means the template body. Header and footer blocks
+     * style themselves inline, because Chromium renders those templates without the page's CSS.
+     */
+    target?: 'header' | 'footer';
     /** Source per engine; `$0` marks the final cursor position (Monaco snippet syntax). */
     source: Record<EngineId, string>;
     /** Sample data merged (deep, without overwriting) into the template's sample data. */
     sampleData?: Record<string, unknown>;
-    /** CSS appended to the template's stylesheet if the selector prefix is absent. */
+    /**
+     * CSS whose rules are appended when the stylesheet lacks their selector (`mergeSnippetCss`).
+     * Colours and heading fonts read the brand kit's `--brand-*` variables with a neutral fallback.
+     */
     css?: string;
+    /**
+     * Label texts per language for the `t` calls in `source`, merged into the template's dictionaries
+     * without overwriting (`mergeSnippetI18n`), so a German template gets German labels.
+     */
+    i18n?: Record<string, Record<string, string>>;
 }
 export declare const snippets: Snippet[];
 export declare function snippetsFor(engine: EngineId): Array<Snippet & {
     code: string;
 }>;
+/** Snippet code without Monaco tab stops (`$0`, `$1`, `${1:default}` keeps its default), as it renders. */
+export declare function snippetText(code: string): string;
+/**
+ * The line that includes a partial in the engine's syntax, the form the gateway's
+ * `sharedPartialsFor` recognises; `undefined` for a name that syntax cannot carry. Liquid uses
+ * `include`, because `render` hides the template's data from the partial.
+ */
+export declare function partialInclude(engine: EngineId, name: string): string | undefined;
+/**
+ * Appends the rules of a snippet's CSS whose selector list the stylesheet does not have yet, so a
+ * template that already styles `.ff-lines` itself keeps that rule and still gets the others.
+ */
+export declare function mergeSnippetCss(css: string, snippetCss: string | undefined): string;
+/**
+ * Adds a snippet's label texts to the template's dictionaries without overwriting a key: English
+ * always (the `t` helper's last fallback), plus every language the template renders in or already
+ * has a dictionary for. A `de-DE` dictionary gets its keys through `de`, which `t` reads next.
+ */
+export declare function mergeSnippetI18n(dictionaries: unknown, extra: Snippet['i18n'], locale: string): unknown;
 /** Deep merge that keeps existing values; arrays are taken from the base when present. */
 export declare function mergeSampleData(base: unknown, extra: Record<string, unknown> | undefined): unknown;

package/types/lib/snippets.d.ts

@@ -3,20 +3,57 @@ import type { EngineId } from './types.js';
  * Snippet library (spec 06 §2): building blocks in every engine's syntax with the sample data keys
  * they expect, so inserting one also completes the data panel.
  */
+export type SnippetGroup = 'letter' | 'invoice' | 'page' | 'report';
 export interface Snippet {
     id: string;
     title: string;
     description: string;
+    /** Where the library lists the block. */
+    group: SnippetGroup;
+    /** Document kinds the block makes sense in; absent means both (page breaks and footers are PDF only). */
+    kinds?: Array<'pdf' | 'image'>;
+    /**
+     * The document the block belongs in; absent means the template body. Header and footer blocks
+     * style themselves inline, because Chromium renders those templates without the page's CSS.
+     */
+    target?: 'header' | 'footer';
     /** Source per engine; `$0` marks the final cursor position (Monaco snippet syntax). */
     source: Record<EngineId, string>;
     /** Sample data merged (deep, without overwriting) into the template's sample data. */
     sampleData?: Record<string, unknown>;
-    /** CSS appended to the template's stylesheet if the selector prefix is absent. */
+    /**
+     * CSS whose rules are appended when the stylesheet lacks their selector (`mergeSnippetCss`).
+     * Colours and heading fonts read the brand kit's `--brand-*` variables with a neutral fallback.
+     */
     css?: string;
+    /**
+     * Label texts per language for the `t` calls in `source`, merged into the template's dictionaries
+     * without overwriting (`mergeSnippetI18n`), so a German template gets German labels.
+     */
+    i18n?: Record<string, Record<string, string>>;
 }
 export declare const snippets: Snippet[];
 export declare function snippetsFor(engine: EngineId): Array<Snippet & {
     code: string;
 }>;
+/** Snippet code without Monaco tab stops (`$0`, `$1`, `${1:default}` keeps its default), as it renders. */
+export declare function snippetText(code: string): string;
+/**
+ * The line that includes a partial in the engine's syntax, the form the gateway's
+ * `sharedPartialsFor` recognises; `undefined` for a name that syntax cannot carry. Liquid uses
+ * `include`, because `render` hides the template's data from the partial.
+ */
+export declare function partialInclude(engine: EngineId, name: string): string | undefined;
+/**
+ * Appends the rules of a snippet's CSS whose selector list the stylesheet does not have yet, so a
+ * template that already styles `.ff-lines` itself keeps that rule and still gets the others.
+ */
+export declare function mergeSnippetCss(css: string, snippetCss: string | undefined): string;
+/**
+ * Adds a snippet's label texts to the template's dictionaries without overwriting a key: English
+ * always (the `t` helper's last fallback), plus every language the template renders in or already
+ * has a dictionary for. A `de-DE` dictionary gets its keys through `de`, which `t` reads next.
+ */
+export declare function mergeSnippetI18n(dictionaries: unknown, extra: Snippet['i18n'], locale: string): unknown;
 /** Deep merge that keeps existing values; arrays are taken from the base when present. */
 export declare function mergeSampleData(base: unknown, extra: Record<string, unknown> | undefined): unknown;

package/types/lib/source-positions.d.cts

@@ -0,0 +1,27 @@
+import type { EngineId } from './types.cjs';
+/**
+ * Click-to-source for the editor's previews (spec 06 §3): every HTML start tag written literally in
+ * the template source gets `data-ff-src="<file>:<line>:<column>"` right after its tag name, so the
+ * rendered element says where it came from instead of the editor searching the template for it.
+ * Elements from a loop all point at the loop body, which is the line that wrote them.
+ *
+ * The annotation must never change what the template means: tags inside template syntax, in
+ * blocks whose output is captured or filtered as a string (`{% set %}…{% endset %}`, `{% filter %}`,
+ * `{% capture %}`), in raw and comment blocks, in `<script>`/`<style>`/`<textarea>`/`<title>` and
+ * HTML comments, closing tags, declarations, tags whose name is built by template syntax and tags
+ * that already carry the attribute stay untouched. Removing the attribute from the rendered output
+ * gives the document of the original source. Preview only: saved versions, API renders and the
+ * render-worker never see it.
+ */
+export type SourceFile = 'body' | 'header' | 'footer';
+export declare const sourceAttribute = "data-ff-src";
+export interface SourceLocation {
+    file: SourceFile;
+    /** 1-based, as Monaco counts. */
+    line: number;
+    /** 1-based UTF-16 column of the tag's `<`. */
+    column: number;
+}
+/** Parses a `data-ff-src` value; null when it is not one. */
+export declare function parseSourceAttribute(value: string | null | undefined): SourceLocation | null;
+export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile): string;

package/types/lib/source-positions.d.ts

@@ -0,0 +1,27 @@
+import type { EngineId } from './types.js';
+/**
+ * Click-to-source for the editor's previews (spec 06 §3): every HTML start tag written literally in
+ * the template source gets `data-ff-src="<file>:<line>:<column>"` right after its tag name, so the
+ * rendered element says where it came from instead of the editor searching the template for it.
+ * Elements from a loop all point at the loop body, which is the line that wrote them.
+ *
+ * The annotation must never change what the template means: tags inside template syntax, in
+ * blocks whose output is captured or filtered as a string (`{% set %}…{% endset %}`, `{% filter %}`,
+ * `{% capture %}`), in raw and comment blocks, in `<script>`/`<style>`/`<textarea>`/`<title>` and
+ * HTML comments, closing tags, declarations, tags whose name is built by template syntax and tags
+ * that already carry the attribute stay untouched. Removing the attribute from the rendered output
+ * gives the document of the original source. Preview only: saved versions, API renders and the
+ * render-worker never see it.
+ */
+export type SourceFile = 'body' | 'header' | 'footer';
+export declare const sourceAttribute = "data-ff-src";
+export interface SourceLocation {
+    file: SourceFile;
+    /** 1-based, as Monaco counts. */
+    line: number;
+    /** 1-based UTF-16 column of the tag's `<`. */
+    column: number;
+}
+/** Parses a `data-ff-src` value; null when it is not one. */
+export declare function parseSourceAttribute(value: string | null | undefined): SourceLocation | null;
+export declare function annotateSourcePositions(source: string, engine: EngineId, file: SourceFile): string;

package/types/lib/types.d.cts

@@ -1,3 +1,4 @@
+import type { BrandContext } from './brand.cjs';
 /**
  * Shared contracts of `@formfeed/engine` (spec 05). Used by the Angular editor (browser) and the
  * Fly.io render-worker (Node); nothing here may touch Node-only APIs.
@@ -84,6 +85,18 @@ export interface RenderContext {
     i18n?: Record<string, Record<string, string>>;
     /** Base URL for `asset()` (workspace asset root on the CDN). */
     assetBaseUrl?: string;
+    /**
+     * The organisation's brand kit (spec 18): the template global `brand` (request data of the same
+     * name wins) and the `--brand-*` variables the assembler injects.
+     */
+    brand?: BrandContext;
+    /**
+     * `office` renders the text of an office part (spec 22 §4.3): the engines do not escape, because the
+     * text is escaped as a whole when the markup is restored (`office/template-text.ts`). HTML by default.
+     */
+    mode?: 'html' | 'office';
+    /** Office mode, set by `renderOffice`: see `HelperContext.drawing`. */
+    drawing?: (request: OfficeDrawingRequest) => string;
 }
 export interface CompileOptions {
     /** Name used in error messages and as the root include name. */
@@ -128,7 +141,30 @@ export interface HelperContext {
     currency: string;
     i18n?: Record<string, Record<string, string>>;
     assetBaseUrl?: string;
-}
+    /** `office` while an office template is filled (spec 22 §4.4); helpers that emit markup behave differently. */
+    mode?: 'html' | 'office';
+    /**
+     * Office mode: registers a drawing (a code, an image or a page break) and returns the placeholder
+     * the post pass turns into it. Set by `renderOffice`.
+     */
+    drawing?: (request: OfficeDrawingRequest) => string;
+}
+/** What a helper asks the office post pass to place where its placeholder stands. */
+export type OfficeDrawingRequest = {
+    kind: 'svg';
+    svg: string;
+    width?: number | string;
+    height?: number | string;
+    alt?: string;
+} | {
+    kind: 'url';
+    url: string;
+    width?: number | string;
+    height?: number | string;
+    alt?: string;
+} | {
+    kind: 'page-break';
+};
 export interface HelperRegistry {
     /** Registered helpers keyed by canonical name. */
     readonly definitions: ReadonlyMap<string, HelperDefinition>;

package/types/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { BrandContext } from './brand.js';
 /**
  * Shared contracts of `@formfeed/engine` (spec 05). Used by the Angular editor (browser) and the
  * Fly.io render-worker (Node); nothing here may touch Node-only APIs.
@@ -84,6 +85,18 @@ export interface RenderContext {
     i18n?: Record<string, Record<string, string>>;
     /** Base URL for `asset()` (workspace asset root on the CDN). */
     assetBaseUrl?: string;
+    /**
+     * The organisation's brand kit (spec 18): the template global `brand` (request data of the same
+     * name wins) and the `--brand-*` variables the assembler injects.
+     */
+    brand?: BrandContext;
+    /**
+     * `office` renders the text of an office part (spec 22 §4.3): the engines do not escape, because the
+     * text is escaped as a whole when the markup is restored (`office/template-text.ts`). HTML by default.
+     */
+    mode?: 'html' | 'office';
+    /** Office mode, set by `renderOffice`: see `HelperContext.drawing`. */
+    drawing?: (request: OfficeDrawingRequest) => string;
 }
 export interface CompileOptions {
     /** Name used in error messages and as the root include name. */
@@ -128,7 +141,30 @@ export interface HelperContext {
     currency: string;
     i18n?: Record<string, Record<string, string>>;
     assetBaseUrl?: string;
-}
+    /** `office` while an office template is filled (spec 22 §4.4); helpers that emit markup behave differently. */
+    mode?: 'html' | 'office';
+    /**
+     * Office mode: registers a drawing (a code, an image or a page break) and returns the placeholder
+     * the post pass turns into it. Set by `renderOffice`.
+     */
+    drawing?: (request: OfficeDrawingRequest) => string;
+}
+/** What a helper asks the office post pass to place where its placeholder stands. */
+export type OfficeDrawingRequest = {
+    kind: 'svg';
+    svg: string;
+    width?: number | string;
+    height?: number | string;
+    alt?: string;
+} | {
+    kind: 'url';
+    url: string;
+    width?: number | string;
+    height?: number | string;
+    alt?: string;
+} | {
+    kind: 'page-break';
+};
 export interface HelperRegistry {
     /** Registered helpers keyed by canonical name. */
     readonly definitions: ReadonlyMap<string, HelperDefinition>;

package/types/types/modules.d.cts

@@ -33,6 +33,7 @@ declare module 'nunjucks/browser/nunjucks.js' {
     Loader: typeof N.Loader;
     runtime: typeof N.runtime & {
       memberLookup: (obj: unknown, val: unknown, ...rest: unknown[]) => unknown;
+      suppressValue: (val: unknown, autoescape: boolean) => unknown;
     };
     /** The code generator; patched for `not` precedence and namespace attributes (engines/jinja2.ts). */
     compiler: {

package/types/types/modules.d.ts

@@ -33,6 +33,7 @@ declare module 'nunjucks/browser/nunjucks.js' {
     Loader: typeof N.Loader;
     runtime: typeof N.runtime & {
       memberLookup: (obj: unknown, val: unknown, ...rest: unknown[]) => unknown;
+      suppressValue: (val: unknown, autoescape: boolean) => unknown;
     };
     /** The code generator; patched for `not` precedence and namespace attributes (engines/jinja2.ts). */
     compiler: {