Add color emoji support via SBIX bitmap rendering

[jspears]

Summary

Adds color emoji rendering to PDFKit. When an emoji font is registered, text containing emoji is automatically segmented into plain text and emoji runs. Emoji glyphs are rendered as inline bitmap images (PNG XObjects) extracted from the font's sbix table, while surrounding text continues to render normally through the existing font pipeline.

There is a follow up PR stacked on this one that adds support for COLR/CPAL and CBDT/CBLC

Motivation

PDFKit currently discards color emoji data during font subsetting. The PDF either shows monochrome outlines or blank spaces where emoji should appear. This is a common pain point for anyone generating PDFs with user-supplied text that may contain emoji.

How It Works

Text Segmentation

A new emoji segmenter (lib/emoji/segmenter.js) splits input text into text vs emoji segments using Unicode range heuristics. It correctly handles ZWJ sequences, regional indicator pairs (flag emoji), skin tone modifiers, variation selectors, and keycap sequences.

Emoji Font Registration

A new registerEmojiFont method (lib/mixins/fonts.js, lib/font_factory.js) loads an emoji font via fontkit. TrueType Collections are handled by iterating the font collection and matching by postscriptName or familyName, avoiding the getVariation call that crashes on emoji fonts lacking fvar/gvar tables.

Can also be set via document constructor options:

const doc = new PDFDocument({
  emojiFont: '/path/to/Apple Color Emoji.ttc',
  emojiFontFamily: 'AppleColorEmoji',
});

Rendering

• widthOfString is now emoji-aware, summing text widths and emoji widths across segments
• _line detects emoji segments and routes them to _emojiFragment instead of _fragment
• _emojiFragment uses fontkit layout/shaping, extracts SBIX bitmaps via glyph.getImageForSize, and places them as image XObjects
• Bitmap images are cached by glyphId:ppem to avoid redundant embedding

Line Wrapping

No changes needed. LineWrapper calls widthOfString which is now emoji-aware, so word wrapping works correctly with mixed text/emoji content.

Usage

import PDFDocument from 'pdfkit';

const doc = new PDFDocument({
  emojiFont: '/System/Library/Fonts/Apple Color Emoji.ttc',
  emojiFontFamily: 'AppleColorEmoji',
});

doc.font('Helvetica')
   .fontSize(18)
   .text('Hello World PDFKit');

Testing

• All 287 existing unit tests pass with no regressions
• 10 new visual snapshot tests covering: simple emoji, multiple emoji, he- 10 new visual snapshot tests covering:la- 10 ni, skin tone modifiers, different font sizes, emoji-only lines, plain text (no regression), and keycap emoji

Limitations

• Currently supports sbix (bitmap) fonts only. Apple Color Emoji
• Follow up PR supports COLR/CPAL and CBDT/CBLC via NotoColorEmoji.ttf/Twemoji.Mozilla.ttf respectively

[jspears]

• How would one add an svg based image inside the text sized to the text? #978
• Color emojis are not getting displayed in the pdf #1399
• does PDFKit supports emoji now ? #1056

[blikblum]

Some nit

Please add only one visual test

We should prefer unit tests going forward

[blikblum]

Please look at test fails

[jspears]

Some nit

Please add only one visual test

We should prefer unit tests going forward

moved into single test -- ran prettier -- probably should add it lint command in package.json or add it to CONTRIBUTING.md

[jspears]

Please look at test fails

tests are passing now.

[blikblum]

Is good to go.

Just some NIT:

• in the demo // --- Mixed scripts with emoji --- is not rendering properly. You can remove it if is not a bug at all, just no font support as a suppose
• try to make the visual snapshot generate only one png file
• please remove tests/visual/image_snapshots/fonts-spec-js-fonts-default-helvetica-1-snap.png and tests/visual/image_snapshots/fonts-spec-js-fonts-helvetica-bold-1-snap.png from PR. There an issue in current setup that should be addressed separately

[blikblum]

@jspears tried to run the tests in my local setup and noted the font file is not in the PR

Downloaded a font from https://github.com/samuelngs/apple-emoji-ttf/releases

Tested with AppleColorEmoji-Linux.ttf and got the error below

I believe you did not commit the font because of copyright concerns

Is there other font that don't have copyright issues that can be used to test this feature?

emoji › simple emoji mixed with text
    TypeError: Cannot read properties of null (reading 'id')

      181 |   _emojiWidthOfString(text, fontSize) {
      182 |     if (!this._emojiFont) return 0;
    > 183 |     const run = this._emojiFont.layout(text);
          |                                 ^
      184 |     let totalAdvance = 0;
      185 |     for (let i = 0; i < run.glyphs.length; i++) {
      186 |       totalAdvance += run.positions[i].xAdvance;

      at $99be642f82069918$export$2e2bcd8739ae039.processNoncontextualSubstitutions (node_modules/fontkit/dist/src/aat/AATMorxProcessor.js:218:17)
      at $99be642f82069918$export$2e2bcd8739ae039.processSubtable (node_modules/fontkit/dist/src/aat/AATMorxProcessor.js:90:12)
      at $99be642f82069918$export$2e2bcd8739ae039.process (node_modules/fontkit/dist/src/aat/AATMorxProcessor.js:68:16)
      at $860fcbd64bc12fbc$export$2e2bcd8739ae039.substitute (node_modules/fontkit/dist/src/aat/AATLayoutEngine.js:19:24)
      at $9d641258c9d7180d$export$2e2bcd8739ae039.substitute (node_modules/fontkit/dist/src/layout/LayoutEngine.js:86:19)
      at $9d641258c9d7180d$export$2e2bcd8739ae039.layout (node_modules/fontkit/dist/src/layout/LayoutEngine.js:70:10)
      at $0a8ef2660a6ce4b6$export$2e2bcd8739ae039.layout (node_modules/fontkit/dist/src/TTFFont.js:360:31)
      at PDFDocument.layout [as _emojiWidthOfString] (lib/mixins/fonts.js:183:33)
      at PDFDocument._emojiWidthOfString [as widthOfString] (lib/mixins/text.js:123:30)
      at LineWrapper.widthOfString [as wordWidth] (lib/line_wrapper.js:90:21)
      at LineWrapper.wordWidth [as eachWord] (lib/line_wrapper.js:119:38)
      at LineWrapper.eachWord [as wrap] (lib/line_wrapper.js:225:10)
      at PDFDocument.wrap [as _text] (lib/mixins/text.js:94:15)
      at PDFDocument._text [as text] (lib/mixins/text.js:111:17)
      at text (tests/visual/emoji.spec.js:29:11)
      at fn (tests/visual/helpers.js:18:13)
      at tests/visual/helpers.js:19:6
      at runDocTest (tests/visual/helpers.js:13:10)
      at Object.<anonymous> (tests/visual/emoji.spec.js:21:22)