Generate a byte-stable preview PNG for every docs snippet, as the visual-
regression oracle foundation of #381. A changed image means the snippet's
behaviour changed and wants review.
Pipeline (no C++ change; existing headless build suffices):
- _seed.py: chained as the FIRST --exec so random.seed(42) governs the
snippet's RNG before it draws (snippets draw at import; seeding after is
too late). Shared-interpreter seeding covers all 25 random-module snippets.
- _screenshot.py: chained as the LAST --exec; steps setup frames then
automation.screenshot(). Kept separate from _harness.py so the pass/fail
suite stays fast and untouched.
- tools/generate_snippet_shots.py: orchestrator; runs seed->snippet->shot,
writes gitignored snippet-shots/ (images belong in the doc-site repo,
which pulls them from here). Per-snippet capture params live in a sidecar
OVERRIDES table, not the mcrf: header (which would fight stamp_snippets
and can't hold Phase-3 interaction scripts).
- make snippet-shots target; snippet-shots/ gitignored.
The 4 BSP snippets that needed deterministic pixels (060, 102, 224, 243)
now pass seed=42 — libtcod's global RNG is time(0)-seeded and unreachable
from Python, and seed= also documents reproducible generation for readers.
Validated: 272 captured, 10 skipped (noshot opt-outs), 0 failed; all 272
byte-identical across two full runs (~49s).
Addresses #381.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LTh2ZW7bd3XSd9qK86Z2CE
Extends the docs-as-tests pipeline to the hand-written pages. A multi-agent
workflow (tools/wf_docs_rewrite.js) fixed every cookbook/objects/tutorial/
features/templates page against the live 0.2.8-dev API and extracted every
complete runnable example into tests/snippets/131-282, each validated through
_harness.py and stamped by stamp_snippets.py.
run_tests.py already discovers tests/snippets/, so these 152 are now permanently
gated: a future API break that invalidates a documented example fails the suite.
Suite is 282/282; `make check-snippets` clean.
