@broadpaper/forme 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+import { TableRowGeometry, BlockRegistry, Theme, DocumentStyles, FormatContext, RenderMode, ResolvedNode, GeometryMap, VNode, RenderTreeOptions, ReportTemplate, AnyVersionTemplate, ReportData, DataSource, PagedDocument } from '@broadpaper/core';
+import { WatermarkSpec, LicenseStatus } from '@broadpaper/license';
+export { BroadPaper, BroadPaperConfig, Entitlement, LicensePayload, LicenseState, LicenseStatus, configure, parseLicense, resolveLicenseStatus, verifyLicense } from '@broadpaper/license';
+
+/**
+ * Translates the inline CSS our block renderers emit into Forme's style model.
+ *
+ * BroadPaper blocks produce a deliberately small, self-generated CSS vocabulary
+ * (we never accept CSS from users), which is what makes a faithful mapping
+ * possible at all. Anything outside that vocabulary is reported rather than
+ * dropped silently — the caller surfaces it as a validation warning.
+ */
+/** CSS pixels at 96 dpi → PDF points at 72 dpi. */
+declare const PX_TO_PT: number;
+declare function pxToPt(px: number): number;
+interface FormeStyle {
+    [prop: string]: unknown;
+}
+interface StyleTranslation {
+    style: FormeStyle;
+    /** CSS declarations with no Forme equivalent, e.g. "box-shadow". */
+    unsupported: string[];
+}
+/** Parses an inline style string or object into kebab-case declarations. */
+declare function parseDeclarations(style: unknown): Record<string, string>;
+/**
+ * Maps CSS declarations to Forme style props. Returns the props plus any
+ * declaration we could not represent.
+ */
+declare function translateStyle(css: Record<string, string>): StyleTranslation;
+
+/**
+ * Forme as a pure measurer.
+ *
+ * Forme is page-native: given a document it paginates and draws. But given a
+ * page tall enough that nothing can overflow, it becomes a measurement engine —
+ * it returns the laid-out tree with a box for every node, a `TextLine` per line
+ * of wrapped text and a `TableRow` per row. That is exactly the geometry our own
+ * paginator consumes, so BroadPaper keeps every pagination decision (keep
+ * together, keep with next, orphans and widows, repeated table headers, page
+ * breaks, splitting multi-column rows) while no browser is involved anywhere.
+ *
+ * Correlating engine output back to BroadPaper nodes is done structurally: the
+ * translator records an annotation tree in lockstep with the nodes it emits, and
+ * the layout tree comes back with the same shape (leaf `Text` nodes merely gain
+ * `TextLine` children, which appends rather than reorders).
+ */
+
+/** Mirrors an emitted node, carrying what we need to map geometry back. */
+interface Annotation {
+    /** BroadPaper node key, when this node is a block wrapper. */
+    key?: string;
+    /** This node's subtree holds wrapped text whose line boxes we want. */
+    text?: boolean;
+    /** Row roles in emission order, for table nodes. */
+    rowKinds?: Array<TableRowGeometry["kind"]>;
+    children: Annotation[];
+}
+/** A layout element as returned by Forme. */
+interface LayoutElement {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    nodeType: string;
+    textContent?: string | null;
+    children?: LayoutElement[];
+}
+interface LayoutPage {
+    width: number;
+    height: number;
+    elements: LayoutElement[];
+}
+/** Height of the measurement page. Tall enough that nothing paginates. */
+declare const UNBOUNDED_PAGE_HEIGHT = 200000;
+interface MeasuredSection {
+    section: ResolvedNode;
+    node: FormeNode;
+    ann: Annotation;
+}
+/**
+ * Builds the geometry map our paginator expects from Forme's layout of an
+ * unbounded page. `pageElements` are the top-level elements of that page, in the
+ * same order as `sections`.
+ */
+declare function geometryFromLayout(sections: MeasuredSection[], pageElements: LayoutElement[], width: number): GeometryMap;
+
+interface FormeRenderer {
+    (doc: Record<string, unknown>): Promise<{
+        pdf: Uint8Array;
+        layout?: unknown;
+        warnings?: string[];
+    }>;
+}
+interface FormeMeasurerOptions {
+    registry: BlockRegistry;
+    theme: Theme;
+    styles: DocumentStyles;
+    format: FormatContext;
+    mode?: RenderMode;
+    /** Page width in CSS pixels, used for the measurement page. */
+    pageWidth: number;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    fonts?: unknown[];
+    /** Injected so the caller picks the Forme entry point (node, browser, worker). */
+    render: FormeRenderer;
+}
+/**
+ * Measures resolved sections with Forme, returning geometry in CSS pixels — the
+ * same shape `DomMeasurer` produces, so the paginator and the editor cannot tell
+ * which one measured.
+ */
+declare class FormeMeasurer {
+    private readonly opts;
+    readonly warnings: Set<string>;
+    constructor(opts: FormeMeasurerOptions);
+    private renderOptions;
+    get contentWidth(): number;
+    measure(sections: ResolvedNode[], width?: number): Promise<GeometryMap>;
+}
+
+/**
+ * VNode → Forme document node.
+ *
+ * Block renderers (built-in and custom alike) return a VNode tree, so a single
+ * translator gives every block a browserless PDF path for free — no block has
+ * to know Forme exists.
+ *
+ * Alongside each emitted node the translator records an `Annotation` in exactly
+ * the same shape. That is what lets `measure.ts` map Forme's layout result back
+ * onto BroadPaper node keys without the engine needing to carry our identifiers.
+ */
+
+interface FormeNode {
+    kind: Record<string, unknown>;
+    style: FormeStyle;
+    children: FormeNode[];
+    href?: string;
+    alt?: string;
+}
+interface TranslateContext {
+    warnings: Set<string>;
+    /**
+     * Keeps design-mode affordances — placeholders, empty-slot outlines, the
+     * page-break rule. They never belong in a PDF, but when this translation is
+     * measuring the editor's canvas they are part of what the canvas draws, and
+     * measuring them as nothing makes blocks invisible on screen.
+     */
+    design?: boolean;
+    /**
+     * Drops page-break nodes, for the passes where BroadPaper has already decided
+     * the pages. Measurement uses one unbounded page and reads back only its
+     * first, so a break there would silently discard everything after it; the
+     * paginated draw pass has placed its content already and must not reflow.
+     */
+    suppressPageBreaks?: boolean;
+}
+/** An emitted node paired with its annotation. */
+interface Translated {
+    node: FormeNode;
+    ann: Annotation;
+}
+/** Translates one VNode, returning the emitted node and its annotation. */
+declare function translate(v: VNode, ctx: TranslateContext): Translated | null;
+/** Translates one VNode. Returns null for nodes that draw nothing. */
+declare function vnodeToForme(v: VNode, ctx: TranslateContext): FormeNode | null;
+
+declare function watermarkNode(spec: WatermarkSpec): FormeNode;
+
+/**
+ * Forme as the editor's measurer.
+ *
+ * The canvas normally measures in the browser, which is immediate and free.
+ * That is the right default, but it means the editor and the PDF are laid out
+ * by two different engines, and where they disagree a page breaks in one place
+ * on screen and another in the file. Measuring the canvas with the same engine
+ * that renders the PDF removes the disagreement entirely: a break you see is a
+ * break you get.
+ *
+ * The engine is injected rather than imported so this module stays neutral
+ * about which Forme entry point the host uses — browser, worker or node.
+ */
+
+interface FormeEditorMeasurerOptions {
+    /** The engine call, e.g. `renderSerializedDocWithLayout` from `@formepdf/core/browser`. */
+    render: FormeRenderer;
+    /** Font files the engine should use, matching the theme's families. */
+    fonts?: unknown[];
+    /** Called for every distinct translation warning, once. */
+    onWarning?(message: string): void;
+}
+/**
+ * Measures resolved sections with Forme, caching by section content.
+ *
+ * Engine measurement is far slower than reading the DOM, so an edit must not
+ * re-measure the whole document. Only sections whose content actually changed
+ * are sent, and they go in one call rather than one call each.
+ */
+declare class FormeEditorMeasurer {
+    private readonly config;
+    private opts;
+    private readonly cache;
+    private readonly seen;
+    constructor(config: FormeEditorMeasurerOptions);
+    setOptions(opts: RenderTreeOptions): void;
+    clearCache(): void;
+    destroy(): void;
+    private key;
+    measure(sections: ResolvedNode[], width: number): Promise<GeometryMap>;
+}
+
+/**
+ * @broadpaper/forme — browserless PDF output.
+ *
+ * The Chromium backend (`@broadpaper/pdf`) prints a document BroadPaper has
+ * already paginated. This backend instead hands Forme the flowing content and
+ * lets its page-native Rust/WASM engine paginate and draw: no browser, no
+ * native dependencies, runs in Node, edge runtimes and the browser.
+ *
+ * The trade-off is explicit: pagination decisions move from BroadPaper's
+ * paginator to Forme's, so the editor's on-screen page breaks are an
+ * approximation of this output until the editor is switched to the same engine.
+ * `renderPdf` returns Forme's own page geometry so callers can compare.
+ */
+
+interface FormeFont {
+    family: string;
+    /** TTF/OTF bytes, a data: URI, or a filesystem path (Node only). */
+    src: string | Uint8Array;
+    weight?: number;
+    style?: "normal" | "italic";
+}
+interface RenderFormePdfOptions {
+    template: ReportTemplate | AnyVersionTemplate;
+    registry: BlockRegistry;
+    data?: ReportData;
+    theme?: Partial<Theme>;
+    dataSources?: DataSource[];
+    now?: Date;
+    locale?: string;
+    currency?: string;
+    timeZone?: string;
+    metadata?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        creator?: string;
+        lang?: string;
+    };
+    /** Fonts to embed. Without these Forme falls back to its standard faces. */
+    fonts?: FormeFont[];
+    /** Emit a tagged (accessible) PDF. */
+    tagged?: boolean;
+    /** PDF/UA-1 conformance. Requires an embeddable font. */
+    pdfUa?: boolean;
+    /** PDF/A conformance level. */
+    pdfA?: "2b" | "2u" | "2a" | "3b" | "3u" | "3a";
+    /**
+     * A licence for this render only, overriding whatever `configure` was given.
+     *
+     * Almost nothing should need it: a process renders under one licence, and
+     * setting it once at startup is both less code and impossible to forget on
+     * one export path. It exists for a multi-tenant host that renders on behalf
+     * of several licensed organisations from one process.
+     */
+    license?: string | null;
+    /**
+     * Injected renderer, so the caller controls which Forme entry point is used
+     * (`@formepdf/core`, `/browser`, or `/worker`). Defaults to a dynamic import
+     * of `@formepdf/core`.
+     */
+    renderer?: (doc: Record<string, unknown>) => Promise<{
+        pdf: Uint8Array;
+        layout?: unknown;
+        warnings?: string[];
+    }>;
+}
+interface FormePageInfo {
+    width: number;
+    height: number;
+    contentWidth: number;
+    contentHeight: number;
+    elements: unknown[];
+}
+interface RenderFormePdfResult {
+    pdf: Uint8Array;
+    pages: number;
+    /** Forme's own layout geometry — the basis for driving an editor from this engine. */
+    layout: {
+        pages: FormePageInfo[];
+    } | null;
+    /** Everything BroadPaper could not translate, plus everything Forme flagged. */
+    warnings: string[];
+    durationMs: number;
+}
+/**
+ * Builds the Forme document JSON for a resolved BroadPaper document.
+ *
+ * Asynchronous only because it checks the licence, which it does itself rather
+ * than taking a "watermark this" flag from its caller. Every route to a
+ * BroadPaper PDF through this engine passes through here or through
+ * `emitPages`, and a document built without the evaluation mark is a clean
+ * unlicensed PDF — so the decision is made where the document is assembled and
+ * nowhere else.
+ */
+declare function buildFormeDocument(opts: Omit<RenderFormePdfOptions, "renderer">): Promise<{
+    doc: Record<string, unknown>;
+    warnings: string[];
+    license: LicenseStatus;
+}>;
+/**
+ * How this package reaches the engine when the caller injects no `renderer`.
+ *
+ * It is set by the entry point rather than imported here, because the two
+ * runtimes need different Forme builds and a browser bundler must never even
+ * see the other one. `@formepdf/core`'s default browser build is the
+ * wasm-pack *bundler* target, whose `import * as wasm from "./forme_bg.wasm"`
+ * Angular's builder rejects outright ("WASM/ES module integration imports are
+ * not supported with Zone.js applications") — so a single bare import here
+ * obliged every Angular host to go zoneless to use us at all. That is a
+ * decision about the host's change detection, and a reporting SDK has no
+ * business making it.
+ *
+ * `src/index.ts` installs the Node loader, `src/index.browser.ts` the browser
+ * one, and the `browser` condition in this package's exports picks between
+ * them. Neither bundle contains the other's import.
+ */
+type EngineLoader = () => Promise<(doc: Record<string, unknown>) => Promise<{
+    pdf: Uint8Array;
+    layout?: unknown;
+    warnings?: string[];
+}>>;
+/**
+ * Installs the engine used when no `renderer` is passed. Each entry point calls
+ * this for its own runtime, which is all most hosts need; it is exported
+ * because a host that reaches Forme some third way — a shared worker, a
+ * pre-instantiated module, a pooled engine — has somewhere to say so once
+ * rather than on every call.
+ */
+declare function setEngineLoader(loader: EngineLoader): void;
+/** Renders a BroadPaper template to PDF with no browser involved. */
+declare function renderPdf(opts: RenderFormePdfOptions): Promise<RenderFormePdfResult>;
+
+interface RenderPaginatedResult extends RenderFormePdfResult {
+    /** The pages BroadPaper's own paginator decided. */
+    paged: PagedDocument;
+    /** Geometry measured by the engine, keyed by section. */
+    geometry: GeometryMap;
+}
+/**
+ * Renders with **BroadPaper owning pagination** and Forme acting only as a
+ * measurer and a draw target — no browser, and every page-break rule
+ * (keep together, keep with next, orphans and widows, repeated table headers,
+ * explicit breaks, splitting multi-column rows) still comes from our paginator.
+ *
+ * Two passes through the engine: one onto a page tall enough that nothing can
+ * overflow, which yields a box for every node, line and table row; then one that
+ * draws the pages our paginator produced. Both passes lay text out with the same
+ * engine at the same width, so the second cannot re-break what the first
+ * measured.
+ */
+declare function renderPdfPaginated(opts: RenderFormePdfOptions): Promise<RenderPaginatedResult>;
+
+export { type Annotation, type EngineLoader, FormeEditorMeasurer, type FormeEditorMeasurerOptions, type FormeFont, FormeMeasurer, type FormeMeasurerOptions, type FormeNode, type FormePageInfo, type FormeRenderer, type LayoutElement, type LayoutPage, PX_TO_PT, type RenderFormePdfOptions, type RenderFormePdfResult, type RenderPaginatedResult, type TranslateContext, type Translated, UNBOUNDED_PAGE_HEIGHT, buildFormeDocument, geometryFromLayout, parseDeclarations, pxToPt, renderPdf, renderPdfPaginated, setEngineLoader, translate, translateStyle, vnodeToForme, watermarkNode };

package/dist/index.js

@@ -0,0 +1,54 @@
+import {
+  BroadPaper,
+  FormeEditorMeasurer,
+  FormeMeasurer,
+  PX_TO_PT,
+  UNBOUNDED_PAGE_HEIGHT,
+  buildFormeDocument,
+  configure,
+  geometryFromLayout,
+  parseDeclarations,
+  parseLicense,
+  pxToPt,
+  renderPdf,
+  renderPdfPaginated,
+  resolveLicenseStatus,
+  setEngineLoader,
+  translate,
+  translateStyle,
+  verifyLicense,
+  vnodeToForme,
+  watermarkNode
+} from "./chunk-KE7FFMY2.js";
+
+// src/engine.node.ts
+var loadEngine = async () => {
+  const mod = await import("@formepdf/core");
+  return (doc) => mod.renderSerializedDocWithLayout(doc);
+};
+
+// src/index.ts
+setEngineLoader(loadEngine);
+export {
+  BroadPaper,
+  FormeEditorMeasurer,
+  FormeMeasurer,
+  PX_TO_PT,
+  UNBOUNDED_PAGE_HEIGHT,
+  buildFormeDocument,
+  configure,
+  geometryFromLayout,
+  parseDeclarations,
+  parseLicense,
+  pxToPt,
+  renderPdf,
+  renderPdfPaginated,
+  resolveLicenseStatus,
+  setEngineLoader,
+  translate,
+  translateStyle,
+  verifyLicense,
+  vnodeToForme,
+  watermarkNode
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.node.ts","../src/index.ts"],"sourcesContent":["/**\n * The engine as Node, Bun, Deno and edge runtimes get it.\n *\n * `@formepdf/core`'s own conditional exports pick the right build for the\n * runtime resolving it, so the bare specifier is the correct one here — this\n * module is only ever in a graph that is not a browser's.\n */\nimport type { EngineLoader } from \"./api.js\";\n\nexport const loadEngine: EngineLoader = async () => {\n  const mod = (await import(\"@formepdf/core\")) as unknown as {\n    renderSerializedDocWithLayout(d: Record<string, unknown>): Promise<{ pdf: Uint8Array; layout: unknown; warnings: string[] }>;\n  };\n  return (doc) => mod.renderSerializedDocWithLayout(doc);\n};\n","/**\n * @broadpaper/forme — the browserless PDF backend, for Node and every other\n * non-browser runtime. Browser bundlers resolve `./index.browser.ts` instead,\n * through the `browser` condition in this package's exports.\n */\nimport { setEngineLoader } from \"./api.js\";\nimport { loadEngine } from \"./engine.node.js\";\n\nsetEngineLoader(loadEngine);\n\nexport * from \"./api.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AASO,IAAM,aAA2B,YAAY;AAClD,QAAM,MAAO,MAAM,OAAO,gBAAgB;AAG1C,SAAO,CAAC,QAAQ,IAAI,8BAA8B,GAAG;AACvD;;;ACNA,gBAAgB,UAAU;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@broadpaper/forme",
+  "version": "0.1.1",
+  "description": "Browserless PDF backend for BroadPaper, built on the Forme (Rust/WASM) engine. Runs in Node, edge runtimes and the browser.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "import": "./dist/index.browser.js"
+      },
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/index.browser.js"
+  ],
+  "dependencies": {
+    "@formepdf/core": "^0.20.0",
+    "@formepdf/shared": "^0.20.0",
+    "@broadpaper/blocks": "0.1.1",
+    "@broadpaper/core": "0.1.1",
+    "@broadpaper/license": "0.1.1"
+  },
+  "browser": "./dist/index.browser.js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}