@formfeed/engine 0.1.0

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

@@ -0,0 +1,29 @@
+import type { HelperDefinition } from '../types.cjs';
+/**
+ * Document helpers that emit markup the assembler completes (spec 05 §2): `chart` places a canvas
+ * that Chart.js draws inside Chromium (browser preview and render-worker alike, so both paths
+ * produce the same pixels), `image` places a sized, cropped picture.
+ */
+export interface ChartSpec {
+    type?: string;
+    data?: unknown;
+    options?: Record<string, unknown>;
+    width?: number | string;
+    height?: number | string;
+}
+export interface ImageOptions {
+    width?: number | string;
+    height?: number | string;
+    fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    class?: string;
+}
+/** The chart payload the assembler's init script reads from `data-ff-chart`. */
+export declare function chartPayload(spec: ChartSpec): {
+    type: string;
+    data: unknown;
+    options: Record<string, unknown>;
+};
+export declare function chartMarkup(spec: ChartSpec, id?: string): string;
+export declare function imageMarkup(url: string, options?: ImageOptions): string;
+export declare const documentHelpers: HelperDefinition[];

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

@@ -0,0 +1,29 @@
+import type { HelperDefinition } from '../types.js';
+/**
+ * Document helpers that emit markup the assembler completes (spec 05 §2): `chart` places a canvas
+ * that Chart.js draws inside Chromium (browser preview and render-worker alike, so both paths
+ * produce the same pixels), `image` places a sized, cropped picture.
+ */
+export interface ChartSpec {
+    type?: string;
+    data?: unknown;
+    options?: Record<string, unknown>;
+    width?: number | string;
+    height?: number | string;
+}
+export interface ImageOptions {
+    width?: number | string;
+    height?: number | string;
+    fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    alt?: string;
+    class?: string;
+}
+/** The chart payload the assembler's init script reads from `data-ff-chart`. */
+export declare function chartPayload(spec: ChartSpec): {
+    type: string;
+    data: unknown;
+    options: Record<string, unknown>;
+};
+export declare function chartMarkup(spec: ChartSpec, id?: string): string;
+export declare function imageMarkup(url: string, options?: ImageOptions): string;
+export declare const documentHelpers: HelperDefinition[];

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

@@ -0,0 +1,5 @@
+import type { HelperDefinition } from '../types.cjs';
+export declare function toNumber(value: unknown): number;
+export declare function toDate(value: unknown, tz: string): Date | null;
+export declare function escapeHtml(value: string): string;
+export declare const formatHelpers: HelperDefinition[];

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

@@ -0,0 +1,5 @@
+import type { HelperDefinition } from '../types.js';
+export declare function toNumber(value: unknown): number;
+export declare function toDate(value: unknown, tz: string): Date | null;
+export declare function escapeHtml(value: string): string;
+export declare const formatHelpers: HelperDefinition[];

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

@@ -0,0 +1,17 @@
+import type { HelperDefinition, HelperDoc } from '../types.cjs';
+import { DefaultHelperRegistry } from './registry.cjs';
+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 type { ChartSpec, ImageOptions } from './document.cjs';
+/** Helpers shipped with the product (spec 05 §2), identical in all three engines. */
+export declare const builtinHelpers: HelperDefinition[];
+export declare function createHelperRegistry(extra?: HelperDefinition[]): DefaultHelperRegistry;
+/** Lazily built default registry, shared by analyze() and the engines when none is supplied. */
+export declare function defaultHelpers(): DefaultHelperRegistry;
+/** Documentation entries that feed editor hover and completion (spec 05 §2). */
+export declare function helperDocs(registry?: DefaultHelperRegistry): Array<HelperDoc & {
+    name: string;
+    aliases: string[];
+}>;

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

@@ -0,0 +1,17 @@
+import type { HelperDefinition, HelperDoc } from '../types.js';
+import { DefaultHelperRegistry } from './registry.js';
+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 type { ChartSpec, ImageOptions } from './document.js';
+/** Helpers shipped with the product (spec 05 §2), identical in all three engines. */
+export declare const builtinHelpers: HelperDefinition[];
+export declare function createHelperRegistry(extra?: HelperDefinition[]): DefaultHelperRegistry;
+/** Lazily built default registry, shared by analyze() and the engines when none is supplied. */
+export declare function defaultHelpers(): DefaultHelperRegistry;
+/** Documentation entries that feed editor hover and completion (spec 05 §2). */
+export declare function helperDocs(registry?: DefaultHelperRegistry): Array<HelperDoc & {
+    name: string;
+    aliases: string[];
+}>;

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

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

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

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

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

@@ -0,0 +1,18 @@
+import type { HelperContext, HelperDefinition, HelperRegistry } from '../types.cjs';
+/** Registry of helpers shared by all engines (spec 05 §2). */
+export declare class DefaultHelperRegistry implements HelperRegistry {
+    private readonly byName;
+    private readonly aliasToName;
+    constructor(definitions?: HelperDefinition[]);
+    get definitions(): ReadonlyMap<string, HelperDefinition>;
+    register(definition: HelperDefinition): void;
+    get(name: string): HelperDefinition | undefined;
+    has(name: string): boolean;
+    names(): string[];
+    /** The preferred name when `name` is a deprecated alias, otherwise undefined. */
+    deprecationOf(name: string): string | undefined;
+    bind(ctx: HelperContext): Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        html: boolean;
+    }>;
+}

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

@@ -0,0 +1,18 @@
+import type { HelperContext, HelperDefinition, HelperRegistry } from '../types.js';
+/** Registry of helpers shared by all engines (spec 05 §2). */
+export declare class DefaultHelperRegistry implements HelperRegistry {
+    private readonly byName;
+    private readonly aliasToName;
+    constructor(definitions?: HelperDefinition[]);
+    get definitions(): ReadonlyMap<string, HelperDefinition>;
+    register(definition: HelperDefinition): void;
+    get(name: string): HelperDefinition | undefined;
+    has(name: string): boolean;
+    names(): string[];
+    /** The preferred name when `name` is a deprecated alias, otherwise undefined. */
+    deprecationOf(name: string): string | undefined;
+    bind(ctx: HelperContext): Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        html: boolean;
+    }>;
+}

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

@@ -0,0 +1,45 @@
+import type { TemplateSettings } from '../assemble.cjs';
+/**
+ * apitemplate.io importer (spec 10 §4, spec 05 §8): turns an exported template (HTML body, CSS,
+ * settings, sample JSON) into a Formfeed draft and a report of what needs attention. The Jinja2
+ * engine already carries the compatibility layer (string methods, `.items()`, filter aliases), so
+ * the source is kept verbatim apart from placeholders in header and footer templates.
+ */
+export interface ApitemplateExport {
+    name?: string;
+    html: string;
+    css?: string;
+    /** apitemplate.io template settings (paper, margins, header/footer templates, image options). */
+    settings?: Record<string, unknown> | null;
+    /** Their sample JSON; a string is parsed. */
+    sample_data?: unknown;
+    /** Their template format; JPEG and PNG become image templates. */
+    format?: string | null;
+}
+export interface ImportNote {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    /** Path under docs.formfeed.dev with the details. */
+    docs?: string;
+}
+export interface ImportResult {
+    name: string;
+    slug: string;
+    kind: 'pdf' | 'image';
+    engine: 'jinja2';
+    html: string;
+    css: string;
+    head: string;
+    settings: TemplateSettings;
+    sampleData: unknown;
+    /** Compile or analysis errors: the draft is created, but it will not render as is. */
+    errors: ImportNote[];
+    /** Unknown filters, unsupported Python constructs, ignored settings. */
+    warnings: ImportNote[];
+    /** What the importer changed or mapped. */
+    changes: string[];
+}
+export declare function slugFromName(name: string): string;
+export declare function importApitemplate(input: ApitemplateExport): ImportResult;

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

@@ -0,0 +1,45 @@
+import type { TemplateSettings } from '../assemble.js';
+/**
+ * apitemplate.io importer (spec 10 §4, spec 05 §8): turns an exported template (HTML body, CSS,
+ * settings, sample JSON) into a Formfeed draft and a report of what needs attention. The Jinja2
+ * engine already carries the compatibility layer (string methods, `.items()`, filter aliases), so
+ * the source is kept verbatim apart from placeholders in header and footer templates.
+ */
+export interface ApitemplateExport {
+    name?: string;
+    html: string;
+    css?: string;
+    /** apitemplate.io template settings (paper, margins, header/footer templates, image options). */
+    settings?: Record<string, unknown> | null;
+    /** Their sample JSON; a string is parsed. */
+    sample_data?: unknown;
+    /** Their template format; JPEG and PNG become image templates. */
+    format?: string | null;
+}
+export interface ImportNote {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    /** Path under docs.formfeed.dev with the details. */
+    docs?: string;
+}
+export interface ImportResult {
+    name: string;
+    slug: string;
+    kind: 'pdf' | 'image';
+    engine: 'jinja2';
+    html: string;
+    css: string;
+    head: string;
+    settings: TemplateSettings;
+    sampleData: unknown;
+    /** Compile or analysis errors: the draft is created, but it will not render as is. */
+    errors: ImportNote[];
+    /** Unknown filters, unsupported Python constructs, ignored settings. */
+    warnings: ImportNote[];
+    /** What the importer changed or mapped. */
+    changes: string[];
+}
+export declare function slugFromName(name: string): string;
+export declare function importApitemplate(input: ApitemplateExport): ImportResult;

package/types/lib/limits.d.cts

@@ -0,0 +1,10 @@
+import type { RenderLimits } from './types.cjs';
+/** Limits of spec 05 §7 for a normal render. */
+export declare const defaultLimits: RenderLimits;
+/**
+ * Post-hoc enforcement for synchronous engines: the render-worker isolates runaway templates with a
+ * process timeout; here we reject oversized or overlong results so they never reach Chromium.
+ */
+export declare function enforceLimits(output: string, startedAt: number, limits: RenderLimits): string;
+/** Wraps a partial resolver so nested includes past `includeDepth` fail instead of recursing. */
+export declare function depthGuard(resolve: (name: string) => string | undefined, includeDepth: number): (name: string) => string | undefined;

package/types/lib/limits.d.ts

@@ -0,0 +1,10 @@
+import type { RenderLimits } from './types.js';
+/** Limits of spec 05 §7 for a normal render. */
+export declare const defaultLimits: RenderLimits;
+/**
+ * Post-hoc enforcement for synchronous engines: the render-worker isolates runaway templates with a
+ * process timeout; here we reject oversized or overlong results so they never reach Chromium.
+ */
+export declare function enforceLimits(output: string, startedAt: number, limits: RenderLimits): string;
+/** Wraps a partial resolver so nested includes past `includeDepth` fail instead of recursing. */
+export declare function depthGuard(resolve: (name: string) => string | undefined, includeDepth: number): (name: string) => string | undefined;

package/types/lib/preview.d.cts

@@ -0,0 +1,30 @@
+import type { TemplateKind, 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
+ * sheet with margins, header and footer emulated; paged mode lets Paged.js paginate with the
+ * `@page` rule of the print reset and turns header and footer into running elements.
+ */
+export interface RenderedDraft {
+    document: string;
+    headerHtml?: string;
+    footerHtml?: string;
+    settings: TemplateSettings;
+    kind: TemplateKind;
+}
+export declare function paperOf(settings: TemplateSettings): {
+    width: string;
+    height: string;
+};
+/** Chromium's header/footer placeholders replaced for the screen. */
+export declare const pageNumberSpans: (html: string, page: string, total: string) => string;
+export declare function flowDocument(draft: RenderedDraft): string;
+export interface PagedOptions {
+    /** URL of the Paged.js polyfill the frame can load. */
+    pagedScriptUrl: string;
+}
+/**
+ * Charts are drawn after pagination (Paged.js clones the content into pages and a cloned canvas is
+ * blank) and the page count is posted to the parent as `{ type: 'formfeed:pages', pages }`.
+ */
+export declare function pagedDocument(draft: RenderedDraft, options: PagedOptions): string;

package/types/lib/preview.d.ts

@@ -0,0 +1,30 @@
+import type { TemplateKind, 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
+ * sheet with margins, header and footer emulated; paged mode lets Paged.js paginate with the
+ * `@page` rule of the print reset and turns header and footer into running elements.
+ */
+export interface RenderedDraft {
+    document: string;
+    headerHtml?: string;
+    footerHtml?: string;
+    settings: TemplateSettings;
+    kind: TemplateKind;
+}
+export declare function paperOf(settings: TemplateSettings): {
+    width: string;
+    height: string;
+};
+/** Chromium's header/footer placeholders replaced for the screen. */
+export declare const pageNumberSpans: (html: string, page: string, total: string) => string;
+export declare function flowDocument(draft: RenderedDraft): string;
+export interface PagedOptions {
+    /** URL of the Paged.js polyfill the frame can load. */
+    pagedScriptUrl: string;
+}
+/**
+ * Charts are drawn after pagination (Paged.js clones the content into pages and a cloned canvas is
+ * blank) and the page count is posted to the parent as `{ type: 'formfeed:pages', pages }`.
+ */
+export declare function pagedDocument(draft: RenderedDraft, options: PagedOptions): string;

package/types/lib/schema.d.cts

@@ -0,0 +1,22 @@
+/**
+ * JSON Schema (draft 2020-12) inference from sample data (spec 05 §4). Arrays infer their item
+ * schema from every element; objects mark keys present in all samples as required.
+ */
+export interface JsonSchema {
+    $schema?: string;
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    examples?: unknown[];
+    format?: string;
+    additionalProperties?: boolean;
+}
+export declare function inferSchema(sample: 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[];
+    type: string;
+    format?: string;
+    example?: unknown;
+}>;

package/types/lib/schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JSON Schema (draft 2020-12) inference from sample data (spec 05 §4). Arrays infer their item
+ * schema from every element; objects mark keys present in all samples as required.
+ */
+export interface JsonSchema {
+    $schema?: string;
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    examples?: unknown[];
+    format?: string;
+    additionalProperties?: boolean;
+}
+export declare function inferSchema(sample: 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[];
+    type: string;
+    format?: string;
+    example?: unknown;
+}>;

package/types/lib/snippets.d.cts

@@ -0,0 +1,22 @@
+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 interface Snippet {
+    id: string;
+    title: string;
+    description: string;
+    /** 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?: string;
+}
+export declare const snippets: Snippet[];
+export declare function snippetsFor(engine: EngineId): Array<Snippet & {
+    code: string;
+}>;
+/** 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

@@ -0,0 +1,22 @@
+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 interface Snippet {
+    id: string;
+    title: string;
+    description: string;
+    /** 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?: string;
+}
+export declare const snippets: Snippet[];
+export declare function snippetsFor(engine: EngineId): Array<Snippet & {
+    code: string;
+}>;
+/** 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/types.d.cts

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ */
+export type EngineId = 'jinja2' | 'liquid' | 'handlebars';
+/** 1-based line and column, end exclusive. */
+export interface Position {
+    line: number;
+    column: number;
+}
+export interface Range {
+    start: Position;
+    end: Position;
+}
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    range: Range;
+    /** Stable code the editor keys quick-fixes and docs on, e.g. `unknown-filter`. */
+    code: string;
+    /** Optional quick-fix: replace the range with `replacement`. */
+    fix?: {
+        title: string;
+        replacement: string;
+    };
+}
+export interface VariableRef {
+    path: string[];
+    range: Range;
+    kind: 'read' | 'loop-var' | 'assigned';
+}
+export interface FilterRef {
+    name: string;
+    range: Range;
+    known: boolean;
+}
+export interface IncludeRef {
+    name: string;
+    range: Range;
+}
+export interface BlockRef {
+    type: 'for' | 'if' | 'block' | 'raw' | 'macro' | 'other';
+    open: Range;
+    close?: Range;
+}
+export interface Analysis {
+    variables: VariableRef[];
+    filters: FilterRef[];
+    includes: IncludeRef[];
+    blocks: BlockRef[];
+    diagnostics: Diagnostic[];
+}
+export interface AnalyzeOptions {
+    /** Sample data; when given, variable paths missing from it produce warnings. */
+    sampleData?: unknown;
+    /** Helper registry that decides which filter names are known. Defaults to the built-in set. */
+    helpers?: HelperRegistry;
+}
+/** Resolves a workspace partial by name to its source; `undefined` when it does not exist. */
+export type PartialResolver = (name: string) => string | undefined;
+export interface RenderLimits {
+    /** Wall-clock budget of one render in milliseconds. */
+    ms: number;
+    /** Maximum size of the rendered HTML in bytes. */
+    outputBytes: number;
+    /** Maximum nesting of includes and extends. */
+    includeDepth: number;
+}
+export interface RenderContext {
+    locale: string;
+    timezone: string;
+    currency: string;
+    partials: PartialResolver;
+    helpers: HelperRegistry;
+    limits: RenderLimits;
+    /** Template-level dictionaries for `t()`: locale → key → text (USP-8). */
+    i18n?: Record<string, Record<string, string>>;
+    /** Base URL for `asset()` (workspace asset root on the CDN). */
+    assetBaseUrl?: string;
+}
+export interface CompileOptions {
+    /** Name used in error messages and as the root include name. */
+    name?: string;
+}
+export interface CompiledTemplate {
+    engine: EngineId;
+    name: string;
+    source: string;
+    render(data: unknown, ctx: RenderContext): Promise<string>;
+}
+export interface Engine {
+    id: EngineId;
+    /** Parses and compiles; throws `EngineSyntaxError` with line and column. */
+    compile(source: string, opts?: CompileOptions): CompiledTemplate;
+    analyze(source: string, opts?: AnalyzeOptions): Analysis;
+    render(tpl: CompiledTemplate, data: unknown, ctx: RenderContext): Promise<string>;
+}
+export type HelperCategory = 'format' | 'text' | 'collection' | 'logic' | 'code' | 'document' | 'debug';
+export interface HelperDoc {
+    signature: string;
+    description: string;
+    example: string;
+    category: HelperCategory;
+}
+export interface HelperDefinition {
+    name: string;
+    /** Other names the helper answers to (apitemplate.io compatibility aliases). */
+    aliases?: string[];
+    /** Result is HTML that must not be escaped by the engine. */
+    html?: boolean;
+    /** Emits a warning diagnostic pointing to the preferred name (deprecated aliases). */
+    deprecatedAlias?: Record<string, string>;
+    doc: HelperDoc;
+    /** Receives the render context first, then the template arguments. */
+    fn: (ctx: HelperContext, ...args: unknown[]) => unknown;
+}
+/** What helpers know about the current render without receiving the whole context. */
+export interface HelperContext {
+    locale: string;
+    timezone: string;
+    currency: string;
+    i18n?: Record<string, Record<string, string>>;
+    assetBaseUrl?: string;
+}
+export interface HelperRegistry {
+    /** Registered helpers keyed by canonical name. */
+    readonly definitions: ReadonlyMap<string, HelperDefinition>;
+    /** Resolves a name or alias. */
+    get(name: string): HelperDefinition | undefined;
+    has(name: string): boolean;
+    /** Every name the engines know, aliases included. */
+    names(): string[];
+    /** Concrete functions bound to a render context, keyed by every name and alias. */
+    bind(ctx: HelperContext): Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        html: boolean;
+    }>;
+    register(definition: HelperDefinition): void;
+}