iftypeset/docs/12-codex-max-workload.md

Codex Max Workload (High-Leverage) — Forgejo PDF Integration + PDF QA Expansion

This is the next big acceleration chunk for iftypeset.

Goal: make iftypeset visibly valuable in the real world by wiring it into the existing Forgejo PDF export worker, then deepen PDF QA so we catch real pagination failures (beyond widows/orphans).

Non-negotiables

• Do not OCR/transcribe Chicago/Bringhurst into the repo(s). Paraphrases + pointers only.
• Keep dependencies minimal. Prefer stdlib + existing tooling already present in the environment.
• Keep outputs deterministic. If a dependency/version makes determinism impossible, document it in a “trust contract” note instead of pretending.

Target repos

• iftypeset: /root/ai-workspace/iftypeset
• forgejo-pdf: /root/ai-workspace/forgejo-pdf

Part A — Integrate iftypeset CSS into Forgejo PDF export (primary goal)

A1) Understand current Forgejo PDF pipeline

In /root/ai-workspace/forgejo-pdf, identify:

• where Markdown is converted to HTML
• where CSS is selected/loaded (currently basic.css, professional.css, etc.)
• where PDF is rendered (Chromium / Playwright / Puppeteer / wkhtmltopdf / etc.)
• how configuration is passed (env vars, config file, CLI args)

Write a short “current pipeline” note in forgejo-pdf/worker/pdf/README.md (or existing docs file) so we can reason about changes later.

A2) Add a new theme option: iftypeset-web_pdf

We want Forgejo to be able to select:

• basic
• professional
• iftypeset-web_pdf (new)

Implementation constraints:

• The CSS file must ship with the worker (no network fetch at runtime).
• The CSS must load after any base CSS so it can override.
• The result should still render correctly even if some fonts are missing (font stack fallbacks).

A3) Generate and vendor the CSS from iftypeset

In iftypeset the command exists:

iftypeset emit-css --spec spec --profile web_pdf --out out-css

Pick one approach:

1. Vendored CSS in forgejo-pdf (recommended for now):

   • Generate out-css/iftypeset_web_pdf.css
   • Copy into forgejo-pdf/worker/pdf/assets/css/iftypeset-web_pdf.css
   • Add a small “refresh script” in forgejo-pdf/scripts/update_iftypeset_css.sh that regenerates and copies the file.
   • Document the source-of-truth as iftypeset + the refresh script.

2. Build-time generation (optional later):

   • During forgejo-pdf build, call iftypeset emit-css and bundle the output.

A4) Wire it into the render code path

Update the Forgejo PDF worker so that selecting the new theme:

• includes the CSS file in the HTML head
• produces PDFs/HTML without breaking existing themes

A5) Tests + validation

Add a minimal smoke test in forgejo-pdf that:

• renders a small known fixture Markdown
• verifies that the resulting HTML references iftypeset-web_pdf.css
• (optional) verifies PDF generation completes

Avoid checking in large PDF binaries. Prefer small text-based assertions (e.g., HTML contains a <link> to the CSS).

A6) Documentation

Update both repos:

• iftypeset/forgejo/README.md: “how to enable iftypeset-web_pdf theme in forgejo-pdf”
• forgejo-pdf docs: new theme option + how to refresh CSS

Part B — Expand PDF QA beyond widows/orphans (secondary goal)

We already have PDF-aware widows/orphans via Poppler pdftotext -layout.

Add 1–2 additional PDF incident kinds without adding heavy dependencies:

1. Stranded headings (most valuable)
   • detect headings at end of a page with insufficient following content (heuristic)
2. Overfull/clipping approximation
   • flag suspicious long lines that exceed measure, using pdftotext -layout and profile measure targets as heuristics

Requirements:

• Emit incidents with enough context to be actionable (page number, snippet, rule/tag).
• Update spec/quality_gates.yaml metrics if needed (or map into existing ones).
• Add fixtures + tests in iftypeset/tests/ for the new incidents.
• Update STATUS.md and docs/06-project-overview.md if behavior changes.

Completion checklist (what “done” looks like)

• Forgejo PDF worker can render using iftypeset-web_pdf theme.
• A refresh script exists to sync CSS from iftypeset.
• Both repos have docs explaining how to use it.
• CI stays green in both repos (or a clear note exists if one repo lacks CI).
• iftypeset PDF QA reports at least one new PDF incident kind beyond widows/orphans.

After each major chunk

• Run:
  • bash /root/ai-workspace/iftypeset/scripts/ci.sh
  • create an iftypeset checkpoint: bash /root/ai-workspace/iftypeset/scripts/checkpoint.sh "note"
  • and if you touch forgejo-pdf, do the equivalent if that repo has checkpoint tooling (otherwise document git rev-parse HEAD).