Fix: resolve AGL underscore ligature glyph names (f_i/f_l/f_f/...)

[Malcolmnixon]

Pull Request

Description

Fixes the still-broken half of the beta.7 real-world glyph-gap report:
/Differences arrays naming a ligature glyph via the Adobe Glyph List's
underscore ligature-naming convention (f_i, f_l, f_f, f_f_i,
f_f_l - two or more component glyph names joined by underscores) were
left unresolved, so the affected glyphs rendered as missing/tofu boxes
even though StandardGlyphNames already had a dedicated codepoint for
the same ligature under its own AGL name (fi, fl, ff, ffi,
ffl). PR #35 already fixed the non-ligature uniXXXX/thinspace
half of this report; this closes the remaining gap.

Adds TryResolveLigatureUnderscoreName: resolves each underscore-
separated component recursively (so a component may itself use the
uniXXXX/uXXXX hex convention), concatenates the resolved characters,
and looks the concatenated string up as an AGL glyph name in
StandardGlyphNames.

The existing real-world text-type1c-differences-agl-ligatures.pdf
fixture already exercised an /f_f ligature in its content stream
(previously documented as a deliberate, out-of-scope limitation); it
now resolves and paints correctly, proving the fix against both a
synthetic regression test and a genuine real-world embedded font.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Closes #

Pre-Submission Checklist

Build and Test

• Code builds successfully and all tests pass: pwsh ./build.ps1 - all tests passed, 0 failures, 0 regressions
• Code produces zero warnings

Code Quality

• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

• All linters pass: pwsh ./lint.ps1 - clean (markdownlint, cspell, yamllint, dotnet format, reqstream, versionmark, reviewmark, sysml2tools)

Testing

• Added unit tests for new functionality (f_i/f_l/f_f/f_f_i/f_f_l resolving end-to-end against an embedded Type1C font, plus an unrecognized-underscore-name fallback case)
• Updated existing tests if behavior changed (fixture README/test remarks updated to reflect the formerly out-of-scope /f_f case now resolving)
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable) - N/A, no end-user-visible API change
• Updated docs/ documentation (reqstream/verification docs and fixture README updated)
• Added code examples for new features (if applicable) - N/A
• Updated requirements.yaml (if applicable) - N/A, no new top-level requirement; extends existing FontEncoding/Type1CFontResolution requirements

Additional Notes

Follow-up to PR #35 (PDF Type1C/Differences glyph lookup). Queued behind the PPTX Phase 1a-1d work per explicit sequencing instruction.

[Copilot]

Copilot review overview

🟡 Changes recommended

Reject surrogate-range component values before UTF-32 conversion to prevent rendering failures.

Review effort: Lite
Findings: 1

Open (1)

• Reject surrogate values before char.ConvertFromUtf32 · New

What changed in this PR

Adds AGL underscore-ligature resolution for PDF /Differences glyph names.

Changes:

• Implements recursive ligature component resolution.
• Adds regression tests and fixture coverage.
• Updates verification and requirements documentation.

File	Summary
test/​DemaConsulting.CanvasNet.Pdf.Tests/​PdfFixtures/​README.md	Updates fixture behavior documentation.
test/​DemaConsulting.CanvasNet.Pdf.Tests/​PdfDocumentTests.cs	Adds ligature regression tests.
src/​DemaConsulting.CanvasNet.Pdf/​PdfDocument.Fonts.cs	Implements underscore-ligature resolution.
docs/​verification/​canvas-net-pdf/​pdf-document.md	Updates verification coverage.
docs/​reqstream/​canvas-net-pdf/​pdf-document.yaml	Updates requirements traceability.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Add mixed hex-component test coverage and correct overclaimed fixture verification/documentation.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Reject surrogate values before char.ConvertFromUtf32

Previously missed (3)

In code that hasn't changed since last review

Test hex-named components in the fallback theory

test/​DemaConsulting.CanvasNet.Pdf.Tests/​PdfDocumentTests.cs:7712

The implementation explicitly supports hex-named components (for example uni0066_uni0069), but this theory only exercises literal f/i/l components. Add at least one such case so a regression in the component-to-codepoint fallback cannot pass the entire new test coverage.

Fixture assertion cannot prove /f_f resolves

docs/​verification/​canvas-net-pdf/​pdf-document.md:1245

The verification text says the broad real-world fixture now proves /f_f resolves, but its test only uses AssertPaintedSomePixel while the page also exercises /uni03BC and /thinspace; that assertion cannot distinguish a resolved ligature from a tofu glyph. Please add a glyph-specific check or qualify this statement so the verification record does not claim coverage the test does not provide.

Fixture test overstates proof of /f_f resolution

test/​DemaConsulting.CanvasNet.Pdf.Tests/​PdfFixtures/​README.md:151

This updated note overstates what the real-world fixture test proves: PdfDocument_Load_TextType1CDifferencesAglLigaturesFixture_PaintsVisibleGlyphInk only asserts that some pixel is painted, and the same page also contains /uni03BC and /thinspace, so it can pass even if /f_f remains unresolved. Please either add a glyph-specific assertion for the /f_f occurrence or soften this to say that the fixture contains the name; the theory test is the actual isolated coverage today.

[Copilot]

Copilot review overview

🔵 Needs a closer look

One or more issues must be addressed before approval.

Review effort: Lite
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Keep the explanatory dash inline to preserve Markdown rendering

docs/​verification/​canvas-net-pdf/​pdf-document.md:1544

This line starts with - , so Markdown renders the continuation as a new unordered-list item instead of the closing dash in the surrounding sentence. Keep the dash inline with the preceding paragraph (or otherwise indent/escape it) so this explanation renders as a single sentence.