💥 Remove support for fonts in document definition

`FontStore` parsed each font twice: once in `registerFont()` to extract
metadata, and again in `_loadFont()` when actually selecting a font.
Additionally, a stale TODO comment remained from the pdf-core migration,
and the deprecated `fonts` property in the document definition was still
supported.

Store the `PDFEmbeddedFont` created during `registerFont()` in `FontDef`
so that `_loadFont()` can reuse it. Remove the `fonts` property from
`DocumentDefinition`, along with `readFonts`, `readFont`,
`FontsDefinition`, `FontDefinition`, and the `FontStore` constructor
parameter. Update font-store tests to use `registerFont()` with explicit
config instead of pre-built `FontDef` arrays.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ralfstx

CHANGELOG.md

@@ -18,6 +18,10 @@
   referred to by URL instead. The `ImagesDefinition` and
   `ImageDefinition` types have been removed.
 
+- The `fonts` property in the document definition. Fonts must now be
+  registered with `PdfMaker.registerFont()`. The `FontsDefinition` and
+  `FontDefinition` types have been removed.
+
 ### Breaking
 
 - Text height is now based on the OS/2 typographic metrics

src/api/PdfMaker.ts

@@ -55,14 +55,10 @@ export class PdfMaker {
    */
   async makePdf(definition: DocumentDefinition): Promise<Uint8Array> {
     const def = readAs(definition, 'definition', readDocumentDefinition);
-    let fontStore = this.#fontStore;
-    if (def.fonts) {
-      fontStore = new FontStore(def.fonts);
-      console.warn(
-        'Registering fonts via document definition is deprecated. Use PdfMaker.registerFont() instead.',
-      );
-    }
-    const ctx: MakerCtx = { fontStore, imageLoader: createImageLoader(this.#resourceRoot) };
+    const ctx: MakerCtx = {
+      fontStore: this.#fontStore,
+      imageLoader: createImageLoader(this.#resourceRoot),
+    };
     if (def.dev?.guides != null) ctx.guides = def.dev.guides;
     const pages = await layoutPages(def, ctx);
     return await renderDocument(def, pages);

src/api/document.ts

@@ -51,14 +51,6 @@ export type DocumentDefinition = {
    */
   margin?: Length | BoxLengths | ((info: PageInfo) => Length | BoxLengths);
 
-  /**
-   * The fonts to use in the document. There is no default. Each font that is used in the document
-   * must be registered. Not needed for documents that contain only graphics.
-   *
-   * @deprecated Register fonts with `PdfMaker` instead.
-   */
-  fonts?: FontsDefinition;
-
   /**
    * Metadata to include in the PDF's *document information dictionary*.
    */
@@ -215,38 +207,6 @@ export type CustomInfoAttrs = CustomInfoProps;
  */
 export type CustomInfoProps = Record<`XX${string}`, string>;
 
-/**
- * An object that defines the fonts to use in the document.
- *
- * @deprecated Register fonts with `PdfMaker` instead.
- */
-export type FontsDefinition = { [name: string]: FontDefinition[] };
-
-/**
- * The definition of a single font.
- *
- * @deprecated Register fonts with `PdfMaker` instead.
- */
-export type FontDefinition = {
-  /**
-   * The font data as a Uint8Array.
-   *
-   * Supports TrueType font files (`.ttf`) and OpenType (`.otf`) font
-   * files with TrueType outlines.
-   */
-  data: Uint8Array;
-
-  /**
-   * Whether this is a bold font.
-   */
-  bold?: boolean;
-
-  /**
-   * Whether this is an italic font.
-   */
-  italic?: boolean;
-};
-
 /**
  * Information about the current page, provided to functions that create
  * page-specific headers, footers, and margins.

src/font-store.test.ts

@@ -5,7 +5,6 @@ import type { PDFEmbeddedFont } from '@ralfstx/pdf-core';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { FontStore } from './font-store.ts';
-import type { FontDef } from './fonts.ts';
 import { mkData } from './test/test-utils.ts';
 
 vi.mock('@ralfstx/pdf-core', async (importOriginal) => {
@@ -39,14 +38,6 @@ vi.mock('@ralfstx/pdf-core', async (importOriginal) => {
 });
 
 describe('FontStore', () => {
-  let normalFont: FontDef;
-  let italicFont: FontDef;
-  let obliqueFont: FontDef;
-  let boldFont: FontDef;
-  let italicBoldFont: FontDef;
-  let obliqueBoldFont: FontDef;
-  let otherFont: FontDef;
-
   describe('registerFont', () => {
     let robotoRegular: Uint8Array;
     let robotoLightItalic: Uint8Array;
@@ -93,23 +84,7 @@ describe('FontStore', () => {
     let store: FontStore;
 
     beforeEach(() => {
-      normalFont = fakeFontDef('Test');
-      italicFont = fakeFontDef('Test', { style: 'italic' });
-      obliqueFont = fakeFontDef('Test', { style: 'oblique' });
-      boldFont = fakeFontDef('Test', { weight: 700 });
-      italicBoldFont = fakeFontDef('Test', { style: 'italic', weight: 700 });
-      obliqueBoldFont = fakeFontDef('Test', { style: 'oblique', weight: 700 });
-      otherFont = fakeFontDef('Other');
-
-      store = new FontStore([
-        normalFont,
-        italicFont,
-        obliqueFont,
-        boldFont,
-        italicBoldFont,
-        obliqueBoldFont,
-        otherFont,
-      ]);
+      store = createTestStore();
     });
 
     afterEach(() => {
@@ -137,7 +112,9 @@ describe('FontStore', () => {
     });
 
     it('rejects when no matching font style can be found', async () => {
-      store = new FontStore([normalFont, boldFont]);
+      const store = new FontStore();
+      registerFakeFont(store, 'Test');
+      registerFakeFont(store, 'Test', { weight: 700 });
 
       await expect(store.selectFont({ fontFamily: 'Test', fontStyle: 'italic' })).rejects.toThrow(
         new Error("Could not load font for 'Test', style=italic, weight=normal", {
@@ -181,15 +158,23 @@ describe('FontStore', () => {
     });
 
     it('falls back to oblique when no italic font can be found', async () => {
-      store = new FontStore([normalFont, obliqueFont, boldFont, obliqueBoldFont]);
+      const store = new FontStore();
+      registerFakeFont(store, 'Test');
+      registerFakeFont(store, 'Test', { style: 'oblique' });
+      registerFakeFont(store, 'Test', { weight: 700 });
+      registerFakeFont(store, 'Test', { style: 'oblique', weight: 700 });
 
       await expect(store.selectFont({ fontFamily: 'Test', fontStyle: 'italic' })).resolves.toEqual(
         expect.objectContaining({ name: 'MockFont:Test:oblique:400' }),
       );
     });
 
     it('falls back to italic when no oblique font can be found', async () => {
-      store = new FontStore([normalFont, italicFont, boldFont, italicBoldFont]);
+      const store = new FontStore();
+      registerFakeFont(store, 'Test');
+      registerFakeFont(store, 'Test', { style: 'italic' });
+      registerFakeFont(store, 'Test', { weight: 700 });
+      registerFakeFont(store, 'Test', { style: 'italic', weight: 700 });
 
       const font = await store.selectFont({ fontFamily: 'Test', fontStyle: 'italic' });
 
@@ -228,9 +213,25 @@ describe('FontStore', () => {
   });
 });
 
-function fakeFontDef(family: string, options?: Partial<FontDef>): FontDef {
+function registerFakeFont(
+  store: FontStore,
+  family: string,
+  options?: { style?: string; weight?: number },
+) {
   const style = options?.style ?? 'normal';
   const weight = options?.weight ?? 400;
-  const data = options?.data ?? mkData([family, style, weight].join(':'));
-  return { family, style, weight, data };
+  const data = mkData([family, style, weight].join(':'));
+  store.registerFont(data, { family, style: style as 'normal', weight });
+}
+
+function createTestStore(): FontStore {
+  const store = new FontStore();
+  registerFakeFont(store, 'Test');
+  registerFakeFont(store, 'Test', { style: 'italic' });
+  registerFakeFont(store, 'Test', { style: 'oblique' });
+  registerFakeFont(store, 'Test', { weight: 700 });
+  registerFakeFont(store, 'Test', { style: 'italic', weight: 700 });
+  registerFakeFont(store, 'Test', { style: 'oblique', weight: 700 });
+  registerFakeFont(store, 'Other');
+  return store;
 }

src/font-store.ts

@@ -10,16 +10,16 @@ export class FontStore {
   readonly #fontDefs: FontDef[];
   #fontCache: Record<string, Promise<Font>> = {};
 
-  constructor(fontDefs?: FontDef[]) {
-    this.#fontDefs = fontDefs ?? [];
+  constructor() {
+    this.#fontDefs = [];
   }
 
   registerFont(data: Uint8Array, config?: FontConfig): void {
     const pdfFont = new PDFEmbeddedFont(data);
     const family = config?.family ?? pdfFont.familyName;
     const style = config?.style ?? pdfFont.style;
     const weight = weightToNumber(config?.weight ?? pdfFont.weight);
-    this.#fontDefs.push({ family, style, weight, data });
+    this.#fontDefs.push({ family, style, weight, data, pdfFont });
     this.#fontCache = {}; // Invalidate cache
   }
 
@@ -40,11 +40,11 @@ export class FontStore {
 
   _loadFont(selector: FontSelector, key: string): Promise<Font> {
     const selectedFontDef = selectFontDef(this.#fontDefs, selector);
-    const pdfFont = new PDFEmbeddedFont(selectedFontDef.data);
+    const pdfFont = selectedFontDef.pdfFont ?? new PDFEmbeddedFont(selectedFontDef.data);
     return Promise.resolve(
       pickDefined({
         key,
-        name: pdfFont.fontName ?? selectedFontDef.family, // TODO ?? pdfFont.postscriptName
+        name: pdfFont.fontName ?? selectedFontDef.family,
         style: selector.fontStyle ?? 'normal',
         weight: weightToNumber(selector.fontWeight ?? 400),
         pdfFont,

src/fonts.test.ts

@@ -1,59 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import type { FontWeight } from './api/text.ts';
-import { readFonts, weightToNumber } from './fonts.ts';
-
-describe('readFonts', () => {
-  it('returns fonts array', () => {
-    const fontsDef = {
-      Test: [
-        { data: mkData('Test_Sans_Normal') },
-        { data: mkData('Test_Sans_Italic'), italic: true },
-        { data: mkData('Test_Sans_Bold'), bold: true },
-        { data: mkData('Test_Sans_BoldItalic'), italic: true, bold: true },
-      ],
-      Other: [{ data: mkData('Other_Normal') }],
-    };
-
-    const fonts = readFonts(fontsDef);
-
-    expect(fonts).toEqual([
-      { family: 'Test', style: 'normal', weight: 400, data: mkData('Test_Sans_Normal') },
-      { family: 'Test', style: 'italic', weight: 400, data: mkData('Test_Sans_Italic') },
-      { family: 'Test', style: 'normal', weight: 700, data: mkData('Test_Sans_Bold') },
-      { family: 'Test', style: 'italic', weight: 700, data: mkData('Test_Sans_BoldItalic') },
-      { family: 'Other', style: 'normal', weight: 400, data: mkData('Other_Normal') },
-    ]);
-  });
-
-  it('throws on missing input', () => {
-    expect(() => readFonts(undefined)).toThrow(new TypeError('Expected object, got: undefined'));
-  });
-
-  it('throws on invalid type', () => {
-    expect(() => readFonts(23)).toThrow(new TypeError('Expected object, got: 23'));
-  });
-
-  it('throws on invalid italic value', () => {
-    const fn = () => readFonts({ Test: [{ data: 'data', italic: 23 }] });
-
-    expect(fn).toThrow(
-      new TypeError('Invalid value for "Test/0/italic": Expected boolean, got: 23'),
-    );
-  });
-
-  it('throws on invalid bold value', () => {
-    const fn = () => readFonts({ Test: [{ data: 'data', bold: 23 }] });
-
-    expect(fn).toThrow(new TypeError('Invalid value for "Test/0/bold": Expected boolean, got: 23'));
-  });
-
-  it('throws on missing data', () => {
-    const fn = () => readFonts({ Test: [{ italic: true }] });
-
-    expect(fn).toThrow(new TypeError('Invalid value for "Test/0": Missing value for "data"'));
-  });
-});
+import { weightToNumber } from './fonts.ts';
 
 describe('weightToNumber', () => {
   it('supports keywords `normal` and `bold`', () => {
@@ -79,7 +27,3 @@ describe('weightToNumber', () => {
     expect(() => weightToNumber(0.1)).toThrow(new Error('Invalid font weight: 0.1'));
   });
 });
-
-function mkData(value: string) {
-  return new Uint8Array(value.split('').map((c) => c.charCodeAt(0)));
-}

src/fonts.ts

@@ -1,9 +1,7 @@
-import type { PDFFont } from '@ralfstx/pdf-core';
+import type { PDFEmbeddedFont, PDFFont } from '@ralfstx/pdf-core';
 
 import type { FontStyle, FontWeight } from './api/text.ts';
-import { readBinaryData } from './binary-data.ts';
 import { printValue } from './print-value.ts';
-import { optional, readAs, readBoolean, readObject, required, types } from './types.ts';
 
 /**
  * The resolved definition of a font.
@@ -13,6 +11,7 @@ export type FontDef = {
   style: FontStyle;
   weight: number;
   data: Uint8Array;
+  pdfFont?: PDFEmbeddedFont;
 };
 
 export type Font = {
@@ -29,27 +28,6 @@ export type FontSelector = {
   fontWeight?: FontWeight;
 };
 
-export function readFonts(input: unknown): FontDef[] {
-  return Object.entries(readObject(input)).flatMap(([name, fontDef]) => {
-    return readAs(fontDef, name, required(types.array(readFont))).map(
-      (font) => ({ family: name, ...font }) as FontDef,
-    );
-  });
-}
-
-export function readFont(input: unknown): Partial<FontDef> {
-  const obj = readObject(input, {
-    italic: optional((value) => readBoolean(value) || undefined),
-    bold: optional((value) => readBoolean(value) || undefined),
-    data: required(readBinaryData),
-  });
-  return {
-    style: obj.italic ? 'italic' : 'normal',
-    weight: obj.bold ? 700 : 400,
-    data: obj.data,
-  } as FontDef;
-}
-
 export function weightToNumber(weight: FontWeight): number {
   if (weight === 'normal') {
     return 400;

src/read-document.ts

@@ -3,16 +3,13 @@ import type { PDFDocument } from '@ralfstx/pdf-core';
 import type { FileRelationShip } from './api/document.ts';
 import type { BoxEdges, Size } from './box.ts';
 import { parseEdges } from './box.ts';
-import type { FontDef } from './fonts.ts';
-import { readFonts } from './fonts.ts';
 import type { Block, TextAttrs } from './read-block.ts';
 import { readBlock, readInheritableAttrs } from './read-block.ts';
 import { parseOrientation, readPageSize } from './read-page-size.ts';
 import type { Obj } from './types.ts';
 import { dynamic, optional, readAs, readObject, required, typeError, types } from './types.ts';
 
 export type DocumentDefinition = {
-  fonts?: FontDef[];
   pageSize?: Size;
   pageOrientation?: 'portrait' | 'landscape';
   info?: Metadata;
@@ -54,7 +51,6 @@ export type PageInfo = {
 
 export function readDocumentDefinition(input: unknown): DocumentDefinition {
   const def1 = readObject(input, {
-    fonts: optional(readFonts),
     pageSize: optional(readPageSize),
     pageOrientation: optional(parseOrientation),
     info: optional(readInfo),