|
1 | 1 | # Changelog |
2 | 2 |
|
| 3 | +## [1.5.1.0] - 2026-04-20 |
| 4 | + |
| 5 | +## **Three visible bugs in v1.4.0.0 /make-pdf, all fixed.** |
| 6 | + |
| 7 | +Page footers showed "6 of 8" twice on every page because Chromium's native footer and our print CSS were both rendering numbers. A markdown title containing `&` rendered as `Faber &amp; Faber` in `<title>` and TOC entries, because the extractors stripped tags but forgot to decode entities. On Linux (Docker, CI, servers), body text fell through to DejaVu Sans because neither Helvetica nor Arial is installed by default, and nothing in the font stack caught that. This release fixes all three and extends the fix beyond the obvious symptom each time. |
| 8 | + |
| 9 | +### The numbers that matter |
| 10 | + |
| 11 | +All three bugs were caught and expanded in review before any code was written. The plan went through `/plan-eng-review` (Claude), then `/codex` (outside voice), then implementation. Source: `.github/docker/Dockerfile.ci` (Linux fonts), `make-pdf/test/render.test.ts` (17 new tests), `git log main..HEAD` (this branch). |
| 12 | + |
| 13 | +| Surface | Before (v1.4.0.0) | After (v1.5.1.0) | |
| 14 | +|---------|-------------------|-----------------| |
| 15 | +| Page footer | "6 of 8" stacked twice | "6 of 8" once | |
| 16 | +| `# Faber & Faber` in `<title>` | `Faber &amp; Faber` | `Faber & Faber` | |
| 17 | +| TOC entry with `&` | Double-escaped | Single-escaped | |
| 18 | +| `©` (copyright) in H1 | Broken | Decodes to `©` | |
| 19 | +| `--no-page-numbers` CLI flag | Silently did nothing | Actually suppresses page numbers | |
| 20 | +| `--footer-template` | Layered CSS page numbers on top | Custom footer wins cleanly | |
| 21 | +| Linux PDF body font | DejaVu Sans (wrong) | Liberation Sans (metric-compatible Helvetica clone) | |
| 22 | + |
| 23 | +| Review layer | Findings | Outcome | |
| 24 | +|--------------|----------|---------| |
| 25 | +| `/plan-eng-review` (Claude) | 1 architectural gap | expanded Bug 1 scope to include CSS-side conditional | |
| 26 | +| `/codex` (outside voice) | 11 findings | 11 incorporated (data flow, TOC site, decoder collision, footer semantic, test contract, scope boundaries, font dependency) | |
| 27 | +| Cross-model agreement rate | ~30% | Codex found 7 issues Claude's eng review missed by staying too high-altitude | |
| 28 | + |
| 29 | +The agreement rate is the tell. One reviewer was not enough on this diff. Codex caught that my original "one-line fix" for Bug 1 would have left the `--no-page-numbers` CLI flag silently dead, because `RenderOptions` didn't carry `pageNumbers` and the orchestrator's `render()` call didn't pass it. Without the second opinion, the CLI flag ships broken again. |
| 30 | + |
| 31 | +### What this means for anyone generating PDFs |
| 32 | + |
| 33 | +Page numbers are now controlled by one flag from CLI to CSS, with the custom-footer semantic restored. Titles, cover pages, and TOC entries render HTML entities correctly, including numeric entities like `©`. Linux environments no longer need to know about fonts-liberation — the Dockerfile installs it explicitly and a build-time `fc-match` check fails the image if the font disappears. Run `bun run dev make-pdf <file.md> --cover --toc` on Mac, and now also inside Docker, and the output looks the same. |
| 34 | + |
| 35 | +### Itemized changes |
| 36 | + |
| 37 | +#### Fixed |
| 38 | + |
| 39 | +- **Page numbers no longer render twice on every page.** Chromium's native footer used to layer on top of our `@page @bottom-center` CSS. Now CSS is the single source of truth; Chromium native numbering is off unconditionally. |
| 40 | +- **`--no-page-numbers` works end-to-end.** The CLI flag now reaches the CSS layer via `RenderOptions.pageNumbers`. Previously it died at the orchestrator and the CSS kept rendering numbers regardless. |
| 41 | +- **`--footer-template` cleanly replaces the stock footer.** Passing a custom footer now also suppresses the CSS page numbers, preserving the original "custom footer wins" semantic that existed before Bug 1 collided with it. |
| 42 | +- **HTML entities in titles, cover pages, and TOC entries render correctly.** A markdown heading like `# Faber & Faber` renders as `Faber & Faber` in `<title>` (single-escaped) instead of `Faber &amp; Faber` (double-escaped). Covers both extractor call sites: `extractFirstHeading` (title + cover) and `extractHeadings` (TOC). |
| 43 | +- **Numeric HTML entities decode too.** `©` in an H1 now renders as `©` in the PDF title. Decimal and hex numeric entities both supported. |
| 44 | +- **Linux PDFs render in Liberation Sans instead of DejaVu Sans.** Font stacks in all four print-CSS slots (body, running header, page number, CONFIDENTIAL label) now include `"Liberation Sans"` between Helvetica and Arial. Metric-compatible, SIL OFL 1.1, installs via `fonts-liberation`. |
| 45 | + |
| 46 | +#### Changed |
| 47 | + |
| 48 | +- `.github/docker/Dockerfile.ci` installs `fonts-liberation` + `fontconfig` explicitly with retries, runs `fc-cache -f`, and verifies `fc-match "Liberation Sans"` in the final build step. Previously relied on Playwright's `install-deps` pulling it in transitively, which could silently regress on upgrade. |
| 49 | +- `SKILL.md.tmpl` documents the Linux font dependency for users who install outside CI/Docker. |
| 50 | + |
| 51 | +#### For contributors |
| 52 | + |
| 53 | +- New helper `decodeTextEntities` in `render.ts` (distinct from existing `decodeTypographicEntities`, which intentionally preserves `&` in pipeline HTML where `&amp;` can be legitimate). Use the new one when extracting plain text destined for `<title>`, cover, or TOC. |
| 54 | +- `PrintCssOptions.pageNumbers` wraps the `@bottom-center` rule in a conditional matching the existing `showConfidential` pattern. Thread `pageNumbers` through `RenderOptions` and forward from `orchestrator.ts` into both `render()` call sites (generate + preview). |
| 55 | +- 17 new tests in `make-pdf/test/render.test.ts`: `printCss` pageNumbers isolation (3), `render()` data flow with footerTemplate (4), parameterized entity contracts across `&`, `<`, `>`, `©`, `—` (5), `<title>` exact single-escape assertion, TOC single-escape, numeric entity decode, smartypants-interacts contract, Liberation Sans body + @page box coverage (2). |
| 56 | +- Known test gaps (small, future PR): hex numeric entity path, amp-last ordering with double-encoded input, SKILL.md Linux note content assertion. Orchestrator → `browseClient.pdf({pageNumbers: false})` and orchestrator → `render()` forwarding are covered transitively via the CSS end-to-end tests, not asserted directly. |
| 57 | + |
3 | 58 | ## [1.5.0.0] - 2026-04-20 |
4 | 59 |
|
5 | 60 | ## **Your sidebar agent now defends itself against prompt injection.** |
|
0 commit comments