Print view and PDF download for guides (#90) #91

Merged
miko merged 4 commits from feature/90-print-and-pdf into development 2026-11-05 09:38:14 +01:00
Owner

Closes #90

Summary

A guide prints without the titlebar, breadcrumb and buttons, and can be downloaded as a PDF. Both end with an Attribution Line (new glossary term): instance · guide URL · owner and last edit · "Created with kataba". The PDF is drawn on the server with @react-pdf/renderer (ADR-0019).

 <GuidePage> (src/app/guides/[id]/[slug]/page.tsx)
-  <Breadcrumb>
+  <Breadcrumb>                      print:hidden
   <header>
+    <GuideExport>                   print:hidden
+      <PrintButton>                 window.print()
+      <a href="/guides/<id>/pdf">   Download PDF
     <GuideControls>                 (editors only)
   <GuideSteps>
     <StepFigure>
-      <StepImageViewer>
+      <StepImageViewer>             print:hidden
+      <PrintedStepImages>           print only: every image with its annotations
+  <GuideAttributionLine>            print only
GET /guides/[id]/pdf (route.ts)
  guidePdfResponse
    loadGuide(id, user)            → 404, private, no-store, when hidden or missing
    pdfImage(storage, imageId)     → medium WebP variant as JPEG
    renderGuidePdf                 → logo header + page numbers on every page,
                                     description, steps, attribution line
src/guides/pdf/
├── renderGuidePdf.tsx   # document: logo header, title, attribution line
├── PdfSteps.tsx         # steps: images with annotations, step lines
├── PdfRichText.tsx      # descriptions and step content
├── pdfFonts.ts          # Inter, falling back to Noto Sans CJK glyph by glyph
├── pdfTheme.ts          # light theme colours mirrored from globals.css
└── fonts/               # Inter TTFs + Noto Sans CJK SC (SIL OFL)

Print CSS forces the light colour scheme, prints colours exactly (print-color-adjust), and sets page margins to 15 mm. pdf is now a reserved guide slug, like edit.

Evidence

  • Before: the guide page printed with the titlebar, breadcrumb and buttons, showed only the selected step image, and had no attribution. There was no PDF.
    After:
    • Tests:
      • guidePdfResponse: a PDF download named after the slug, private, no-store, with the guide's images embedded. A hidden or missing guide gives a 404.
      • renderGuidePdf: every block type, step line kind and annotation shape renders. Text is set in Inter, and Chinese, Japanese and Korean in Noto Sans CJK.
      • guideAttribution: English and German wording, absolute URL.
      • pdfImage: the WebP variant becomes a JPEG.
      • GuideSteps: every image is printed with its annotations.
    • 387/387 tests pass, lint and typecheck are clean, next build and the standalone build both succeed, and the standalone server serves the PDF with its fonts.
    • Checked by hand: a real guide's PDF on the dev server, and the print view rendered with print media in Chromium, light and dark.

Merge Danger

Door: two-way

Rolling back means reverting. Nothing is migrated or stored.

Blast Radius: guide page

  • The print styles touch the titlebar, StepFigure and StepImageViewer. The screen layout is unchanged, apart from the new buttons beside a guide.
  • An existing guide whose slug is exactly pdf would lose its reading page to the download route.
  • The repo and Docker image grow by about 18 MB of fonts.
  • New dependency: @react-pdf/renderer 4.9.0. The PDF renderer mirrors the screen renderer, so a change to rich text blocks or the palette has to be made in both (ADR-0019).

🤖 Generated with Claude Code

Closes #90 ## Summary A guide prints without the titlebar, breadcrumb and buttons, and can be downloaded as a PDF. Both end with an **Attribution Line** (new glossary term): instance · guide URL · owner and last edit · "Created with kataba". The PDF is drawn on the server with `@react-pdf/renderer` (ADR-0019). ```diff <GuidePage> (src/app/guides/[id]/[slug]/page.tsx) - <Breadcrumb> + <Breadcrumb> print:hidden <header> + <GuideExport> print:hidden + <PrintButton> window.print() + <a href="/guides/<id>/pdf"> Download PDF <GuideControls> (editors only) <GuideSteps> <StepFigure> - <StepImageViewer> + <StepImageViewer> print:hidden + <PrintedStepImages> print only: every image with its annotations + <GuideAttributionLine> print only ``` ```text GET /guides/[id]/pdf (route.ts) guidePdfResponse loadGuide(id, user) → 404, private, no-store, when hidden or missing pdfImage(storage, imageId) → medium WebP variant as JPEG renderGuidePdf → logo header + page numbers on every page, description, steps, attribution line ``` ```text src/guides/pdf/ ├── renderGuidePdf.tsx # document: logo header, title, attribution line ├── PdfSteps.tsx # steps: images with annotations, step lines ├── PdfRichText.tsx # descriptions and step content ├── pdfFonts.ts # Inter, falling back to Noto Sans CJK glyph by glyph ├── pdfTheme.ts # light theme colours mirrored from globals.css └── fonts/ # Inter TTFs + Noto Sans CJK SC (SIL OFL) ``` Print CSS forces the light colour scheme, prints colours exactly (`print-color-adjust`), and sets page margins to 15 mm. `pdf` is now a reserved guide slug, like `edit`. ## Evidence - **Before:** the guide page printed with the titlebar, breadcrumb and buttons, showed only the selected step image, and had no attribution. There was no PDF. **After:** - Tests: - `guidePdfResponse`: a PDF download named after the slug, `private, no-store`, with the guide's images embedded. A hidden or missing guide gives a 404. - `renderGuidePdf`: every block type, step line kind and annotation shape renders. Text is set in Inter, and Chinese, Japanese and Korean in Noto Sans CJK. - `guideAttribution`: English and German wording, absolute URL. - `pdfImage`: the WebP variant becomes a JPEG. - `GuideSteps`: every image is printed with its annotations. - 387/387 tests pass, lint and typecheck are clean, `next build` and the standalone build both succeed, and the standalone server serves the PDF with its fonts. - Checked by hand: a real guide's PDF on the dev server, and the print view rendered with print media in Chromium, light and dark. ## Merge Danger **Door:** two-way Rolling back means reverting. Nothing is migrated or stored. **Blast Radius:** guide page - The print styles touch the titlebar, `StepFigure` and `StepImageViewer`. The screen layout is unchanged, apart from the new buttons beside a guide. - An existing guide whose slug is exactly `pdf` would lose its reading page to the download route. - The repo and Docker image grow by about 18 MB of fonts. - New dependency: `@react-pdf/renderer` 4.9.0. The PDF renderer mirrors the screen renderer, so a change to rich text blocks or the palette has to be made in both (ADR-0019). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
The guide page prints without the titlebar, breadcrumb and buttons, shows
every step image with its annotations on paper, always in the light theme,
and ends with an attribution line. "Download PDF" draws the guide with
react-pdf: logo header and page numbers on every page, the same
attribution line at the end (ADR-0019).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
react-pdf starts a dashed circle's dash elsewhere than browsers, which put
the ring's gap at the bottom left and ran it into the dot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Helvetica covered only Western European text. Inter, the interface's
font, now sets Latin, Greek and Cyrillic; Noto Sans CJK fills in Chinese,
Japanese and Korean glyph by glyph, code falls back to both. The fonts
(SIL OFL, licences beside them) are traced into the standalone build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit cf43137291 into development 2026-11-05 09:38:14 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!91
No description provided.