Skip to content

Add Adobe Glyph List resolution helpers - #256

Open
balazs-szucs wants to merge 3 commits into
refactor/font-02b-fallback-testsfrom
refactor/font-03-agl-names
Open

balazs-szucs wants to merge 3 commits into
refactor/font-02b-fallback-testsfrom
refactor/font-03-agl-names

Conversation

@balazs-szucs

@balazs-szucs balazs-szucs commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Description of Changes

Adds Adobe Glyph List (AGL) glyph-name resolution helpers to map single-scalar, uniXXXX, uppercase-only uXXXX, .suffix variants, and underscore-separated ligature names to Unicode. Reliable glyph-name decoding prevents broken text extraction and invalid /ToUnicode mappings when installing substitute fonts or repairing simple encodings.

Changed:

  • Generate a sorted Adobe glyph-name lookup table in native/bridge/src/adobe_glyph_names.inc and wire lookup helpers in jpdfium_qpdf.cpp.
  • Support uniXXXX, uppercase-only uXXXX, f_i component splitting, and .alt suffix stripping while rejecting ambiguous lowercase names such as uface.
  • Verify mapped Unicode scalars and CIDs before installing substitute font programs.

Checklist

General

  • I have read the Contributing Guide
  • I have performed a self-review of my own code
  • My changes generate no new warnings
  • Notable user-facing changes are recorded under ## [Unreleased] in CHANGELOG.md

Library changes

  • Javadoc covers any new or changed public type or member
  • Public API changes are additive, or .github/workflows/compatibility.yml excludes the break with a reason
  • Version references stay consistent across the README, docs/installation.md, and the POMs

Native or FFM changes

  • Rebuilt the bridge at the stack tip (bash native/build-real.sh)
  • Ran ./gradlew :jpdfium:integrationTest
  • Updated native/bridge/include/jpdfium.h and the ABI notes for any ABI change

Testing

  • Added or updated tests that cover the change
  • ./gradlew :jpdfium:integrationTest passes

@coderabbitai

coderabbitai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Explain Change →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 7a104b4 and cf0753b.

Files selected for processing: 4

  • jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java
  • jpdfium/src/test/java/stirling/software/jpdfium/doc/PdfFontEmbedderTest.java
  • native/bridge/src/adobe_glyph_names.inc
  • native/bridge/src/jpdfium_qpdf.cpp
Summary

Summary by CodeRabbit

  • Bug Fixes
    • Improved font handling in PDFs with custom character mappings, helping preserve the correct appearance of text when fonts are embedded.
    • Improved recognition of a wider range of glyph names, including accented characters, Greek letters, and symbols.
    • When specific font directories are provided, font lookup now respects those directories instead of including bundled font resources.

The change adds Adobe glyph-name lookup and parses PDF ToUnicode mappings. CID font embedding uses those mappings to check supplied glyph order and build CID-to-GID mappings for eligible TrueType fonts. Explicit-directory font indexes exclude bundled-resource faces.

Changes: Glyph-name and CID font mapping

Layer / File(s) Summary
Glyph-name Unicode lookup
native/bridge/src/adobe_glyph_names.inc, native/bridge/src/jpdfium_qpdf.cpp
A generated Adobe glyph-name table supports glyphForName alongside single-character and validated hexadecimal name forms.
ToUnicode parsing and glyph-order checks
native/bridge/src/jpdfium_qpdf.cpp
New helpers decode valid UTF-16 surrogate pairs, parse bfchar and bfrange mappings, and check whether mapped Unicode characters have glyph IDs matching their CIDs.
CID font validation and remapping
native/bridge/src/jpdfium_qpdf.cpp, jpdfium/src/test/java/stirling/software/jpdfium/doc/PdfFontEmbedderTest.java
For eligible CID fonts without an embedded program, processing uses parsed mappings to check glyph order. TrueType fonts can be remapped and receive a CID-to-GID map stream. Related CID replacement tests were removed.

Explicit-directory font selection

Layer / File(s) Summary
Filter bundled faces from explicit-directory lookups
jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java
Both in-memory and file-backed font resolution use an index that excludes bundled-resource faces when directories are explicit.

Change: Feature

Merge Risk: Moderate · previous review 7a104

Font substitution can install a program with wrong or missing glyph mappings for some CID fonts (non-Identity encodings, partial glyph coverage, inherited CMaps), and explicit embedding no longer generates ToUnicode mappings for unembedded Identity TrueType fonts. Glyph-name resolution is also incomplete for legacy and suffixed names. These are bounded to specific font shapes, but they should be fixed or accepted before merge, and the removed CID tests should be restored.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: adding Adobe Glyph List resolution helpers. The changeset adds an AGL lookup table and glyph-name lookup helpers in jpdfium_qpdf.cpp, so the title matches the primary …
Description check Passed The description follows the template's main sections: a 'Description of Changes' section explains the purpose and lists the changes, and the checklist is included. It explains what changed and why. Ga…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: adding Adobe Glyph List resolution helpers. The changeset adds an AGL lookup table and glyph-name lookup helpers in jpdfium_qpdf.cpp, so the title matches the primary change. It is short and specific.

Full details: Description check

Explanation

The description follows the template's main sections: a 'Description of Changes' section explains the purpose and lists the changes, and the checklist is included. It explains what changed and why. Gaps: the template's HTML comment asks for an issue reference ('Closes #(issue number)'), and none is given. Several checklist items are unchecked and the testing item is unclear. The author checks 'Ran ./gradlew :jpdfium:integrationTest' but the raw summary shows PdfFontEmbedderTest tests were removed and no tests were added, so the 'Added or updated tests' item stays unchecked. The changelog item is also unchecked. The description says the integration test passes, but the test-removal diff is not explained. The description does not mention the removed tests or the behaviour change in PdfFontEmbedder.

Resolution

Consider the following improvements. Add the issue reference (for example, 'Closes #256' if applicable). Explain why the tests in PdfFontEmbedderTest were removed and whether equivalent coverage exists. Describe the behaviour change to explicit font directory filtering in PdfFontEmbedder. Complete or explain unchecked items, including the CHANGELOG.md entry and the Javadoc status for public types.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@balazs-szucs
balazs-szucs changed the base branch from refactor/font-02-fallbacks to feat/font-fallbacks November 11, 2026 22:31
@balazs-szucs
balazs-szucs added this pull request to stack #268 November 11, 2026 22:31
@balazs-szucs
balazs-szucs removed this pull request from stack #268 November 11, 2026 22:55
@balazs-szucs
balazs-szucs added this pull request to stack #269 November 11, 2026 22:56
@balazs-szucs
balazs-szucs force-pushed the refactor/font-03-agl-names branch 2 times, most recently from cf40df2 to c67e9af Compare November 11, 2026 23:56

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 10

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between b0bc328 and 346ab96.

Files ignored due to path filters: 1

  • jpdfium/src/main/resources/fonts/NotoSansSC-Regular.otf.xz is excluded by !**/*.xz
Files selected for processing: 2

  • native/bridge/src/adobe_glyph_names.inc
  • native/bridge/src/jpdfium_qpdf.cpp

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Review details

Context from checks skipped due to timeout: 46

  • GitHub Check: Version bump script regression tests
  • GitHub Check: Markdown lint
  • GitHub Check: Gradle wrapper validation
  • GitHub Check: Shellcheck (scripts + native/*.sh)
  • GitHub Check: Javadoc builds cleanly
  • GitHub Check: prep-windows-icu
  • GitHub Check: Native jar checker regression tests
  • GitHub Check: Corpus (generate + native)
  • GitHub Check: Samples E2E (88 features via RunAllSamples)
  • GitHub Check: FFM layout vs pinned PDFium headers
  • GitHub Check: Public API compatibility (japicmp vs last release)
  • GitHub Check: Corpus + integration e2e
  • GitHub Check: build-natives (darwin-arm64, macos-15)
  • GitHub Check: Module descriptor integrity
  • GitHub Check: build-natives (windows-x64, windows-latest)
  • GitHub Check: C++ - clang-tidy + cppcheck + clang-format
  • GitHub Check: build-natives (linux-x64, ubuntu-latest)
  • GitHub Check: build-natives (windows-arm64, windows-11-arm)
  • GitHub Check: Flaky-test guard (3× rerun)
  • GitHub Check: Native bridge libFuzzer (ASan/UBSan, real PDFium)
  • GitHub Check: build-natives (linux-arm64, ubuntu-24.04-arm)
  • GitHub Check: Build & Verify (Compilation) (macos-15)
  • GitHub Check: Concurrency Stress Tests (Linux x64)
  • GitHub Check: Build & Verify (Compilation) (ubuntu-latest)
  • GitHub Check: Build & Verify (Compilation) (windows-latest)
  • GitHub Check: build-natives (darwin-x64, macos-15-intel)
  • GitHub Check: Unit & Integration E2E Tests (Linux x64)
  • GitHub Check: JMH Benchmarks (advisory)
  • GitHub Check: Samples E2E Suite (All 88 Feature Samples)
  • GitHub Check: Musl Native Detection (Alpine)
  • GitHub Check: Publish Maven Dry Run
  • GitHub Check: README Quick Start Example (Linux x64)
  • GitHub Check: Robustness, Leak & Determinism Tests (Linux x64)
  • GitHub Check: GraalVM Native Image Smoke & E2E Test (Linux x64)
  • GitHub Check: Bundle verify (symbols, RPATH, linkage, sizes)
  • GitHub Check: marker
  • GitHub Check: Java - SpotBugs + Checkstyle + PMD + Spotless
  • GitHub Check: JaCoCo coverage (non-blocking ratchet)
  • GitHub Check: OSV vulnerability scan
  • GitHub Check: Natural System Libvips & Downstream Integration (Linux x64)
  • GitHub Check: Restricted-env compat (no execstack + hermetic bundle)
  • GitHub Check: CodeQL (java-kotlin)
  • GitHub Check: CodeQL Analysis (c-cpp)
  • GitHub Check: CodeQL (c-cpp)
  • GitHub Check: CLI correctness & no-corruption tests
  • GitHub Check: CodeQL Analysis (java-kotlin)
Additional context used

Code guidelines: 1

.github/CODERABBIT_REVIEW.md — configured
Path-based instructions: 2

Apply the native ownership, C ABI, C++23, engine integration, memory, and SIMD rules from .github/CODERABBIT_REVIEW.md.

CodeRabbit configuration file

Files:

  • native/bridge/src/jpdfium_qpdf.cpp
Source excerpt: These rules apply to maintained source.

CodeRabbit inference engine (.github/CODERABBIT_REVIEW.md)

Files:

  • native/bridge/src/adobe_glyph_names.inc
  • native/bridge/src/jpdfium_qpdf.cpp

Comment thread native/bridge/src/adobe_glyph_names.inc Resolved
Comment thread native/bridge/src/adobe_glyph_names.inc Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
Comment thread native/bridge/src/jpdfium_qpdf.cpp Resolved
@balazs-szucs
balazs-szucs force-pushed the refactor/font-03-agl-names branch from 346ab96 to b595f4b Compare November 14, 2026 00:14
@balazs-szucs
balazs-szucs force-pushed the refactor/font-03-agl-names branch from b595f4b to 0824972 Compare November 15, 2026 11:55
@balazs-szucs
balazs-szucs removed this pull request from stack #269 November 15, 2026 11:57
@balazs-szucs
balazs-szucs changed the base branch from feat/font-fallbacks to refactor/font-02b-fallback-tests November 15, 2026 11:58
@balazs-szucs
balazs-szucs added this pull request to stack #298 November 15, 2026 12:00
@balazs-szucs
balazs-szucs force-pushed the refactor/font-03-agl-names branch 2 times, most recently from b054258 to 7a104b4 Compare November 15, 2026 21:03

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 346ab96 and 7a104b4.

Files selected for processing: 3

  • jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java
  • jpdfium/src/test/java/stirling/software/jpdfium/doc/PdfFontEmbedderTest.java
  • native/bridge/src/jpdfium_qpdf.cpp
Files with no reviewable changes: 1

  • jpdfium/src/test/java/stirling/software/jpdfium/doc/PdfFontEmbedderTest.java

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Review details

Context from checks skipped due to timeout: 32

  • GitHub Check: CodeRabbit
  • GitHub Check: Corpus (generate + native)
  • GitHub Check: Samples E2E Suite (All 88 Feature Samples)
  • GitHub Check: Publish Maven Dry Run
  • GitHub Check: GraalVM Native Image Smoke & E2E Test (Linux x64)
  • GitHub Check: Build & Verify (Compilation) (ubuntu-latest)
  • GitHub Check: Build & Verify (Compilation) (windows-latest)
  • GitHub Check: Robustness, Leak & Determinism Tests (Linux x64)
  • GitHub Check: Natural System Libvips & Downstream Integration (Linux x64)
  • GitHub Check: JMH Benchmarks (advisory)
  • GitHub Check: Unit & Integration E2E Tests (Linux x64)
  • GitHub Check: Build patched PDFium and run Ghent V50
  • GitHub Check: Native bridge libFuzzer (ASan/UBSan, real PDFium)
  • GitHub Check: CLI correctness & no-corruption tests
  • GitHub Check: CodeQL (c-cpp)
  • GitHub Check: build-natives (linux-arm64, ubuntu-24.04-arm)
  • GitHub Check: CodeQL (java-kotlin)
  • GitHub Check: Java - SpotBugs + Checkstyle + PMD + Spotless
  • GitHub Check: build-natives (windows-arm64, windows-11-arm)
  • GitHub Check: build-natives (linux-x64, ubuntu-latest)
  • GitHub Check: build-natives (darwin-x64, macos-15-intel)
  • GitHub Check: build-natives (darwin-arm64, macos-15)
  • GitHub Check: build-natives (windows-x64, windows-latest)
  • GitHub Check: Restricted-env compat (no execstack + hermetic bundle)
  • GitHub Check: Flaky-test guard (3× rerun)
  • GitHub Check: Corpus + integration e2e
  • GitHub Check: CodeQL Analysis (java-kotlin)
  • GitHub Check: JaCoCo coverage (non-blocking ratchet)
  • GitHub Check: Javadoc builds cleanly
  • GitHub Check: Samples E2E (88 features via RunAllSamples)
  • GitHub Check: Bundle verify (symbols, RPATH, linkage, sizes)
  • GitHub Check: CodeQL Analysis (c-cpp)
Additional context used

Code guidelines: 1

.github/CODERABBIT_REVIEW.md — configured
Path-based instructions: 3

Apply the native ownership, C ABI, C++23, engine integration, memory, and SIMD rules from .github/CODERABBIT_REVIEW.md.

CodeRabbit configuration file

Files:

  • native/bridge/src/jpdfium_qpdf.cpp
Apply the Java 25 and FFM rules from .github/CODERABBIT_REVIEW.md.

CodeRabbit configuration file

Files:

  • jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java
Source excerpt: These rules apply to maintained source.

CodeRabbit inference engine (.github/CODERABBIT_REVIEW.md)

Files:

  • jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java
  • native/bridge/src/jpdfium_qpdf.cpp
Additional comments: 1

jpdfium/src/main/java/stirling/software/jpdfium/doc/PdfFontEmbedder.java: 1

324-324: Data Integrity & Integration

The filter is an intentional behavior change, not a defect. The commit title, the removeIf line, and the empty-directory test all describe explicit directories as isolated from bundled fallback. The inspected PDF/X documentation names only system font directories. The review comment asks whether losing the fallback is acceptable. That is a design question for maintainers, and it does not establish a concrete failure or a violated repository requirement. The comment's conditional premise that PDF/X must keep the fallback is unsubstantiated by the inspected sources. No change instruction should follow from this comment.


std::map<uint32_t, uint32_t> parseToUnicode(QPDFObjectHandle const& font) {
std::map<uint32_t, uint32_t> map;
auto stream = font.getKey("/ToUnicode");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

Reject or resolve inherited ToUnicode mappings before remapping.

A ToUnicode CMap can inherit mappings through UseCMap. This parser reads only the local stream. (opensource.adobe.com)

For example, let the inherited mapping contain CID 2 → B and the local mapping contain CID 1 → A. If A resolves to GID 36, cidRemap becomes true. The generated /CIDToGIDMap contains only CID 1, so CID 2 loses its glyph selection.

Resolve the inherited mappings with cycle detection, or reject substitution when inheritance is present. Add a regression that checks both glyphs after reopening.

return bytes == 4 && UnicodeScalar::decode(value) != 0;
};
auto skipSpace = [&](size_t& pos) {
while (pos < text.size() && std::isspace(uint8_t(text[pos]))) ++pos;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Skip CMap comments between mapping tokens.

CMaps use PostScript syntax, which permits % comments. (adobe-type-tools.github.io)

For 1 beginbfchar\n% mapping\n<0001> <0041>\nendbfchar, this scanner stops at %. hexAt then fails, and embedMissing leaves the font unresolved. Removing the comment makes the same mapping succeed.

Skip comments during tokenization and section discovery. Add regressions for comments in bfchar and bfrange blocks.

for (auto [gid, u] : unicodeByGlyph(program.face, symbolic)) codes[gid] = u;
std::map<uint32_t, FT_UInt> gidByCid;
uint32_t maxCid = 0;
for (auto [code, u] : cidUnicode) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

Preserve ToUnicode generation for explicit embedding.

PdfFontEmbedder.embed passes onlyMissing=false. Consequently, cidUnicode remains empty, and this loop never populates codes. (raw.githubusercontent.com)

For an unembedded Identity-H TrueType font without /ToUnicode, the immediate-base implementation generated mappings from unicodeByGlyph. This change installs the program without generating those mappings. Text using CID 36 for A therefore loses the generated CID-to-Unicode association. (raw.githubusercontent.com)

Keep the inverse-glyph mapping path for explicit embedding when /ToUnicode is absent. Add a regression that embeds the original program and checks extraction after reopening.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
@balazs-szucs
balazs-szucs force-pushed the refactor/font-03-agl-names branch from 7a104b4 to cf0753b Compare November 19, 2026 12:56

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant