fix: AcroForm custom fonts fall back to a substitute font in Acrobat

[KaiPressmar]

What kind of change does this PR introduce?

Bug fix. Fixes #1096 (also relevant to #1335).

A custom embedded font applied to an AcroForm text field renders in the wrong font in some readers — reported here in Adobe Acrobat/Reader — even though the same font renders correctly for ordinary page text.

Root cause

initForm() always sets NeedAppearances: true, so a reader may regenerate a form field's appearance from its plain-text value at any time. Doing that requires resolving arbitrary characters to glyphs through the font referenced in the AcroForm's /DR and /DA resources.

For a custom embedded font, that resource was reusing the exact same font object used in content streams. I inspected the raw PDF bytes pdfkit produces and confirmed:

• The AcroForm's /DR /Font entry and the page's content-stream font are literally the same object: a subsetted Type0 font under /Encoding /Identity-H.
• That embedded, subsetted TrueType program has no cmap table at all (head, hhea, loca, maxp, cvt, prep, glyf, hmtx, fpgm — no cmap). That's fine for content streams, since pdfkit addresses glyphs directly by glyph ID there, but it leaves a reader with no way to map a form field's text to a glyph in that font when regenerating its appearance, and Identity-H isn't a standard character encoding it can fall back on either. It silently substitutes another font instead.

The fix

EmbeddedFont now embeds a second, dedicated font object the first time it's needed for AcroForm use, holding every glyph so a reader can resolve any character a user later types into the field, not just the ones already drawn elsewhere in the document. acroform.js now asks each font for this dedicated reference; StandardFont has no such distinction, so it falls back to its existing .ref() (the 14 standard fonts aren't embedded and already use WinAnsiEncoding, so they were never affected).

The dedicated font is a composite (Type0/CID) font, addressed through a custom WinAnsi-code-to-glyph-id CMap rather than a simple font under /Encoding /WinAnsiEncoding (the initial version of this PR). That redesign came from a second real-world bug, found after this PR was first opened and after real Acrobat testing against only a synthetic .ttf test fixture had passed:

• The original fix embedded this.font.stream.buffer directly, assuming it was always a valid, standalone TrueType or CFF program. For a font whose source file is .woff/.woff2 — which is how most web-sourced fonts, and both fonts that surfaced this in production, actually arrive — that buffer is the original compressed container, not a font program a viewer can load at all. Acrobat reported it as a font it "could not be extracted", the same failure this PR set out to fix.
• Routing the font program through fontkit's ordinary subset encoder instead (including every glyph, so nothing is missing) fixes that: the encoder always normalizes any source format into a valid TrueType/CFF program. But that encoder also always produces CID-keyed, cmap-less output for both TrueType and CFF sources — incompatible with a simple font's /Encoding /WinAnsiEncoding, which needs named, non-CID glyph access.
• The composite-font-plus-custom-CMap design resolves both constraints at once: it only ever needs the subset encoder's actual output shape (CID-keyed access to any glyph by id), and the CMap gives a reader the character encoding a simple font's built-in cmap would otherwise have supplied. It works uniformly whether the source font is TrueType or CFF, and whether it came from a .ttf/.otf file or a .woff/.woff2 one.

Two pitfalls worth flagging for review, both found and fixed while testing against real Acrobat:

• This new font object must not reuse pdfkit's subset-tag BaseFont naming convention (the six-uppercase-letter prefix meaning "an arbitrary subset of the font named after the +"), since it isn't a subset in pdfkit's usual sense. Reusing it gave both font objects an identical BaseFont name despite differing font programs, which made Acrobat report the embedded font as one it "could not be extracted".
• The FontFile2/FontFile3 stream needs its required length entry (/Length1 for FontFile2, spec 9.9 Table 127); pdfkit's existing embedding for content-stream fonts doesn't set it either, but that only surfaced as a problem once this stream was something Acrobat's forms engine actually tried to load and validate on its own.

Demo

Attached: a before/after PDF pair (same custom-font AcroForm field, built with pdfkit as it was before this fix and with this fix applied) plus screenshots of both opened in Adobe Acrobat/Reader. Before: the field falls back to a substitute font. After: it renders in the embedded font, no warnings on open.

• font-before.pdf
• font-after.pdf

Verification

• yarn test:unit — all 438 tests pass, including two regression tests in tests/unit/acroform.spec.js: one against a TrueType fixture, one against a CFF-flavored (OpenType/CFF) fixture, since the CFF/CIDFontType0 code path is a separate path through this fix and wasn't exercised by the first version of it.
• yarn lint / yarn format — clean.
• Manually verified against Adobe Acrobat with a generated form: before the fix, the field falls back to a substitute font; with the fix, it renders in the embedded font with no warnings on open. Also verified against real production fonts loaded from .woff2 files (both TrueType- and CFF-flavored), which is what caught the second bug described above.

Checklist:

• Unit Tests
• Documentation
• Update CHANGELOG.md
• Ready to be merged

Credit to @r4tz52 for the original report.

cc @blikblum, since you looked at this issue before — flagging for review whenever you have a chance.

[blikblum]

1- This behavior should be opt in. This increase the file size significantly
2- The handling should not be done in EmbeddedFont class, i.e., EmbeddedFont should not know about AcroForm. It should be the other way around
3- Investigate the possibility of using only the complete font for both AcroForm and TextStream, so the subset can be discarded ib this context