@broadpaper/forme 0.3.0 → 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.
  *
@@ -190,12 +262,13 @@ interface FormeEditorMeasurerOptions {
     /** The engine call, e.g. `renderSerializedDocWithLayout` from `@formepdf/core/browser`. */
     render: FormeRenderer;
     /**
-     * Font files the engine should use, matching the families the document names.
+     * Fonts for the engine beyond the theme's own.
      *
-     * 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.
+     * 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. */
@@ -219,6 +292,7 @@ declare class FormeEditorMeasurer {
     destroy(): void;
     private key;
     measure(sections: ResolvedNode[], width: number): Promise<GeometryMap>;
+    private warn;
 }
 
 /**
@@ -235,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;
@@ -259,8 +326,16 @@ 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. */
@@ -431,4 +506,4 @@ interface PaginatedLayout {
  */
 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, type LayoutPaginatedOptions, MEASURE_BATCH_ROWS, PX_TO_PT, type PaginatedLayout, type RenderFormePdfOptions, type RenderFormePdfResult, type RenderPaginatedResult, type TranslateContext, type Translated, UNBOUNDED_PAGE_HEIGHT, buildFormeDocument, geometryFromLayout, layoutPaginated, 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

@@ -14,16 +14,22 @@ import {
   pxToPt,
   renderPdf,
   renderPdfPaginated,
+  resolveFonts,
   resolveLicenseStatus,
   setEngineLoader,
+  setFontFileReader,
   translate,
   translateStyle,
   verifyLicense,
   vnodeToForme,
   watermarkNode
-} from "./chunk-2C3MAW2U.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);
@@ -31,6 +37,7 @@ var loadEngine = async () => {
 
 // src/index.ts
 setEngineLoader(loadEngine);
+setFontFileReader(readFontFile);
 export {
   BroadPaper,
   FormeEditorMeasurer,
@@ -47,8 +54,10 @@ export {
   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.3.0",
+  "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/core": "0.3.0",
-    "@broadpaper/blocks": "0.3.0",
-    "@broadpaper/license": "0.3.0"
+    "@broadpaper/core": "0.4.0",
+    "@broadpaper/license": "0.4.0",
+    "@broadpaper/blocks": "0.4.0"
   },
   "browser": "./dist/index.browser.js",
   "scripts": {