@formfeed/engine 0.1.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@formfeed/engine",
+  "version": "0.1.0",
+  "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./types/index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "*.cjs",
+    "types",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@date-fns/tz": "^1.5.0",
+    "bwip-js": "^4.11.4",
+    "date-fns": "^4.4.0",
+    "handlebars": "^4.7.9",
+    "liquidjs": "^10.29.0",
+    "marked": "^18.0.11",
+    "n2words": "^6.1.2",
+    "nunjucks": "^3.2.4",
+    "qrcode": "^1.5.4"
+  },
+  "keywords": [
+    "formfeed",
+    "templates",
+    "template-engine",
+    "jinja2",
+    "liquid",
+    "handlebars",
+    "pdf"
+  ],
+  "homepage": "https://docs.formfeed.dev/devkit/engine-package",
+  "author": {
+    "name": "Formfeed",
+    "email": "support@formfeed.dev",
+    "url": "https://formfeed.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formfeed-dev/formfeed.git",
+    "directory": "packages/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/formfeed-dev/formfeed/issues",
+    "email": "support@formfeed.dev"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/types/index.d.cts

@@ -0,0 +1,17 @@
+export * from './lib/types.cjs';
+export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.cjs';
+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, ImportNote, ImportResult, } from './lib/import/apitemplate.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 { ChartSpec, ImageOptions } from './lib/helpers/index.cjs';
+export { flowDocument, pagedDocument, pageNumberSpans, paperOf } 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 { resolvePath, scanBlocks, jinjaTags, liquidTags, } from './lib/analysis/tags.cjs';

package/types/index.d.ts

@@ -0,0 +1,17 @@
+export * from './lib/types.js';
+export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.js';
+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, ImportNote, ImportResult, } from './lib/import/apitemplate.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 { ChartSpec, ImageOptions } from './lib/helpers/index.js';
+export { flowDocument, pagedDocument, pageNumberSpans, paperOf } 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 { resolvePath, scanBlocks, jinjaTags, liquidTags, } from './lib/analysis/tags.js';

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

@@ -0,0 +1,36 @@
+import type { BlockRef, Diagnostic, Position, Range, VariableRef } from '../types.cjs';
+/** Builds a range from a 1-based start position and a length on the same line. */
+export declare function rangeAt(line: number, column: number, length: number): Range;
+/** Converts a 0-based offset into a 1-based position. */
+export declare function positionOf(source: string, offset: number): Position;
+export declare function rangeOf(source: string, start: number, end: number): Range;
+interface TagSpec {
+    /** Regex over the whole source; group 1 = tag keyword, group 2 = the rest of the tag. */
+    pattern: RegExp;
+    openers: Record<string, BlockRef['type']>;
+    /** Closing keyword → opening keyword. */
+    closers: Record<string, string>;
+    /** Keywords that continue a block without opening or closing one. */
+    continuations: string[];
+}
+export declare const jinjaTags: TagSpec;
+export declare const liquidTags: TagSpec;
+/**
+ * Pairs opening and closing block tags by text scan. Works even when the parser bails out on the
+ * first error, so the editor gets every mismatch at once (spec 05 §3).
+ */
+export declare function scanBlocks(source: string, spec: TagSpec): {
+    blocks: BlockRef[];
+    diagnostics: Diagnostic[];
+};
+/** Looks a path up in sample data; arrays are traversed by union of their items' keys. */
+export declare function resolvePath(data: unknown, path: string[]): {
+    found: boolean;
+    value: unknown;
+};
+/**
+ * Warns for `read` variables whose path is missing from the sample data. Loop variables are
+ * resolved through their source (`for line in invoice.lines` → `invoice.lines[]`) when known.
+ */
+export declare function missingPathDiagnostics(variables: VariableRef[], sampleData: unknown, loopSources: Map<string, string[] | null>, builtinRoots: Set<string>): Diagnostic[];
+export {};

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

@@ -0,0 +1,36 @@
+import type { BlockRef, Diagnostic, Position, Range, VariableRef } from '../types.js';
+/** Builds a range from a 1-based start position and a length on the same line. */
+export declare function rangeAt(line: number, column: number, length: number): Range;
+/** Converts a 0-based offset into a 1-based position. */
+export declare function positionOf(source: string, offset: number): Position;
+export declare function rangeOf(source: string, start: number, end: number): Range;
+interface TagSpec {
+    /** Regex over the whole source; group 1 = tag keyword, group 2 = the rest of the tag. */
+    pattern: RegExp;
+    openers: Record<string, BlockRef['type']>;
+    /** Closing keyword → opening keyword. */
+    closers: Record<string, string>;
+    /** Keywords that continue a block without opening or closing one. */
+    continuations: string[];
+}
+export declare const jinjaTags: TagSpec;
+export declare const liquidTags: TagSpec;
+/**
+ * Pairs opening and closing block tags by text scan. Works even when the parser bails out on the
+ * first error, so the editor gets every mismatch at once (spec 05 §3).
+ */
+export declare function scanBlocks(source: string, spec: TagSpec): {
+    blocks: BlockRef[];
+    diagnostics: Diagnostic[];
+};
+/** Looks a path up in sample data; arrays are traversed by union of their items' keys. */
+export declare function resolvePath(data: unknown, path: string[]): {
+    found: boolean;
+    value: unknown;
+};
+/**
+ * Warns for `read` variables whose path is missing from the sample data. Loop variables are
+ * resolved through their source (`for line in invoice.lines` → `invoice.lines[]`) when known.
+ */
+export declare function missingPathDiagnostics(variables: VariableRef[], sampleData: unknown, loopSources: Map<string, string[] | null>, builtinRoots: Set<string>): Diagnostic[];
+export {};

package/types/lib/assemble.d.cts

@@ -0,0 +1,147 @@
+import type { EngineId, RenderContext } from './types.cjs';
+/** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
+export interface TemplateSettings {
+    paper?: {
+        format?: string;
+        width?: string | null;
+        height?: string | null;
+        unit?: 'mm' | 'in' | 'px';
+        landscape?: boolean;
+    };
+    margin?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+    header?: {
+        html?: string;
+        height?: string;
+    } | null;
+    footer?: {
+        html?: string;
+        height?: string;
+    } | null;
+    printBackground?: boolean;
+    scale?: number;
+    preferCssPageSize?: boolean;
+    pageRanges?: string;
+    waitFor?: {
+        networkIdle?: boolean;
+        selector?: string | null;
+        timeoutMs?: number;
+        delayMs?: number;
+    };
+    pdf?: {
+        tagged?: boolean;
+        outline?: boolean;
+        metadata?: {
+            title?: string;
+            author?: string;
+            subject?: string;
+            keywords?: string;
+        };
+    };
+    image?: {
+        width?: number;
+        height?: number;
+        deviceScaleFactor?: number;
+        format?: 'png' | 'jpeg' | 'webp';
+        quality?: number;
+        fullPage?: boolean;
+        transparent?: boolean;
+        clipSelector?: string | null;
+    };
+    locale?: string;
+    timezone?: string;
+    currency?: string;
+    tailwind?: boolean;
+    watermark?: {
+        text?: string;
+        opacity?: number;
+    } | null;
+}
+export type TemplateKind = 'pdf' | 'image';
+export declare function defaultSettings(): Required<Pick<TemplateSettings, 'paper' | 'margin' | 'printBackground' | 'scale' | 'preferCssPageSize' | 'locale' | 'timezone' | 'currency'>> & TemplateSettings;
+/** Deep merge where `override` wins; `null` removes a section (e.g. `header: null`). */
+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. */
+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 {
+    family: string;
+    weight?: number;
+    style?: 'normal' | 'italic';
+    format?: 'woff2' | 'woff' | 'ttf' | 'otf';
+    url: string;
+}
+/** Browser-side vendor scripts the assembler wires in when the document needs them. */
+export interface AssembleVendor {
+    /** Chart.js UMD build: a URL the frame can load, or the source to inline (render-worker). */
+    chartJs?: {
+        src: string;
+    } | {
+        inline: string;
+    };
+    /** `@tailwindcss/browser` for the preview; the worker compiles Tailwind ahead and passes `extraCss`. */
+    tailwind?: {
+        src: string;
+    };
+}
+/** Optional inputs that vary per host (preview frame vs. worker) rather than per template. */
+export interface AssembleExtras {
+    fonts?: FontFace[];
+    vendor?: AssembleVendor;
+    /** Stylesheet appended after the template CSS (compiled Tailwind in the worker). */
+    extraCss?: string;
+}
+/**
+ * `@font-face` rules for the organisation fonts a template refers to (spec 05 §6): a font is
+ * injected when its family name appears anywhere in the template's CSS, head or HTML.
+ */
+export declare function fontFaceCss(fonts: FontFace[] | undefined, referencedIn: string): string;
+/** Draws every `canvas[data-ff-chart]` placed by the `chart` helper; runs after the body is parsed. */
+export declare function chartInitScript(): string;
+export interface AssembleInput extends AssembleExtras {
+    /** Rendered body HTML (engine output). */
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: TemplateSettings;
+    kind?: TemplateKind;
+    /** Base URL for relative asset references (`<base href>`); omitted when undefined. */
+    assetBaseUrl?: string;
+    /** Preview marks the document so the preview frame can style it; print is what Chromium gets. */
+    mode?: 'preview' | 'print';
+    title?: string;
+}
+/** Produces the full document handed to Chromium or the preview frame (spec 05 §5). */
+export declare function assembleDocument(input: AssembleInput): string;
+export interface VersionSource {
+    engine: EngineId;
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: TemplateSettings;
+    kind?: TemplateKind;
+}
+export interface RenderedDocument {
+    /** Complete HTML document. */
+    document: string;
+    /** Rendered header/footer HTML for Chromium's `headerTemplate`/`footerTemplate`, when configured. */
+    headerHtml?: string;
+    footerHtml?: string;
+    /** PDF metadata title after template rendering. */
+    title?: string;
+    settings: TemplateSettings;
+    /** Font faces and extra CSS the header/footer templates need inlined (Chromium loads no external CSS there). */
+    inlineCss: string;
+}
+/**
+ * Renders a template version end to end: body, header, footer and metadata with the same engine and
+ * data, then assembles the document. Header and footer are rendered without autoescape differences:
+ * they are HTML by definition.
+ */
+export declare function renderVersion(version: VersionSource, data: unknown, ctx: RenderContext, mode?: 'preview' | 'print', extras?: AssembleExtras): Promise<RenderedDocument>;

package/types/lib/assemble.d.ts

@@ -0,0 +1,147 @@
+import type { EngineId, RenderContext } from './types.js';
+/** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
+export interface TemplateSettings {
+    paper?: {
+        format?: string;
+        width?: string | null;
+        height?: string | null;
+        unit?: 'mm' | 'in' | 'px';
+        landscape?: boolean;
+    };
+    margin?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+    header?: {
+        html?: string;
+        height?: string;
+    } | null;
+    footer?: {
+        html?: string;
+        height?: string;
+    } | null;
+    printBackground?: boolean;
+    scale?: number;
+    preferCssPageSize?: boolean;
+    pageRanges?: string;
+    waitFor?: {
+        networkIdle?: boolean;
+        selector?: string | null;
+        timeoutMs?: number;
+        delayMs?: number;
+    };
+    pdf?: {
+        tagged?: boolean;
+        outline?: boolean;
+        metadata?: {
+            title?: string;
+            author?: string;
+            subject?: string;
+            keywords?: string;
+        };
+    };
+    image?: {
+        width?: number;
+        height?: number;
+        deviceScaleFactor?: number;
+        format?: 'png' | 'jpeg' | 'webp';
+        quality?: number;
+        fullPage?: boolean;
+        transparent?: boolean;
+        clipSelector?: string | null;
+    };
+    locale?: string;
+    timezone?: string;
+    currency?: string;
+    tailwind?: boolean;
+    watermark?: {
+        text?: string;
+        opacity?: number;
+    } | null;
+}
+export type TemplateKind = 'pdf' | 'image';
+export declare function defaultSettings(): Required<Pick<TemplateSettings, 'paper' | 'margin' | 'printBackground' | 'scale' | 'preferCssPageSize' | 'locale' | 'timezone' | 'currency'>> & TemplateSettings;
+/** Deep merge where `override` wins; `null` removes a section (e.g. `header: null`). */
+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. */
+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 {
+    family: string;
+    weight?: number;
+    style?: 'normal' | 'italic';
+    format?: 'woff2' | 'woff' | 'ttf' | 'otf';
+    url: string;
+}
+/** Browser-side vendor scripts the assembler wires in when the document needs them. */
+export interface AssembleVendor {
+    /** Chart.js UMD build: a URL the frame can load, or the source to inline (render-worker). */
+    chartJs?: {
+        src: string;
+    } | {
+        inline: string;
+    };
+    /** `@tailwindcss/browser` for the preview; the worker compiles Tailwind ahead and passes `extraCss`. */
+    tailwind?: {
+        src: string;
+    };
+}
+/** Optional inputs that vary per host (preview frame vs. worker) rather than per template. */
+export interface AssembleExtras {
+    fonts?: FontFace[];
+    vendor?: AssembleVendor;
+    /** Stylesheet appended after the template CSS (compiled Tailwind in the worker). */
+    extraCss?: string;
+}
+/**
+ * `@font-face` rules for the organisation fonts a template refers to (spec 05 §6): a font is
+ * injected when its family name appears anywhere in the template's CSS, head or HTML.
+ */
+export declare function fontFaceCss(fonts: FontFace[] | undefined, referencedIn: string): string;
+/** Draws every `canvas[data-ff-chart]` placed by the `chart` helper; runs after the body is parsed. */
+export declare function chartInitScript(): string;
+export interface AssembleInput extends AssembleExtras {
+    /** Rendered body HTML (engine output). */
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: TemplateSettings;
+    kind?: TemplateKind;
+    /** Base URL for relative asset references (`<base href>`); omitted when undefined. */
+    assetBaseUrl?: string;
+    /** Preview marks the document so the preview frame can style it; print is what Chromium gets. */
+    mode?: 'preview' | 'print';
+    title?: string;
+}
+/** Produces the full document handed to Chromium or the preview frame (spec 05 §5). */
+export declare function assembleDocument(input: AssembleInput): string;
+export interface VersionSource {
+    engine: EngineId;
+    html: string;
+    css?: string;
+    head?: string;
+    settings?: TemplateSettings;
+    kind?: TemplateKind;
+}
+export interface RenderedDocument {
+    /** Complete HTML document. */
+    document: string;
+    /** Rendered header/footer HTML for Chromium's `headerTemplate`/`footerTemplate`, when configured. */
+    headerHtml?: string;
+    footerHtml?: string;
+    /** PDF metadata title after template rendering. */
+    title?: string;
+    settings: TemplateSettings;
+    /** Font faces and extra CSS the header/footer templates need inlined (Chromium loads no external CSS there). */
+    inlineCss: string;
+}
+/**
+ * Renders a template version end to end: body, header, footer and metadata with the same engine and
+ * data, then assembles the document. Header and footer are rendered without autoescape differences:
+ * they are HTML by definition.
+ */
+export declare function renderVersion(version: VersionSource, data: unknown, ctx: RenderContext, mode?: 'preview' | 'print', extras?: AssembleExtras): Promise<RenderedDocument>;

package/types/lib/engines/handlebars.d.cts

@@ -0,0 +1,3 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.cjs';
+export declare function analyzeHandlebars(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const handlebarsEngine: Engine;

package/types/lib/engines/handlebars.d.ts

@@ -0,0 +1,3 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.js';
+export declare function analyzeHandlebars(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const handlebarsEngine: Engine;

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

@@ -0,0 +1,7 @@
+import type { Engine, EngineId } from '../types.cjs';
+export { analyzeHandlebars, handlebarsEngine } from './handlebars.cjs';
+export { analyzeJinja2, jinja2Engine, nunjucksBuiltinFilters } from './jinja2.cjs';
+export { analyzeLiquid, liquidBuiltinFilters, liquidEngine } from './liquid.cjs';
+export declare const engines: Record<EngineId, Engine>;
+export declare const engineIds: EngineId[];
+export declare function getEngine(id: EngineId | string): Engine;

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

@@ -0,0 +1,7 @@
+import type { Engine, EngineId } from '../types.js';
+export { analyzeHandlebars, handlebarsEngine } from './handlebars.js';
+export { analyzeJinja2, jinja2Engine, nunjucksBuiltinFilters } from './jinja2.js';
+export { analyzeLiquid, liquidBuiltinFilters, liquidEngine } from './liquid.js';
+export declare const engines: Record<EngineId, Engine>;
+export declare const engineIds: EngineId[];
+export declare function getEngine(id: EngineId | string): Engine;

package/types/lib/engines/jinja2.d.cts

@@ -0,0 +1,5 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.cjs';
+/** Nunjucks built-in filters that count as known even without a helper of the same name. */
+export declare const nunjucksBuiltinFilters: Set<string>;
+export declare function analyzeJinja2(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const jinja2Engine: Engine;

package/types/lib/engines/jinja2.d.ts

@@ -0,0 +1,5 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.js';
+/** Nunjucks built-in filters that count as known even without a helper of the same name. */
+export declare const nunjucksBuiltinFilters: Set<string>;
+export declare function analyzeJinja2(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const jinja2Engine: Engine;

package/types/lib/engines/liquid.d.cts

@@ -0,0 +1,16 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.cjs';
+/** LiquidJS standard filters (Shopify set) that count as known. */
+export declare const liquidBuiltinFilters: Set<string>;
+/**
+ * LiquidJS hands keyword filter arguments (`| image: width: 120, fit: 'cover'`) over as `[key, value]`
+ * pairs after the positional ones. They become one trailing options object, the shape the helpers
+ * take in Jinja2 (`{ width: 120 }`) and Handlebars (hash arguments), so all engines share one helper.
+ *
+ * Which arguments are keywords comes from the parsed filter token (`isKeyword`), never from the
+ * value: at runtime a `[key, value]` pair and a two-element array of strings look the same, and
+ * guessing by shape turned `['red', 'green'] | join: ', '` into the keyword argument `red: 'green'`
+ * — a list that worked with three entries silently broke with exactly two.
+ */
+export declare function collectKeywordArgs(args: unknown[], isKeyword: (index: number) => boolean): unknown[];
+export declare function analyzeLiquid(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const liquidEngine: Engine;

package/types/lib/engines/liquid.d.ts

@@ -0,0 +1,16 @@
+import type { Analysis, AnalyzeOptions, Engine } from '../types.js';
+/** LiquidJS standard filters (Shopify set) that count as known. */
+export declare const liquidBuiltinFilters: Set<string>;
+/**
+ * LiquidJS hands keyword filter arguments (`| image: width: 120, fit: 'cover'`) over as `[key, value]`
+ * pairs after the positional ones. They become one trailing options object, the shape the helpers
+ * take in Jinja2 (`{ width: 120 }`) and Handlebars (hash arguments), so all engines share one helper.
+ *
+ * Which arguments are keywords comes from the parsed filter token (`isKeyword`), never from the
+ * value: at runtime a `[key, value]` pair and a two-element array of strings look the same, and
+ * guessing by shape turned `['red', 'green'] | join: ', '` into the keyword argument `red: 'green'`
+ * — a list that worked with three entries silently broke with exactly two.
+ */
+export declare function collectKeywordArgs(args: unknown[], isKeyword: (index: number) => boolean): unknown[];
+export declare function analyzeLiquid(source: string, opts?: AnalyzeOptions): Analysis;
+export declare const liquidEngine: Engine;

package/types/lib/errors.d.cts

@@ -0,0 +1,24 @@
+import type { EngineId, Position } from './types.cjs';
+/** Parse or compile failure with a location the editor can jump to. */
+export declare class EngineSyntaxError extends Error {
+    readonly engine: EngineId;
+    readonly line: number;
+    readonly column: number;
+    readonly name = "EngineSyntaxError";
+    constructor(engine: EngineId, message: string, line: number, column: number);
+    get position(): Position;
+}
+/** A render exceeded one of the limits in `RenderLimits` (spec 05 §7). */
+export declare class RenderLimitError extends Error {
+    readonly limit: 'ms' | 'outputBytes' | 'includeDepth';
+    readonly name = "RenderLimitError";
+    constructor(limit: 'ms' | 'outputBytes' | 'includeDepth', message: string);
+}
+/** Runtime failure inside a template (unknown filter at render time, helper threw, ...). */
+export declare class RenderError extends Error {
+    readonly engine: EngineId;
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    readonly name = "RenderError";
+    constructor(engine: EngineId, message: string, line?: number | undefined, column?: number | undefined);
+}

package/types/lib/errors.d.ts

@@ -0,0 +1,24 @@
+import type { EngineId, Position } from './types.js';
+/** Parse or compile failure with a location the editor can jump to. */
+export declare class EngineSyntaxError extends Error {
+    readonly engine: EngineId;
+    readonly line: number;
+    readonly column: number;
+    readonly name = "EngineSyntaxError";
+    constructor(engine: EngineId, message: string, line: number, column: number);
+    get position(): Position;
+}
+/** A render exceeded one of the limits in `RenderLimits` (spec 05 §7). */
+export declare class RenderLimitError extends Error {
+    readonly limit: 'ms' | 'outputBytes' | 'includeDepth';
+    readonly name = "RenderLimitError";
+    constructor(limit: 'ms' | 'outputBytes' | 'includeDepth', message: string);
+}
+/** Runtime failure inside a template (unknown filter at render time, helper threw, ...). */
+export declare class RenderError extends Error {
+    readonly engine: EngineId;
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    readonly name = "RenderError";
+    constructor(engine: EngineId, message: string, line?: number | undefined, column?: number | undefined);
+}

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

@@ -0,0 +1,21 @@
+import type { HelperDefinition } from '../types.cjs';
+type QrOptions = {
+    size?: number;
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    margin?: number;
+    color?: string;
+    background?: string;
+};
+export declare function qrSvg(value: string, options?: QrOptions): string;
+/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
+export declare function epcPayload(input: {
+    name: string;
+    iban: string;
+    bic?: string;
+    amount?: number | string;
+    reference?: string;
+    text?: string;
+    purpose?: string;
+}): string;
+export declare const codeHelpers: HelperDefinition[];
+export {};

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

@@ -0,0 +1,21 @@
+import type { HelperDefinition } from '../types.js';
+type QrOptions = {
+    size?: number;
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    margin?: number;
+    color?: string;
+    background?: string;
+};
+export declare function qrSvg(value: string, options?: QrOptions): string;
+/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
+export declare function epcPayload(input: {
+    name: string;
+    iban: string;
+    bic?: string;
+    amount?: number | string;
+    reference?: string;
+    text?: string;
+    purpose?: string;
+}): string;
+export declare const codeHelpers: HelperDefinition[];
+export {};

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

@@ -0,0 +1,2 @@
+import type { HelperDefinition } from '../types.cjs';
+export declare const collectionHelpers: HelperDefinition[];

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

@@ -0,0 +1,2 @@
+import type { HelperDefinition } from '../types.js';
+export declare const collectionHelpers: HelperDefinition[];