@broadpaper/forme 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -172,6 +172,78 @@ declare function vnodeToForme(v: VNode, ctx: TranslateContext): FormeNode | null
 
 declare function watermarkNode(spec: WatermarkSpec): FormeNode;
 
+/**
+ * The theme's fonts, made into fonts the engine can embed.
+ *
+ * A host declares a font once, in `theme.fonts`. The browser has always read that
+ * declaration — `@font-face` rules on the canvas, the designer's font pickers, the
+ * validator, the Chromium backend — and this engine did not: it took a separate
+ * `fonts` option, so a font declared only in the theme was drawn on screen and
+ * measured and printed in the standard faces. Nothing said so, and the symptom was
+ * a canvas whose sections overlapped and a PDF whose lines broke somewhere else.
+ *
+ * Three things stand between a `@font-face` declaration and the engine.
+ *
+ * **Format.** The engine parses TrueType and OpenType and nothing else; there is no
+ * WOFF decoder in it. A face often lists a WOFF2 for the browser beside a TTF, so
+ * the first source the engine can read is the one it gets, and a WOFF is skipped by
+ * its name before anything is downloaded. What is downloaded is checked by its
+ * first four bytes, not its extension. A face with nothing readable is a warning,
+ * because the alternative is exactly the silence described above.
+ *
+ * **Where it comes from.** A theme is the host's own code in the SDK and a JSON body
+ * from a stranger in the render service, so the service narrows `FontSourcePolicy`
+ * to its allowed hosts and to no files at all. The SDK default is to trust the
+ * theme, as it trusts the template.
+ *
+ * **Doing it once.** The engine resolves a font by rewriting its entry in place,
+ * and re-reads anything that is not a `data:` URI on every render. Every source is
+ * therefore resolved here, once per address, to a `data:` URI the engine passes
+ * straight through.
+ */
+
+interface FormeFont {
+    family: string;
+    /** TTF/OTF bytes, a data: URI, or a filesystem path (Node only). */
+    src: string | Uint8Array;
+    weight?: number;
+    style?: "normal" | "italic";
+}
+/** Where the theme's fonts may be read from. */
+interface FontSourcePolicy {
+    /** Hosts an `http(s)` font may be fetched from; `"*"` for any. Unset means any. */
+    allowedHosts?: string[];
+    /**
+     * Whether a source that is neither `data:` nor `http(s)` may be read — a file in
+     * Node, an address relative to the page in a browser. Default true.
+     */
+    local?: boolean;
+}
+/** Reads a source that is neither `data:` nor `http(s)`. Installed by each entry point. */
+type FontFileReader = (src: string) => Promise<Uint8Array>;
+/**
+ * Installs the reader for local sources. `src/index.ts` reads files and
+ * `src/index.browser.ts` fetches relative to the page, and neither bundle contains
+ * the other's — the same arrangement as `setEngineLoader`.
+ */
+declare function setFontFileReader(reader: FontFileReader): void;
+interface ResolvedFonts {
+    fonts: FormeFont[];
+    warnings: string[];
+}
+/**
+ * The fonts to hand the engine: the caller's own `fonts` first, exactly as given,
+ * then every face in the theme the engine can read.
+ *
+ * The first entry for a family, weight and style wins, so an explicit font — or a
+ * service's own — is never displaced by a theme naming the same face.
+ */
+declare function resolveFonts(input: {
+    fonts?: FormeFont[];
+    theme?: Partial<Theme>;
+    sources?: FontSourcePolicy;
+}): Promise<ResolvedFonts>;
+
 /**
  * Forme as the editor's measurer.
  *
@@ -189,8 +261,16 @@ declare function watermarkNode(spec: WatermarkSpec): FormeNode;
 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[];
+    /**
+     * Fonts for the engine beyond the theme's own.
+     *
+     * Usually unnecessary: the faces in `theme.fonts` are read and given to the
+     * engine without being named here. May be a promise, because a browser host has
+     * to fetch the files and `createMeasurer` has to return synchronously. Every
+     * measurement waits for it, so nothing is ever measured — and cached — with the
+     * engine's standard faces standing in for a font that was still arriving.
+     */
+    fonts?: unknown[] | Promise<unknown[]>;
     /** Called for every distinct translation warning, once. */
     onWarning?(message: string): void;
 }
@@ -212,6 +292,7 @@ declare class FormeEditorMeasurer {
     destroy(): void;
     private key;
     measure(sections: ResolvedNode[], width: number): Promise<GeometryMap>;
+    private warn;
 }
 
 /**
@@ -228,13 +309,6 @@ declare class FormeEditorMeasurer {
  * `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;
@@ -252,14 +326,37 @@ interface RenderFormePdfOptions {
         creator?: string;
         lang?: string;
     };
-    /** Fonts to embed. Without these Forme falls back to its standard faces. */
+    /**
+     * Fonts handed to the engine as they are, before the theme's.
+     *
+     * Most hosts need none: every face in `theme.fonts` with a TrueType or OpenType
+     * source is embedded without being named twice. This is for a font the theme
+     * does not declare — one a service embeds in every render, say.
+     */
     fonts?: FormeFont[];
+    /** Where the theme's fonts may be read from. Unset, anywhere: a host's own theme is trusted. */
+    fontSources?: FontSourcePolicy;
     /** 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";
+    /**
+     * An extra mark to draw behind every page, on top of whatever the licence
+     * decides.
+     *
+     * Additive and never a replacement: the licence mark is decided by
+     * `watermarkFor` and this cannot remove it, which is the property that keeps
+     * "a caller cannot reach a PDF without passing the licence check" true. It
+     * exists for a host whose own commercial model wants a mark — BroadPaper Cloud
+     * marks the documents its free plan produces — and for the ordinary "DRAFT"
+     * stamp a business document sometimes needs.
+     *
+     * Remember that an unstyled Forme watermark draws solid black at full opacity;
+     * a spec without a colour and an opacity makes the document unreadable.
+     */
+    watermark?: WatermarkSpec | null;
     /**
      * A licence for this render only, overriding whatever `configure` was given.
      *
@@ -364,6 +461,49 @@ interface RenderPaginatedResult extends RenderFormePdfResult {
  * engine at the same width, so the second cannot re-break what the first
  * measured.
  */
-declare function renderPdfPaginated(opts: RenderFormePdfOptions): Promise<RenderPaginatedResult>;
+declare function renderPdfPaginated(opts: LayoutPaginatedOptions): Promise<RenderPaginatedResult>;
+/** A table longer than this many body rows is measured a batch at a time. */
+declare const MEASURE_BATCH_ROWS = 1000;
+interface LayoutPaginatedOptions extends RenderFormePdfOptions {
+    /**
+     * Body rows per measuring pass for a long table. Only a test should change it:
+     * a small number exercises the batching on a table short enough to compare with
+     * measuring it whole.
+     */
+    measureBatchRows?: number;
+}
+/** A document laid out and paginated, and not yet drawn. */
+interface PaginatedLayout {
+    /** The pages BroadPaper's own paginator decided. */
+    paged: PagedDocument;
+    /** Geometry measured by the engine, keyed by section. */
+    geometry: GeometryMap;
+    /**
+     * Draws pages `[from, to)` — the whole document when no range is given — as one
+     * PDF. Pages keep their numbers in the whole document, so page 251 of a split
+     * document still says "251 of 1,300".
+     */
+    draw(range?: {
+        from: number;
+        to: number;
+    }): Promise<{
+        pdf: Uint8Array;
+        pages: number;
+        layout: {
+            pages: FormePageInfo[];
+        } | null;
+        warnings: string[];
+    }>;
+}
+/**
+ * Resolves, measures and paginates without drawing.
+ *
+ * Separate from drawing for two reasons a long document made plain. The page
+ * count is known here, before the more expensive half of the work, so a caller
+ * with a ceiling can refuse or split first rather than after; and a document of
+ * a thousand pages can be drawn as several files from one layout, every one of
+ * them agreeing about where the page breaks fall and what the totals are.
+ */
+declare function layoutPaginated(opts: LayoutPaginatedOptions): Promise<PaginatedLayout>;
 
-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 };
+export { type Annotation, type EngineLoader, type FontFileReader, type FontSourcePolicy, FormeEditorMeasurer, type FormeEditorMeasurerOptions, type FormeFont, FormeMeasurer, type FormeMeasurerOptions, type FormeNode, type FormePageInfo, type FormeRenderer, type LayoutElement, type LayoutPage, type LayoutPaginatedOptions, MEASURE_BATCH_ROWS, PX_TO_PT, type PaginatedLayout, type RenderFormePdfOptions, type RenderFormePdfResult, type RenderPaginatedResult, type ResolvedFonts, type TranslateContext, type Translated, UNBOUNDED_PAGE_HEIGHT, buildFormeDocument, geometryFromLayout, layoutPaginated, parseDeclarations, pxToPt, renderPdf, renderPdfPaginated, resolveFonts, setEngineLoader, setFontFileReader, translate, translateStyle, vnodeToForme, watermarkNode };

package/dist/index.js

@@ -2,26 +2,34 @@ import {
   BroadPaper,
   FormeEditorMeasurer,
   FormeMeasurer,
+  MEASURE_BATCH_ROWS,
   PX_TO_PT,
   UNBOUNDED_PAGE_HEIGHT,
   buildFormeDocument,
   configure,
   geometryFromLayout,
+  layoutPaginated,
   parseDeclarations,
   parseLicense,
   pxToPt,
   renderPdf,
   renderPdfPaginated,
+  resolveFonts,
   resolveLicenseStatus,
   setEngineLoader,
+  setFontFileReader,
   translate,
   translateStyle,
   verifyLicense,
   vnodeToForme,
   watermarkNode
-} from "./chunk-2PT5WRKQ.js";
+} from "./chunk-QA4APTWM.js";
 
 // src/engine.node.ts
+var readFontFile = async (path) => {
+  const { readFile } = await import("fs/promises");
+  return new Uint8Array(await readFile(path));
+};
 var loadEngine = async () => {
   const mod = await import("@formepdf/core");
   return (doc) => mod.renderSerializedDocWithLayout(doc);
@@ -29,22 +37,27 @@ var loadEngine = async () => {
 
 // src/index.ts
 setEngineLoader(loadEngine);
+setFontFileReader(readFontFile);
 export {
   BroadPaper,
   FormeEditorMeasurer,
   FormeMeasurer,
+  MEASURE_BATCH_ROWS,
   PX_TO_PT,
   UNBOUNDED_PAGE_HEIGHT,
   buildFormeDocument,
   configure,
   geometryFromLayout,
+  layoutPaginated,
   parseDeclarations,
   parseLicense,
   pxToPt,
   renderPdf,
   renderPdfPaginated,
+  resolveFonts,
   resolveLicenseStatus,
   setEngineLoader,
+  setFontFileReader,
   translate,
   translateStyle,
   verifyLicense,

package/dist/index.js.map

@@ -1 +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":[]}
+{"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\";\nimport type { FontFileReader } from \"./fonts.js\";\n\n/** A theme font that is not a data: URI or a web address is a file, as the engine itself reads one. */\nexport const readFontFile: FontFileReader = async (path) => {\n  const { readFile } = await import(\"node:fs/promises\");\n  return new Uint8Array(await readFile(path));\n};\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, setFontFileReader } from \"./api.js\";\nimport { loadEngine, readFontFile } from \"./engine.node.js\";\n\nsetEngineLoader(loadEngine);\nsetFontFileReader(readFontFile);\n\nexport * from \"./api.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWO,IAAM,eAA+B,OAAO,SAAS;AAC1D,QAAM,EAAE,SAAS,IAAI,MAAM,OAAO,aAAkB;AACpD,SAAO,IAAI,WAAW,MAAM,SAAS,IAAI,CAAC;AAC5C;AAEO,IAAM,aAA2B,YAAY;AAClD,QAAM,MAAO,MAAM,OAAO,gBAAgB;AAG1C,SAAO,CAAC,QAAQ,IAAI,8BAA8B,GAAG;AACvD;;;ACbA,gBAAgB,UAAU;AAC1B,kBAAkB,YAAY;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broadpaper/forme",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Browserless PDF backend for BroadPaper, built on the Forme (Rust/WASM) engine. Runs in Node, edge runtimes and the browser.",
   "keywords": [
     "pdf",
@@ -50,9 +50,9 @@
   "dependencies": {
     "@formepdf/core": "^0.20.0",
     "@formepdf/shared": "^0.20.0",
-    "@broadpaper/blocks": "0.2.1",
-    "@broadpaper/core": "0.2.1",
-    "@broadpaper/license": "0.2.1"
+    "@broadpaper/core": "0.4.0",
+    "@broadpaper/license": "0.4.0",
+    "@broadpaper/blocks": "0.4.0"
   },
   "browser": "./dist/index.browser.js",
   "scripts": {