brevier 0.1.0__tar.gz

brevier-0.1.0/.githooks/commit-msg

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Enforces AGENTS.md's commit conventions: subject must reference a real
+# issue number, subject must be short, body must stay short (a one-line
+# reason at most, not a rewritten copy of the issue). Installed via
+# `git config core.hooksPath .githooks` (see README/CONTRIBUTING).
+set -eu
+
+MSG_FILE="$1"
+SUBJECT=$(sed -n '1p' "$MSG_FILE")
+SUBJECT_LEN=$(printf '%s' "$SUBJECT" | wc -c)
+
+# Body = all non-blank lines after the first blank line following the subject.
+BODY_LINES=$(awk 'NR==1{next} /^$/{seen_blank=1; next} seen_blank && NF{count++} END{print count+0}' "$MSG_FILE")
+
+FAIL=0
+
+if ! printf '%s' "$SUBJECT" | grep -qE '#[0-9]+'; then
+  echo "commit-msg: subject line must reference a real issue number, e.g. 'feat: add hyphenation ranking (#12)'" >&2
+  FAIL=1
+fi
+
+if [ "$SUBJECT_LEN" -gt 73 ]; then
+  echo "commit-msg: subject line is $SUBJECT_LEN chars, keep it under ~72" >&2
+  FAIL=1
+fi
+
+if [ "$BODY_LINES" -gt 5 ]; then
+  echo "commit-msg: commit body has $BODY_LINES content lines — keep it to a short reason, not a rewritten issue. Long explanation belongs in the issue, not the commit." >&2
+  FAIL=1
+fi
+
+exit $FAIL

brevier-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,52 @@
+---
+name: Bug
+about: Something is broken, with a known or suspected reproduction
+title: '[BUG] '
+labels: bug
+---
+
+<!-- Before opening this issue:
+     Short sentences, plain words, facts and numbers. No filler.
+     Labels: one type (set by this template) and one priority, P0-critical
+     to P3-low. Assign the issue. The sprint is the milestone: sprint-N
+     labels are retired, do not add one.
+     Project board: set Status, Priority, Size, Estimate, Start date and
+     Target date. Size and Estimate come from the points or hours below. -->
+
+## Bug
+<!-- What is broken and how to see it: reproduction steps, a command, or a
+     log excerpt. Say whether it is confirmed live or only suspected. -->
+
+## Root Cause
+<!-- Fill in once known. Delete this section while still investigating. -->
+
+## Severity vs. Priority
+<!-- Two axes, set independently. A low-severity bug can be P0 when it
+     blocks a release. A Blocker-severity bug in dead code can be P3.
+
+     The priority written here and the P0-critical to P3-low label on the
+     issue must agree. -->
+**Severity (technical impact):** Blocker / Critical / Major / Minor
+**Priority (business urgency):** P0 / P1 / P2 / P3
+
+## Acceptance Criteria
+<!-- At most 5, each independently checkable, each naming the test or
+     command that proves it. A date is not a proof.
+
+     Two more rules for a Bug specifically:
+     "Fixed and verified live" means you drove the broken path and watched
+     it work, not that the diff looks right. If the bug is in generated
+     code, verify against the golden-project build, not a template unit
+     test alone.
+     The regression test is the criterion most often ticked without the
+     test existing. Name it, and break the fix once to watch it fail. -->
+- [ ] Fixed, and the fixed path verified through the layer the bug was in
+      (`<test or command>`)
+- [ ] Regression test added, seen failing before it passed (`<test name>`)
+
+## Notes
+<!-- Decisions, rescopes, follow-up issue numbers. Delete if there are
+     none. Not a running log.
+
+     Bugs sit outside the Epic to Story to Task hierarchy, so there is no
+     parent section here by design. -->

brevier-0.1.0/.github/ISSUE_TEMPLATE/epic.md

@@ -0,0 +1,39 @@
+---
+name: Epic
+about: A large body of work spanning several sprints, broken into Stories
+title: '[EPIC] '
+labels: epic
+---
+
+<!-- Before opening this issue:
+     Short sentences, plain words, facts and numbers. No filler.
+     Labels: one type (set by this template) and one priority, P0-critical
+     to P3-low. Assign the issue. The sprint is the milestone: sprint-N
+     labels are retired, do not add one.
+     Project board: set Status, Priority, Size, Estimate, Start date and
+     Target date. Size and Estimate come from the points or hours below. -->
+
+## Epic
+<!-- The outcome this epic delivers. Name what exists at the end, not the
+     slot in the schedule it occupies. -->
+
+## Business Value
+<!-- Why it matters, in one or two sentences. -->
+
+## Product Goal alignment
+<!-- Which Product Goal (docs/process/PRODUCT_GOAL.md) this serves.
+     "Indirect: ..." is a valid answer for tooling and maintenance work.
+     Write that rather than deleting the section. -->
+
+## Closing this Epic
+<!-- Child Stories are the native sub-issue links and nothing else. Add
+     them from the Sub-issues panel on this Epic. There is no markdown list
+     here on purpose — it duplicates the panel and drifts.
+
+     Do not close this Epic while a sub-issue is open. Do not leave it open
+     once they are all closed. Tasks hang off Stories, never off an Epic. A
+     Story that was dropped rather than delivered gets one line in Notes. -->
+
+## Notes
+<!-- Decisions, rescopes, follow-up issue numbers. Delete this section if
+     there are none. Not a running log. -->

brevier-0.1.0/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,52 @@
+---
+name: Task
+about: A technical subtask under a Story, or standalone technical work
+title: '[TASK] '
+labels: task
+---
+
+<!-- Before opening this issue:
+     Short sentences, plain words, facts and numbers. No filler.
+     Labels: one type (set by this template) and one priority, P0-critical
+     to P3-low. Assign the issue. The sprint is the milestone: sprint-N
+     labels are retired, do not add one.
+     Project board: set Status, Priority, Size, Estimate, Start date and
+     Target date. Size and Estimate come from the points or hours below. -->
+
+## Task
+<!-- What needs doing, and why, in a few sentences or bullets. -->
+
+## No parent
+<!-- Delete this whole section when the Task has a Story. The native
+     sub-issue link is the parent record; a markdown copy is a second thing
+     to keep in sync.
+
+     Keep it only for a deliberate "no parent" decision, replacing this
+     comment with the one-line reason.
+
+     Set the parent from the Story: Sub-issues, Add existing issue. -->
+
+## Scope
+<!-- Only when it is not obvious what is excluded. Name the sibling issue
+     that owns anything deliberately left out. Delete otherwise. -->
+
+## Acceptance Criteria
+<!-- At most 5, each independently checkable, each naming the test or
+     command that proves it. A date is not a proof.
+
+       - [ ] `npm run compile` succeeds with the new command registered
+             (`extension.activation.test.ts`)
+
+     Prefer a test CI already runs. If nothing can prove it, say so:
+     (manual: exact steps) or (no test: reason). One manual criterion per
+     issue at most. Do not close with a box unchecked. -->
+- [ ] <criterion> (`<test or command>`)
+- [ ] <criterion> (`<test or command>`)
+
+## Estimate
+**Hours:** <hours, not points. Points size a Story; hours size the work of
+implementing one Task inside a sprint.>
+
+## Notes
+<!-- Decisions, rescopes, follow-up issue numbers. Delete this section if
+     there are none. Not a running log. -->

brevier-0.1.0/.github/ISSUE_TEMPLATE/user-story.md

@@ -0,0 +1,71 @@
+---
+name: User Story
+about: A vertical slice of user-facing value, the real requirements unit
+title: '[STORY] As a <role>, I want <goal> so that <benefit>'
+labels: user-story
+---
+
+<!-- Before opening this issue:
+     Short sentences, plain words, facts and numbers. No filler.
+     Labels: one type (set by this template) and one priority, P0-critical
+     to P3-low. Assign the issue. The sprint is the milestone: sprint-N
+     labels are retired, do not add one.
+     Project board: set Status, Priority, Size, Estimate, Start date and
+     Target date. Size and Estimate come from the points or hours below. -->
+
+## User Story
+**As a** <role>
+**I want** <goal>
+**So that** <benefit>
+
+<!-- INVEST before this enters the backlog: Independent, Negotiable,
+     Valuable, Estimable, Small, Testable. If it fails Small or Estimable,
+     split it rather than forcing a sixth criterion. -->
+
+## No parent
+<!-- Delete this whole section when the Story has an Epic. The native
+     sub-issue link is the parent record; a markdown copy is a second thing
+     to keep in sync.
+
+     Keep it only for a deliberate "no parent" decision, replacing this
+     comment with the one-line reason.
+
+     Set the parent from the Epic: Sub-issues, Add existing issue. -->
+
+## Acceptance Criteria (Given/When/Then)
+<!-- At most 5, each independently checkable.
+
+     Every criterion names the test or command that proves it, in brackets
+     at the end:
+
+       - [ ] Given an invoice with 60 rows, when it renders, then the
+             table header repeats on page 2 (`test_table_header_repeats`)
+
+     A date is not a proof. Prefer a test CI already runs. A repeatable
+     command is acceptable when a test genuinely cannot cover it. If
+     nothing can prove it, say so: (manual: exact steps) or (no test:
+     reason). One manual criterion per issue at most.
+
+     Do not close with a box unchecked. Check each one against the code,
+     not against what this issue used to say. -->
+- [ ] Given <context>, when <action>, then <outcome> (`<test or command>`)
+- [ ] Given <context>, when <action>, then <outcome> (`<test or command>`)
+
+## Definition of Ready
+- [ ] Meets [Definition of Ready](https://github.com/liviuionesi/brevier/blob/develop/docs/process/DEFINITION_OF_READY.md)
+
+## Story Points
+**Estimate:** <Fibonacci: 1 / 2 / 3 / 5 / 8 / 13 / 21>
+<!-- The sprint is the GitHub Milestone. There is no Sprint section here. -->
+
+## Closing this Story
+<!-- Technical Tasks are the native sub-issue links and nothing else, for
+     the same reason as the Epic template. Do not close this Story while a
+     child Task is open. -->
+
+## Definition of Done
+- [ ] Meets [Definition of Done](https://github.com/liviuionesi/brevier/blob/develop/docs/process/DEFINITION_OF_DONE.md)
+
+## Notes
+<!-- Decisions, rescopes, follow-up issue numbers. Delete this section if
+     there are none. Not a running log. -->

brevier-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,59 @@
+# Pull Request
+
+## Description
+<!-- What changed, in a few lines. -->
+
+## Related Issue
+Closes #<!-- issue number -->
+
+## Type of Change
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 💥 Breaking change
+- [ ] 📝 Documentation
+- [ ] 🔧 Configuration
+- [ ] ♻️ Refactoring
+- [ ] ✅ Test improvement
+
+## Area(s) Affected
+- [ ] Composer (classes, template or PDF in, schema out)
+- [ ] Preparer (data cleaning, hyphenation, binding)
+- [ ] Engine (layout, pagination, PDF out)
+- [ ] Themes (DIN 5008, web)
+- [ ] PDF import
+- [ ] Linter
+- [ ] CLI
+- [ ] Java client
+- [ ] Packaging / CI
+- [ ] Documentation
+
+## Testing Performed
+- [ ] Tests added or updated (`pytest`, `./gradlew test`)
+- [ ] Golden render gate checked, if this can move a pixel
+      (`docs/process/DEFINITION_OF_DONE.md`)
+- [ ] Output opened and looked at, not only asserted
+
+## Code Quality
+- [ ] `ruff check` and `ruff format --check` clean
+- [ ] `mypy` clean for touched code
+- [ ] Self-review done
+- [ ] Docstrings / Javadoc per `AGENTS.md`
+- [ ] No debug prints left behind
+- [ ] Errors handled, not swallowed
+
+## Documentation
+- [ ] README updated, if needed
+- [ ] `docs/PRD.md` updated with a version history row, if the product changed
+- [ ] New architecture decision written as an ADR under `docs/architecture/adr/`
+
+## Security
+- [ ] No secrets in code, logs or debug output
+- [ ] No customer data written anywhere by default (PRD risk R8)
+- [ ] No font file extracted or redistributed (PRD risk R7)
+- [ ] Dependency scan clean for new or changed dependencies
+
+## Before Merge
+- [ ] CI passing
+- [ ] Review comments addressed
+- [ ] Branch up to date with `develop`
+- [ ] Issue resynced to real implementation state

brevier-0.1.0/.github/workflows/cross-os-proof.yml

@@ -0,0 +1,133 @@
+# Does the engine actually render on Linux, macOS and Windows?
+#
+# ADR 002 commits Brevier to all three operating systems, but only Linux was
+# ever tested. This workflow answers the question for the other two before
+# the product is built on the assumption.
+#
+# Manual trigger only. macOS runner minutes bill at 10x and Windows at 2x on
+# a private repository, so this must never fire on every push.
+name: cross-os-proof
+
+on:
+  workflow_dispatch:
+
+jobs:
+  render:
+    name: render on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One platform failing must not hide the result of the other two —
+      # the whole point is to learn where it breaks.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      # --- the native font stack, obtained the way each platform does it ---
+
+      - name: Linux — font stack from apt
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 \
+            libharfbuzz0b libfontconfig1 fonts-dejavu-core
+
+      - name: macOS — font stack from Homebrew
+        if: runner.os == 'macOS'
+        run: |
+          brew install pango
+          echo "DYLD_FALLBACK_LIBRARY_PATH=$(brew --prefix)/lib" >> "$GITHUB_ENV"
+
+      - name: Windows — font stack from MSYS2
+        if: runner.os == 'Windows'
+        uses: msys2/setup-msys2@v2
+        id: msys2
+        with:
+          msystem: UCRT64
+          update: true
+          install: mingw-w64-ucrt-x86_64-pango
+
+      - name: Windows — tell WeasyPrint where the DLLs are
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          # WEASYPRINT_DLL_DIRECTORIES is WeasyPrint's own supported way to
+          # point at the native libraries, which is why Windows needs no
+          # equivalent of the Linux runtime hook in ADR 001.
+          echo "WEASYPRINT_DLL_DIRECTORIES=${{ steps.msys2.outputs.msys2-location }}\\ucrt64\\bin" >> "$GITHUB_ENV"
+
+      # --- the engine itself, pinned so the comparison means something ---
+
+      - name: Install WeasyPrint
+        shell: bash
+        run: python -m pip install --quiet "weasyprint==70.0" "pypdf>=5,<7"
+
+      - name: Fetch identical font files, pinned by commit
+        shell: bash
+        env:
+          # A fixed commit in google/fonts, so the font bytes cannot move.
+          FONTS_COMMIT: 8b0a1d0f5983c89bc2b93f1b5fb55f9e252744b5
+          SANS_SHA256: bfb7bb691513f12e734dc346c03a03f784912432d7e3fa8e56efcf906fe86b3d
+          SERIF_SHA256: 4d8e6761424656867019081a1a01336f3cb086982682698714054fc33f782713
+        run: |
+          mkdir -p tests/fixtures/fonts
+          base="https://raw.githubusercontent.com/google/fonts/$FONTS_COMMIT/ofl"
+          curl -sSL -o tests/fixtures/fonts/NotoSans.ttf  "$base/notosans/NotoSans%5Bwdth%2Cwght%5D.ttf"
+          curl -sSL -o tests/fixtures/fonts/NotoSerif.ttf "$base/notoserif/NotoSerif%5Bwdth%2Cwght%5D.ttf"
+          # Prove the input was byte-identical here, so a difference in the
+          # output later cannot be blamed on a different font file.
+          digest() { python -c "import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" "$1"; }
+          sans=$(digest tests/fixtures/fonts/NotoSans.ttf)
+          serif=$(digest tests/fixtures/fonts/NotoSerif.ttf)
+          echo "  NotoSans.ttf : $sans"
+          echo "  NotoSerif.ttf: $serif"
+          test "$sans" = "$SANS_SHA256" || { echo "NotoSans differs on this runner"; exit 1; }
+          test "$serif" = "$SERIF_SHA256" || { echo "NotoSerif differs on this runner"; exit 1; }
+          echo "font input is identical on this runner"
+
+      - name: Render with the platform's own fonts
+        shell: bash
+        run: python tests/cross_os_check.py tests/fixtures/hello.html "out-system-${{ runner.os }}.pdf"
+
+      - name: Render with identical bundled fonts
+        shell: bash
+        run: python tests/cross_os_check.py tests/fixtures/hello-bundled.html "out-bundled-${{ runner.os }}.pdf"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pdf-${{ runner.os }}
+          path: out-*.pdf
+
+  compare:
+    name: compare the three PDFs
+    needs: render
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: pdfs
+
+      - name: Checksums across operating systems
+        run: |
+          for kind in system bundled; do
+            echo "=============================================================="
+            if [ "$kind" = system ]; then
+              echo "Each platform used ITS OWN fonts:"
+            else
+              echo "Every platform used the SAME font files:"
+            fi
+            find pdfs -name "out-$kind-*.pdf" -print0 | sort -z | xargs -0 sha256sum
+            count=$(find pdfs -name "out-$kind-*.pdf" | wc -l)
+            unique=$(find pdfs -name "out-$kind-*.pdf" -print0 | xargs -0 sha256sum | awk '{print $1}' | sort -u | wc -l)
+            echo "-> $count PDFs, $unique distinct checksum(s)."
+            echo
+          done
+          echo "Reminder: identical bytes need identical fonts AND identical"
+          echo "native library versions. See ADR 003."

brevier-0.1.0/.github/workflows/pip-install-proof.yml

@@ -0,0 +1,220 @@
+# Does `pip install brevier` give a working `brevier` command?
+#
+# Epic #38's proof: in a folder holding only hello.html and hello.css,
+# `brevier render hello.html -o hello.pdf` writes hello.pdf into that same
+# folder. This workflow builds the wheel once, then runs that proof on
+# Linux, macOS and Windows, on Python 3.10 (the floor) and 3.13, in a fresh
+# virtual environment with nothing else from this repo. `brevier --version`
+# alone does not count — it works even without Pango (ADR 001).
+#
+# It also renders hello-bundled.html (fonts pinned with @font-face, one
+# Python version, one run per OS) and compares those three PDFs' content.
+# hello.html cannot be compared this way: without a pinned font, each OS
+# resolves "Noto Sans" to a different substitute and draws a different page
+# (ADR 002, "Fonts decide the result") — that is real, not a bug, so the
+# content check needs the fixture that removes it.
+#
+# `source: pypi` swaps the wheel for a real `pip install brevier` from
+# PyPI, to prove a tagged release too, not just the local build.
+#
+# Manual trigger and version tags only: macOS runner minutes bill at 10x
+# and Windows at 2x on a private repo (see cross-os-proof.yml).
+name: pip-install-proof
+
+on:
+  workflow_dispatch:
+    inputs:
+      source:
+        description: "Install brevier from the wheel this run builds, or from PyPI"
+        type: choice
+        options: [wheel, pypi]
+        default: wheel
+  push:
+    tags:
+      - "v*.*.*"
+
+env:
+  # A fixed date, so two runs of the same input cannot differ by timestamp
+  # (ADR 002, rule 2).
+  SOURCE_DATE_EPOCH: "1700000000"
+  # pypdf pin shared with cross-os-proof.yml, for the same reason: only the
+  # check scripts use it, so an unpinned range should never be why a run
+  # fails.
+  PYPDF_SPEC: "pypdf>=5,<7"
+
+jobs:
+  build:
+    name: build the wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --quiet build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/*.whl
+          if-no-files-found: error
+
+  install:
+    name: install on ${{ matrix.os }}, Python ${{ matrix.python-version }}
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One combination failing must not hide the result of the other five.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # --- Pango, obtained the way each platform does it (ADR 001) ---
+
+      - name: Linux — font stack from apt
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 \
+            libharfbuzz0b libfontconfig1 fonts-dejavu-core
+
+      - name: macOS — font stack from Homebrew
+        if: runner.os == 'macOS'
+        run: |
+          brew install pango
+          echo "DYLD_FALLBACK_LIBRARY_PATH=$(brew --prefix)/lib" >> "$GITHUB_ENV"
+
+      - name: Windows — font stack from MSYS2
+        if: runner.os == 'Windows'
+        uses: msys2/setup-msys2@v2
+        id: msys2
+        with:
+          msystem: UCRT64
+          update: true
+          install: mingw-w64-ucrt-x86_64-pango
+
+      - name: Windows — tell WeasyPrint where the DLLs are
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          # WEASYPRINT_DLL_DIRECTORIES is WeasyPrint's own supported way to
+          # point at the native libraries (ADR 001).
+          echo "WEASYPRINT_DLL_DIRECTORIES=${{ steps.msys2.outputs.msys2-location }}\\ucrt64\\bin" >> "$GITHUB_ENV"
+
+      # --- a fresh virtual environment, with nothing else from this repo ---
+
+      - name: Create the virtual environment
+        shell: bash
+        run: |
+          python -m venv .venv
+          # Windows' venv lays out Scripts/, not bin/ — record whichever
+          # this OS used, as an absolute path so it survives a later `cd`.
+          if [ -d "$PWD/.venv/bin" ]; then
+            echo "VENV_BIN=$PWD/.venv/bin" >> "$GITHUB_ENV"
+          else
+            echo "VENV_BIN=$PWD/.venv/Scripts" >> "$GITHUB_ENV"
+          fi
+
+      # --- install brevier itself, from the wheel or from PyPI ---
+
+      - uses: actions/download-artifact@v4
+        if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.source == 'pypi') }}
+        with:
+          name: wheel
+          path: dist
+
+      - name: Install brevier from the wheel this run built
+        if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.source == 'pypi') }}
+        shell: bash
+        run: '"$VENV_BIN/python" -m pip install --quiet dist/*.whl "$PYPDF_SPEC"'
+
+      - name: Install brevier from PyPI
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.source == 'pypi' }}
+        shell: bash
+        run: '"$VENV_BIN/python" -m pip install --quiet brevier "$PYPDF_SPEC"'
+
+      # --- the proof itself: render, in a folder holding only the fixtures ---
+
+      - name: Render in a folder holding only the two fixtures
+        shell: bash
+        run: |
+          mkdir -p run
+          cp tests/fixtures/hello.html tests/fixtures/hello.css run/
+          (cd run && "$VENV_BIN/brevier" render hello.html -o hello.pdf)
+
+      - name: Check the PDF is real, not just present
+        shell: bash
+        run: '"$VENV_BIN/python" tests/packaging/check_pdf.py run/hello.pdf'
+
+      # --- the font-pinned fixture, once per OS, for the content check below ---
+
+      - name: Fetch the pinned fonts hello-bundled.html embeds
+        # tests/fixtures/fonts/ is gitignored (cross-os-proof.yml fetches it
+        # the same way) — a checkout alone does not have these files.
+        if: matrix.python-version == '3.13'
+        shell: bash
+        env:
+          # Same commit and checksums as cross-os-proof.yml, so both
+          # workflows prove against the same font bytes.
+          FONTS_COMMIT: 8b0a1d0f5983c89bc2b93f1b5fb55f9e252744b5
+          SANS_SHA256: bfb7bb691513f12e734dc346c03a03f784912432d7e3fa8e56efcf906fe86b3d
+          SERIF_SHA256: 4d8e6761424656867019081a1a01336f3cb086982682698714054fc33f782713
+        run: |
+          mkdir -p tests/fixtures/fonts
+          base="https://raw.githubusercontent.com/google/fonts/$FONTS_COMMIT/ofl"
+          curl -sSL -o tests/fixtures/fonts/NotoSans.ttf  "$base/notosans/NotoSans%5Bwdth%2Cwght%5D.ttf"
+          curl -sSL -o tests/fixtures/fonts/NotoSerif.ttf "$base/notoserif/NotoSerif%5Bwdth%2Cwght%5D.ttf"
+          digest() { "$VENV_BIN/python" -c "import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" "$1"; }
+          test "$(digest tests/fixtures/fonts/NotoSans.ttf)" = "$SANS_SHA256" || { echo "NotoSans differs on this runner"; exit 1; }
+          test "$(digest tests/fixtures/fonts/NotoSerif.ttf)" = "$SERIF_SHA256" || { echo "NotoSerif differs on this runner"; exit 1; }
+
+      - name: Render the font-pinned fixture, for the cross-OS content check
+        if: matrix.python-version == '3.13'
+        shell: bash
+        run: |
+          mkdir -p run-bundled/fonts
+          cp tests/fixtures/hello-bundled.html run-bundled/
+          cp tests/fixtures/fonts/*.ttf run-bundled/fonts/
+          (cd run-bundled && "$VENV_BIN/brevier" render hello-bundled.html -o hello-bundled.pdf)
+
+      - uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.13'
+        with:
+          name: bundled-pdf-${{ runner.os }}
+          path: run-bundled/hello-bundled.pdf
+
+  compare:
+    name: compare the font-pinned PDFs across operating systems
+    needs: install
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - run: python -m pip install --quiet "pypdf>=5,<7"
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: bundled-pdf-*
+          path: pdfs
+
+      - name: Compare content across operating systems
+        shell: bash
+        run: python tests/compare_pdf_content.py pdfs/*/hello-bundled.pdf