feat(templates): classify CV presets as ATS-friendly or design-first

[DemchaAV]

Builds on #688, now merged. The parser results below depend on its letter-spacing fix, without which tracked headings still split into letters in pdf.js and pdfplumber.

Why

A resume parser reads a CV before a person does. Several take the name and the email from the lines stored above the first section heading, and a parser recognises a section by matching its heading against a short list of names. Several CV presets defeated one of those steps with nothing wrong on the page:

• Five presets print headings of their own that no parser's list contains, such as "EMPLOYMENT HISTORY", "Core Stack" and "EXPERTISE". The showcase samples used titles such as "Education & Certifications" and "CORE COMPETENCIES".
• Navy Sidebar, Charcoal Gold and Sidebar Portrait drew the sidebar before the name, and Slate Orange drew its monogram tile first. OpenResume and resume-parser-ats took "CONTACT", "DH" or a contact line for the name.
• Professional Sidebar and Terracotta Rail composed their two columns as one atomic row, so a CV longer than one sheet raised AtomicNodeTooLargeException instead of rendering.

The showcase also had no way to tell a CV that parses from one whose sidebar or columns cost a parser a check.

What changed

Ten commits, in review order:

1. fix(examples): the sample CV titles its education section "Education". Eight presets print that title, so their previews, pixel baselines and layout snapshots change with it. CvPresetFixtures.canonicalDocument mirrors the sample.
2. test(qa): re-records the Teal Pulse, Terracotta Rail and Violet Grid pixel baselines. fix(templates): preserve semantic text when applying letter spacing #682 changed how these presets draw letter-spaced lines but did not re-record their baselines. The drift stayed inside the 50 000-pixel budget. Content and layout snapshots are unchanged.
3. fix(templates): five presets print the headings parsers look for. The presets are ClassicSerif, EditorialBlue, SidebarPortrait, MonogramSidebar and EngineeringResume, and five samples now title their skills "SKILLS". Only the words change; every heading keeps its font, colour, tracking and rules.
4. fix(templates): four sidebar CVs draw the name first.
   • In Navy Sidebar, Charcoal Gold and Sidebar Portrait, package-private ReadingOrderColumns turns the page grid into a layer stack. The stack is atomic like the row it replaces. It draws the name, then the sidebar, then the rest of the main column under a stand-in as tall as the name.
   • Drawing the whole main column first would cost the email instead, because its first heading would then come before the sidebar's contact lines.
   • Slate Orange's masthead cells become layers, identity strip first.
5. feat(templates): Professional Sidebar and Terracotta Rail carry a longer CV onto more pages.
   • Package-private ColumnPages measures each block on its own: a role, a project, a sidebar list, and the hairline that leads it. It packs the blocks one row per page.
   • Every row after the first starts behind a page break. A block that opens a page leaves its hairline behind, so without the break a short last row could settle under the row before it.
   • A CV that fits keeps its single row, to within the 0.5pt the paginator allows an atomic block. Its output and one-page layout snapshot do not change.
   • A block taller than a page is refused, and the error names the block.
   • The education rail moves to ProfessionalSidebarEducation and the projects grid to TerracottaRailProjects, which keeps both column classes under 500 lines.
6. feat(examples): the showcase marks the presets that earned an ATS-friendly badge.
   • ShowcaseMetadata classifies every CV card with an AtsStatus, the parsers used, the date checked and the known limitations. ShowcaseSync writes this as an ats object on CV cards only.
   • web/examples.js draws an "ATS-friendly" chip only when the manifest marks the badge and the status is ATS_CERTIFIED or ATS_COMPATIBLE_WITH_KNOWN_PARSER_LIMITATIONS. The chip links to the new section in using-templates.md.
   • web/examples.json is regenerated by the release, so it is not in this diff.
7. docs(changelog) records the changes above. It also corrects four earlier v2.4.0 entries that these changes made untrue: Professional Sidebar and Terracotta Rail no longer stop at one page, and Navy Sidebar's columns are a layer stack.
8. test(examples): each ATS-friendly badge is pinned to the exact PDF its check read.
   • A hash of the extracted text misses a rendering change that keeps the words. A block moved beside another, a line redrawn or a content stream reordered can change what pdf.js or pdfplumber read.
   • For each badged sample, ats-validated-samples.properties records the preset, the status, validatedAt, the SHA-256 of the exact PDF ats-check read, and a text hash beside it. The file is read fail-closed.
   • ShowcaseAtsClassificationTest holds each record to its card's preset and to the date its badge shows. A badged card without a record fails; a design-first card needs none.
9. test(examples): the certified render lives in the test, and each published sample is held to it.
   • The examples keep buildPdf(), because the runnable-examples guard reads any .render( call in an example as the removed legacy PDF API. Their committed previews keep the files they had.
   • ShowcaseAtsSamples composes each badged sample the way its example does: the preset's default template on A4 at its recommended margin, from the shared sample CV. It renders the sample through PdfFixedLayoutBackend.builder().deterministic(true), which pins the document dates and derives the /ID from the metadata.
   • ShowcaseAtsEvidenceTest writes those renders to examples/target/ats-certification and requires each one's SHA-256 to equal the recorded hash.
   • It also requires the sample each example publishes to draw the same document page by page: size, content stream, fonts and links.
   • Both failures say the ATS check must be run on those renders again.
10. fix(examples): a badged sample's text hashes the same way on every platform. PDFTextStripper ends every page with the platform's line separator, which setLineSeparator does not change. Both strippers now end pages with \n, and the eight text hashes are recomputed from the certified PDFs. The PDF hashes are unchanged.

Before → after

Every CV showcase sample was read with three parsers:

• the OpenResume parser (pdf.js 3.7.107)
• ATS Reader (pdfplumber 0.11.10)
• resume-parser-ats 1.2.3 (pdf-parse)

Each sample was held to these checks:

• the text extracts and no parser fails;
• all three parsers find the name;
• Experience, Education and Skills are recognised;
• reading order passes in all three parsers;
• no words are split;
• the name and the email are in the text layer.

Classification	Presets
ATS-friendly, every check met (7)	Blue Banner, Boxed Sections, Centered Headline, Classic Serif, Editorial Blue, Executive, Minimal Underlined
ATS-friendly, known parser limitation (1)	Modern Professional: ATS Reader does not recognise "Professional Experience" or "Technical Skills" as headings. The other two parsers do.
Design-first (18, plus the Mint Editorial custom card)	every other CV preset

• Classic Serif and Editorial Blue meet every check because of commit 3.
• The name as read by OpenResume / ATS Reader / resume-parser-ats (✓ right, ~ partly right, ≠ wrong):
  • Sidebar Portrait: ≠✓≠ → ✓✓✓
  • Slate Orange: ≠✓✓ → ✓✓✓
  • Navy Sidebar: ≠✓≠ → ≠✓✓
  • Charcoal Gold: ≠~≠ → ~~~
• Professional Sidebar and Terracotta Rail render a full-length CV instead of refusing it.
• Every design-first preset keeps a miss its layout causes: ATS Reader interleaves the sidebar or the columns, or two headings on one baseline fuse. Removing that miss means flattening the design, so those presets stay design-first.
• The eight badged samples were read with ats-check again, as the exact files now recorded. Every parser result and verdict matches the earlier check.

Verification

• ./mvnw -B -ntp clean install -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-templates,:graph-compose-testing,:graph-compose,:graph-compose-bundle,:graph-compose-qa,:graph-compose-coverage -am → BUILD SUCCESS. The documentation guards are part of the core and qa counts.

  Module	Tests
  core	762 (2 skipped)
  render-pdf	274
  render-docx	94
  testing	5
  render-pptx	138
  templates	127
  qa	1777

• ./mvnw -B -ntp -f examples/pom.xml clean test → 87 tests, including CommittedAssetDriftTest.

• Knowledge pack checks all pass:

  • extract-api.mjs --from-reactor --check reports the surfaces current, so no public API changed.
  • check-stability-doc.mjs, check-claims.mjs --check and check-routes.mjs pass, and so do the five fixture suites.

• CI on this head passes every check, including build-and-test on JDK 17, 21 and 25, the examples job and the performance smoke check.

• New and extended tests:

  • ColumnPagesTest covers packing, the first-page budget, the page handoff, the one-page allowance, an oversized block and duplicate names.

  • ProfessionalSidebarSmokeTest and TerracottaRailSmokeTest:

    • a long CV paginates;
    • a role taller than the page is refused, and the error names it;
    • Professional Sidebar also pins a CV whose last role only just overflows.

    Each preset also gains a two-page layout snapshot.

  • CvPresetTextLayerTest.theNameIsTheFirstTextInTheFile holds the four presets to drawing the name first. With a sidebar-first preset added to its list, qa fails on that case alone.

  • ReadingOrderColumnsTest holds measure() to putting the caller's roots back.

  • ShowcaseAtsClassificationTest checks that:

    • every CV card is classified, and no other card is;
    • the badged presets and their statuses match the certified samples;
    • each record names its card's preset and the date its badge shows;
    • each classification has a date, at least two parsers and written limitations;
    • the manifest's badge flag and link are right;
    • the guide's table and the README agree with the register.

  • ShowcaseAtsEvidenceTest requires three things: every generated CV document is classified; every badged sample's certification render is byte-identical to the PDF its ATS check read; every published badged sample draws that same document page by page. Each of these turns it red:

    • a changed recorded hash;
    • a 0.5pt sideways shift in a badged example that leaves its text identical, reported as a different content stream and different links;
    • a removed hash.

• Output:

  • PDFium at 100 dpi shows 0 px changed in all four name-first presets. Commit 4 re-records their layout snapshots for structure only and moves no pixel baseline.
  • Pixel baselines, previews and layout snapshots were re-recorded where a heading's words changed (commits 1 and 3), and for the three baselines in commit 2.
  • The certification renders are byte-identical on Oracle JDK 24 and Corretto 17 on Windows, on Temurin 21 on Linux, and in CI's examples job on Temurin 17. Against the earlier certified files, only the dates and /ID differ; pages, content streams and fonts are identical.

Notes for review

• A badge speaks for the showcase sample only, read on 2026-09-14. A CV with different content can parse differently, and a badge is not a claim about every ATS product. The guide says both.
• A changed PDF means a new ATS check. When a badged sample's render stops matching its recorded hash, or its published file stops matching the render, the test says to run ats-check on the renders under examples/target/ats-certification, review the result, and only then record new evidence. It never updates a hash itself.
• The certification renders use a @Beta option. deterministic(...) is @Beta on PdfFixedLayoutBackend.Builder. If its output changes, the renders change and the guard fails rather than passing.
• Phone and email rows are not checked. Most presets' phone numbers are found by none of the parsers, and resume-parser-ats returns the whole contact row as the email in several presets. A badge says nothing about either.
• Two of the three parsers share pdf.js. OpenResume and resume-parser-ats both extract text with pdf.js (3.7.107 and 1.10.100) before applying their own heuristics. ATS Reader uses pdfplumber.
• Most of the added lines are snapshots. About 16 000 are the two new long-CV layout snapshots. The Charcoal Gold, Navy Sidebar, Sidebar Portrait and Slate Orange snapshots move because their nodes are now layers.
• No public API changes. ColumnPages and ReadingOrderColumns are package-private, ShowcaseAtsSamples is examples test code, and ShowcaseMetadata and ShowcaseSync live in the unpublished examples module.

Lane: templates — CV presets and their gates, the showcase catalogue and one guide section; no public API change.