1.17.1-mod.2025.7 : フォント埋め込み時に fontkit の TTFFont インスタンスを受け付けるよう拡張 (#10)

* docs: add AGENTS.md

* refactor: separate custom font embedder classes into subset/non-subset implementations

* feat: add support for embedding TTFFont instances (subset-only) in PDFDocument

* style: code formatting

* docs: update internal docs

* chore: upgrade devDependencies (types)

* docs: update modifications change log

* 1.17.1-mod.2025.7

* ci: update Node.js version to v20+

* update comments

* change the options argument of `embedTTFFont()` to required

* rename CustomFontEmbedder -> AbstractCustomFontEmbedder and CustomFontNonSubsetEmbedder -> CustomFontEmbedder

* test: remove unnecessary async/await

---------

Co-authored-by: FAL <contact@fal-works.com>

Author: falworks-dy

.github/workflows/npm-publish-github-packages.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: https://npm.pkg.github.com/
           scope: '@denkiyagi'
           cache: yarn
@@ -42,7 +42,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: https://npm.pkg.github.com/
           scope: '@denkiyagi'
       - uses: actions/download-artifact@v4

.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [20.x, 22.x, 24.x]
 
     steps:
       - uses: actions/checkout@v4

AGENTS.md

@@ -0,0 +1,29 @@
+# AI Agent Briefing
+
+## Mission & Purpose
+- `@denkiyagi/pdf-lib` extends the upstream `pdf-lib` to power PDF generation for `yagisan-reports`, a PDF report generation engine.
+- Current focus areas: richer custom font handling via `@denkiyagi/fontkit`, groundwork for improved error handling, adding PDF encryption support, and fixing upstream bugs.
+- Keep the fork aligned with upstream quality while preserving `yagisan-reports`-specific behaviors; prefer additive changes and call out intentional divergences in `MODIFICATIONS.md` or `MODIFICATION-DEVELOPMENT.md`.
+
+## Project Orientation
+- `src/` – Primary TypeScript source for the library; exports must remain framework-agnostic and compatible with browsers and Node.
+- `tests/` – Jest-powered regression coverage.
+- `apps/` – Example and manual-test harnesses used to validate real-world document flows.
+- `assets/` – Sample PDFs, fonts, and images consumed by docs and tests; treat as fixtures when updating expectations.
+- `build/`, `rollup.config.mjs`, `tsconfig.json`, `jest.json` – Tooling scaffolding for bundling, type emission, and tests.
+- `docs/` – Markdown/docs site material mirrored from upstream; update only when behavior changes.
+- `scratchpad/` – Throwaway experiments; do not rely on contents for production logic.
+
+## Tech Stack
+- Node.js 20+ runtime, Yarn package manager.
+- TypeScript 4.x across source and typings.
+- Critical dependency: `@denkiyagi/fontkit` (our fork) powers font parsing, embedding, and subsetting.
+
+## Common Commands
+- `yarn typecheck` – Checks TypeScript types across the codebase.
+- `yarn lint` – Runs the lint rules expected by CI; fix warnings locally to avoid pipeline noise.
+
+## Helpful References
+- Change log: `MODIFICATIONS.md` (what differs from upstream).
+- Dev workflow, release, and scripting notes: `MODIFICATION-DEVELOPMENT.md`.
+- Upstream behavior context: `README.md` plus linked docs/examples.

MODIFICATION-DEVELOPMENT.md

@@ -8,6 +8,12 @@ After cloning the repository and running `yarn install`, you must run the follow
 yarn dev:prep
 ```
 
+## Editor setup
+
+If you use VS Code:
+
+`TypeScript: Select TypeScript Version...` -> `Use Workspace Version`
+
 ## Before submitting pull request
 
 - Lint and typecheck

MODIFICATIONS.md

@@ -1,5 +1,10 @@
 # Modifications
 
+## [1.17.1-mod.2025.7]
+
+- Add `PDFDocument#embedTTFFont` (subset-only) and `CustomFontSubsetEmbedder.forTTFFont` so pre-created fontkit `TTFFont` instances can be embedded.
+- Refactor the internal custom font embedders into separate subset and non-subset implementations by adding the abstract base class `AbstractCustomFontEmbedder`.
+
 ## [1.17.1-mod.2025.6]
 
 - Update `@denkiyagi/fontkit` to `2.0.4-mod.2025.2`, which enhances runtime performance for Unicode Variation Sequences (UVS) support.
@@ -12,7 +17,7 @@
 
 - Changed npm dependency `fontkit` to `@denkiyagi/fontkit`
 - Improved `options` parameter of `PDFDocument#embedFont`
-- Fix `CustomFontEmbedder#embedCIDFontDict` so that it respects glyph metrics when embedding vertical fonts
+- Fix `AbstractCustomFontEmbedder#embedCIDFontDict` so that it respects glyph metrics when embedding vertical fonts
 - Add methods `PDFFont#getRawStandardFont` and `PDFFont#getRawCustomFont`
 - Improve parameters of `PDFPage#drawText`:
     - Expand the data type of the `text` parameter so that it also accepts Glyph IDs instead of string

README.md

@@ -1209,7 +1209,7 @@ Check out [MAINTAINERSHIP.md](docs/MAINTAINERSHIP.md) for details on how this re
 
 ## Prior Art
 
-- [`pdfkit`](https://github.com/devongovett/pdfkit) is a PDF generation library for Node and the Browser. This library was immensely helpful as a reference and existence proof when creating `pdf-lib`. `pdfkit`'s code for [font embedding](src/core/embedders/CustomFontEmbedder.ts#L17-L21), [PNG embedding](src/core/embedders/PngEmbedder.ts#L7-L11), and [JPG embedding](src/core/embedders/JpegEmbedder.ts#L25-L29) was especially useful.
+- [`pdfkit`](https://github.com/devongovett/pdfkit) is a PDF generation library for Node and the Browser. This library was immensely helpful as a reference and existence proof when creating `pdf-lib`. `pdfkit`'s code for [font embedding](src/core/embedders/AbstractCustomFontEmbedder.ts), [PNG embedding](src/core/embedders/PngEmbedder.ts#L7-L11), and [JPG embedding](src/core/embedders/JpegEmbedder.ts#L25-L29) was especially useful.
 - [`pdf.js`](https://github.com/mozilla/pdf.js) is a PDF rendering library for the Browser. This library was helpful as a reference when writing `pdf-lib`'s parser. Some of the code for stream decoding was [ported directly to TypeScript](src/core/streams) for use in `pdf-lib`.
 - [`pdfbox`](https://pdfbox.apache.org/) is a PDF generation and modification library written in Java. This library was an invaluable reference when implementing form creation and filling APIs for `pdf-lib`.
 - [`jspdf`](https://github.com/MrRio/jsPDF) is a PDF generation library for the browser.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denkiyagi/pdf-lib",
-  "version": "1.17.1-mod.2025.6",
+  "version": "1.17.1-mod.2025.7",
   "description": "A modified version of pdf-lib. Create and modify PDF files with JavaScript",
   "author": "DenkiYagi Inc. (modified version author), Andrew Dillon <andrew.dillon.j@gmail.com> (orignal version author)",
   "contributors": [
@@ -89,10 +89,10 @@
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-terser": "^0.3.0",
-    "@types/crypto-js": "^4.0.2",
+    "@types/crypto-js": "^4.2.2",
     "@types/jest": "^26.0.0",
-    "@types/node-fetch": "^2.5.7",
-    "@types/pako": "^2.0.0",
+    "@types/node-fetch": "^2.6.13",
+    "@types/pako": "^2.0.4",
     "downlevel-dts": "^0.5.0",
     "flamebearer": "^1.1.3",
     "http-server": "^0.12.3",

src/api/PDFDocument.ts

@@ -1,3 +1,4 @@
+import type { TTFFont } from '@denkiyagi/fontkit';
 import type { Embeddable } from 'src/api/Embeddable';
 import {
   EncryptedPDFError,
@@ -12,6 +13,7 @@ import { PDFForm } from 'src/api/form/PDFForm';
 import { PageSizes } from 'src/api/sizes';
 import type { StandardFonts } from 'src/api/StandardFonts';
 import {
+  AbstractCustomFontEmbedder,
   CustomFontEmbedder,
   CustomFontSubsetEmbedder,
   JpegEmbedder,
@@ -913,7 +915,7 @@ export class PDFDocument {
    * ```
    * @param font The input data for a font.
    * @param options The options to be used when embedding the font.
-   * @returns Resolves with the embedded font.
+   * @returns The embedded font represented as `PDFFont`.
    */
   embedFont(
     font: StandardFonts | string | Uint8Array | ArrayBuffer,
@@ -924,14 +926,19 @@ export class PDFDocument {
     assertIs(font, 'font', ['string', Uint8Array, ArrayBuffer]);
     assertIs(subset, 'subset', ['boolean']);
 
-    let embedder: CustomFontEmbedder | StandardFontEmbedder;
+    let embedder: AbstractCustomFontEmbedder | StandardFontEmbedder;
     if (isStandardFont(font)) {
       embedder = StandardFontEmbedder.for(font, customName);
     } else if (canBeConvertedToUint8Array(font)) {
       const bytes = toUint8Array(font);
       embedder = subset
         ? CustomFontSubsetEmbedder.for(bytes, customName, vertical, advanced)
-        : CustomFontEmbedder.for(bytes, customName, vertical, advanced);
+        : CustomFontEmbedder.for(
+            bytes,
+            customName,
+            vertical,
+            advanced,
+          );
     } else {
       throw new TypeError(
         '`font` must be one of `StandardFonts | string | Uint8Array | ArrayBuffer`',
@@ -945,6 +952,39 @@ export class PDFDocument {
     return pdfFont;
   }
 
+  /**
+   * Embed a fontkit `TTFFont` instance into this document.
+   *
+   * NOTE: `options.subset` must be `true`, because the non-subset font embedder requires
+   * the raw font bytes which are not available from a `TTFFont` instance.
+   *
+   * @param font The `TTFFont` to subset and embed.
+   * @param options Additional embedding options (the `subset` option must be `true`).
+   * @returns The embedded font represented as `PDFFont`.
+   * @throws If `options.subset` is not `true`.
+   */
+  embedTTFFont(font: TTFFont, options: EmbedFontOptions): PDFFont {
+    const { subset, customName, vertical, advanced } = options;
+    if (subset !== true) {
+      throw new TypeError(
+        '`subset` must explicitly be true when embedding a TTFFont',
+      );
+    }
+
+    const embedder = CustomFontSubsetEmbedder.forTTFFont(
+      font,
+      customName,
+      vertical,
+      advanced,
+    );
+
+    const ref = this.context.nextRef();
+    const pdfFont = PDFFont.of(ref, this, embedder);
+    this.fonts.push(pdfFont);
+
+    return pdfFont;
+  }
+
   /**
    * Embed a standard font into this document.
    * For example:

src/api/PDFFont.ts

@@ -3,15 +3,17 @@ import type { Font as RawStandardFont } from '@pdf-lib/standard-fonts';
 import type { Embeddable } from 'src/api//Embeddable';
 import { PDFDocument } from 'src/api/PDFDocument';
 import {
-  CustomFontEmbedder,
+  AbstractCustomFontEmbedder,
   PDFHexString,
   PDFRef,
   StandardFontEmbedder,
 } from 'src/core';
 import type { SingleLineTextOrGlyphs } from 'src/types/text';
 import { assertIs, assertOrUndefined } from 'src/utils';
 
-export type FontEmbedder = CustomFontEmbedder | StandardFontEmbedder;
+export type FontEmbedder =
+  | AbstractCustomFontEmbedder
+  | StandardFontEmbedder;
 
 /**
  * Represents a font that has been embedded in a [[PDFDocument]].
@@ -48,7 +50,7 @@ export class PDFFont implements Embeddable {
     assertIs(ref, 'ref', [[PDFRef, 'PDFRef']]);
     assertIs(doc, 'doc', [[PDFDocument, 'PDFDocument']]);
     assertIs(embedder, 'embedder', [
-      [CustomFontEmbedder, 'CustomFontEmbedder'],
+      [AbstractCustomFontEmbedder, 'AbstractCustomFontEmbedder'],
       [StandardFontEmbedder, 'StandardFontEmbedder'],
     ]);
 
@@ -137,9 +139,8 @@ export class PDFFont implements Embeddable {
   getCharacterSet(): number[] {
     if (this.embedder instanceof StandardFontEmbedder) {
       return this.embedder.encoding.supportedCodePoints;
-    } else {
-      return this.embedder.font.characterSet;
     }
+    return this.embedder.font.characterSet;
   }
 
   /**
@@ -148,20 +149,18 @@ export class PDFFont implements Embeddable {
   getRawStandardFont(): RawStandardFont | null {
     if (this.embedder instanceof StandardFontEmbedder) {
       return this.embedder.font;
-    } else {
-      return null;
     }
+    return null;
   }
 
   /**
    * @returns The raw standard font instance if `this` is a custom font, otherwise `null`.
    */
   getRawCustomFont(): TTFFont | null {
-    if (this.embedder instanceof CustomFontEmbedder) {
+    if (this.embedder instanceof AbstractCustomFontEmbedder) {
       return this.embedder.font;
-    } else {
-      return null;
     }
+    return null;
   }
 
   /**