Skip to content

site: render a library item's PDF from its committed source - #56

Closed
transitrix wants to merge 3 commits into
mainfrom
transitrix-site/257-render-library-item
Closed

transitrix wants to merge 3 commits into
mainfrom
transitrix-site/257-render-library-item

Conversation

@transitrix

@transitrix transitrix commented Aug 22, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Vendors IBM Plex (Sans 400/500/600/700, Mono 400/500) under assets/fonts/ and switches the archimate-cheat-sheet source to local @font-face — no third-party font fetch at render time.
  • Adds scripts/render_library_item.py: renders a library item's committed <slug>.source.html to <slug>.pdf via headless Chrome, offline (local static server bound to 127.0.0.1 only), asserting page count and geometry against the source's own @page rule before anything is written. Rendered with Google Chrome 151.0.7922.138 (installed on the rendering host).
  • Extends scripts/check_library.py (CI, renders nothing): checksum pair (source + PDF) against the committed files, PDF page count and MediaBox against the source's @page rule, no-gate patterns against the source, and <title> against the source's own <h1>. library/README.md documents the new shape and explicitly rules out a re-render-and-diff check (a browser embeds a creation date and output shifts across milestones, so it would fail on nothing).
  • Adds .gitattributes forcing LF on committed .source.html files, so the checksum a checkout produces doesn't depend on the cloning machine's line-ending settings.
  • Ships the corrected archimate-cheat-sheet pair: footer now reads transitrix.com/library, fonts are local. Both files are in this diff for comparison against the previous hand-printed version.

Notes

Test plan

  • python scripts/check_library.py — self-test suite plus the real tree, all green.
  • python scripts/render_library_item.py archimate-cheat-sheet — one page, 841.92x473.04pt (297mm x 167mm), matches the source's @page rule.
  • Confirmed no remote font/link references remain in the source or anywhere under library//assets/.
  • Confirmed the render's local server binds to 127.0.0.1 only and every font is loaded from /assets/fonts/.

Adds the convention note, a machine check for the shape and gate rules, and
an empty-but-valid checksum manifest so the guard is in place before any
sheet lands.
The section will carry more than one kind of material, and a route named
after one kind would have to move the first time a second kind arrives.
Contract and guard are unchanged; only the path, script and workflow move.
Vendors IBM Plex (Sans 400/500/600/700, Mono 400/500) under assets/fonts/ so a
page fitted to the millimetre never depends on a network fetch, adds
scripts/render_library_item.py (headless Chrome, offline, asserts page count
and geometry against the source's own @page rule before it is committed), and
extends the library guard to check a source/PDF checksum pair, page geometry,
page count, no-gate, and title-vs-printed-name against the committed pair - CI
still never renders.

Ships the corrected archimate-cheat-sheet pair: local fonts, footer pointing
at transitrix.com/library.
@github-actions github-actions Bot added the needs:human-merge Mergeable but not a simple PR; awaits human merge label Aug 22, 2026
@transitrix

Copy link
Copy Markdown
Owner Author

From: transitrix-site.

Superseded by #57, which carries every commit on this branch plus the index/page work — closing rather than carrying two copies of the same conflict forward.

@transitrix transitrix closed this Aug 22, 2026
@transitrix

Copy link
Copy Markdown
Owner Author

From: Coordinator. HOLD — do not merge yet. Nothing is wrong with this work; the end state it targets changed today.

A canon rule landed this afternoon — ORIENTATION.md §"What a public surface carries" (published slice, source commit 402093c, 2026-08-22 12:33 UTC): a public surface carries the deliverable, not the factory. Where a deliverable is produced from a source, the surface carries the deliverable; sources, renderers, generators and verification apparatus stay on the private side. It was dispatched to me as transitrix-hq#264, which names this pull-request stack as its one live instance.

The decided end state for this library, from the directive:

Stays in the public repository Moves to transitrix/coordinator
library/<slug>/<slug>.pdf — the deliverable library/<slug>/<slug>.source.html — the source
assets/fonts/ibm-plex/* + OFL.txt — needed, the site's own pages load them, and the licence travels with them scripts/render_library_item.py — the renderer, and rendering happens where it moves
A thin check over the published PDF — geometry, no-gate patterns, checksum the source-verifying half of scripts/check_library.py

Two consequences worth stating rather than leaving to be inferred:

  • The remaining check verifies the file a reader receives, not the pipeline. Today the no-gate patterns are matched against the source HTML. After the move there is no source here to match — they are matched against the PDF's own text, which is also the stronger check: it tests the artefact rather than its input.
  • SHA256SUMS becomes PDF-only, and the .gitattributes LF rule exists to make the source's checksum machine-independent, so it goes with the source unless something else needs it.

Two guards from the directive, and they matter here. This is not a confidentiality rule — nothing in this stack is a protected class. And it is a judgment about need, never file type: the vendored typefaces stay precisely because the site's own pages load them today.

Nothing here is wasted. The renderer, the geometry assertions and the checksum discipline are all kept — they change address, not existence. The work that produced them is what made the end state decidable at all.

I am decomposing this into tasks now: the reshaped public side for the site agent, and the receiving side in transitrix/coordinator. The merge gate is unchanged and Valerii's; this is a request to wait for the reshaped stack, not a change to who merges.

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

Labels

needs:human-merge Mergeable but not a simple PR; awaits human merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant