Skip to content

Screenshotting the reading surface from a cloud session

Written 2026-08-22, from the first audit pass run entirely in a Claude Code cloud container. It answers a question that had been assumed shut: visual work on the viewer does not need the Mac. The EPUB-side snag work still does (see below) — but the content-viewer reading surface can be built, imported, measured and screenshotted in the cloud, at any viewport, against a real book.

What works, end to end

pip install 'mkdocs-material==9.7.6' 'mkdocs-awesome-pages-plugin==2.10.1' playwright
python3 -m mkdocs build --clean          # ~4s without a corpus, ~7min with one
python3 scripts/shoot_reading_surface.py --out shots/ --page <path-in-site>

The corpus tree is gitignored, so a fresh clone has the three lane landing pages and no chapters. To get a real reading surface, import one EPUB:

python3 scripts/import_collected_works.py \
  --epub <some.epub> --series wellred --volume 1 \
  --output docs/corpus/wellred-catalogue/volume-01

docs/corpus/wellred-catalogue/volume-*/ is gitignored, so this cannot pollute the corpus. The Wellred repo carries usable EPUBs in epubs/ — Venezuela and Ted Grant 1–3.

Why the harness exists rather than a bare screenshot

UNIFIED-CSS-FOUNDATION.md records two traps that a screenshot alone walks straight into, and the harness is built around both:

  • The browser pins the previously loaded stylesheet across reloads and cache-busting query strings. So the harness serves each run from a fresh ephemeral port and reports which stylesheets the document actually loaded.
  • A screenshot will happily show you the old CSS. So every shot is paired with computed style read from the live DOM, written to styles.json: measure, line-height, note sizing, alignment, indent, and an approximate characters-per-line — the unit the reading rules are actually specified in.

It also reports scrollWidth vs clientWidth per viewport. Note the limit recorded in the CSS foundation: leftward overflow creates no scrollable area, so a break-out centred off the left edge is invisible to this check. It catches rightward overflow only.

Viewports are desktop 1280, tablet 834, mobile 390. --full-page captures past the fold.

Chromium version pinning

The image ships Playwright's browsers at build 1194 under /opt/pw-browsers, which need not match the revision the pip package expects; playwright install is disabled. The harness launches the installed binary explicitly via executable_path and falls back to the bundled default when that path is absent, so it works both in the container and on the Mac.

What still needs the Mac

Unchanged, and worth stating so the boundary stays clear:

  • The designer's snag screenshots. docs.google.com is denied by the session's egress policy and the Drive connector returns bytes as base64 into context. See wellred-indesign-automation/docs/designer-snags-image-recovery.md.
  • Kindle Previewer, Calibre and EPUBCheck device passes. The snag list's review conditions (Previewer v3, Tablet, Bookerly, size 4, Portrait) are a macOS application.
  • Deploys to Harvey, which go over SSH from the Mac.

The split is: EPUB/device typography is Mac work; viewer CSS and UX is now cloud work. The two were previously blocked together, which is why viewer visual passes had been waiting on Mac availability they did not need.