Validate gallery example installable deps and add tests

[bdbarnett]

Motivation

• Ensure gallery examples declare any installable top-level deps they actually import so the staging and gallery packaging are consistent.
• Surface warnings for declared-but-unused deps and fail the generator on missing installable deps to avoid broken demo pages.
• Correct the example deps header for apollo.py to include pygraphics.

Description

• Add ast-based import scanning with imported_top_level_modules and a validate_example_deps routine to detect missing or unused installable deps and wire it into main to run discovery validation before generation.
• Introduce INSTALLABLE_DEPS whitelist and reuse it to compute missing/unused declarations, emitting warnings to stderr and raising SystemExit on errors.
• Add pygraphics to the # deps: header in lib/examples/apollo/apollo.py.
• Extend and adjust tests: add dependency-validation coverage to tests/test_gallery_screenshots.py and refactor tests/test_peterhinch_page.py into a unittest.TestCase with a __main__ entry for test execution.

Testing

• Ran the updated gallery unit tests in tests/test_gallery_screenshots.py, including the new dependency validation assertions, and they succeeded.
• Ran tests/test_peterhinch_page.py under the unit test runner to verify the refactored tests and they passed.

---

Codex Task

[bdbarnett]

Review, 2026-09-06. Approve on substance; two things to finish in the description before it merges.

Verified here, beside the sibling repository

• python -m unittest tests.test_peterhinch_page: Ran 17 tests, OK (0 before).
• python -m unittest discover -s tests: Ran 60 tests, OK (43 before).
• scripts/gallery_generator.py --check: exit 0; 55 gallery demos, 17 local-only; three reverse-check warnings (tiny_toasters declares palettes it never imports; touch_gui_simpletest declares pygraphics it never imports; widgets_locker_kiosk declares audioif it never imports). Warnings, as designed.
• Planted fault: with pygraphics stripped from apollo's # deps: header, --check exits 1 with lib/examples/apollo/apollo.py: missing # deps: pygraphics. The guard fires. Header restored.
• The guard runs before the --check branch in main(), so both modes see it.

The apollo header change is a real catch, not a false positive: on main apollo declares # deps: palettes and imports pygraphics, so the Apollo DSKY demo has been dying on the deployed gallery the same way drum_machine did before #120 was filed — the issue's own sweep said 0 of 72 and was wrong by one. Worth a line in the PR description saying so.

The red check is not this PR's, and is fixed on main

quickstart-and-smoke fails at "Verify requirements.txt is current". That has been red on main since 0880cc63 (2026-09-04) added the two audio packages to requirements.txt by hand without adding them to the script's PACKAGE_ORDER; a blind --force would have removed them. Fixed on main in 8268d3aa. Merge main into this branch and the job goes green.

To finish

1. The description must list verbatim what was run and its result, as the approved plan promised: the two gate counts (17, and 60 with the sibling clone, or the count you got and why), the --check run, the ruff checks, and the planted-fault run. Today it says the tests "succeeded" and "passed" with no commands and no numbers.
2. Mark the PR ready for review (it is a draft).

Optional follow-up, not for this PR: the three reverse-check warnings are headers drifting from the truth; a separate tidy-up can remove those three declarations.

[bdbarnett]

Superseded by #122, which carries the same change on top of the requirements fix from main and passes every check. Closing this one; the review comment above applies to #122.