[dmccoystephenson]

Summary

Stage A (documentation accuracy sweep). The README's Usage block was found not to produce what it implies. It painted one frame and then exited: pygame.display.update() was never called, no event was processed, and drawButton could never be clicked. Copied as written, the window opens and closes with nothing shown. Neither pygame.display.update, flip nor event handling was mentioned anywhere in the repository.

• README.md: the example is rewritten as an event loop that presents each frame and quits cleanly, and the placeholder image path is marked as one to replace. A short note states that Graphik only paints the surface, and that drawButton belongs in a loop that handles events.
• graphik.py: docstrings only. The class docstring states the same rule, and its example gains the missing pygame.display.update(). No executable code is changed.
• Tests: two are added (138 passed, 133 before).
  • test_draw_methods_leave_presenting_the_display_to_the_caller pins the new claim for all four draw methods.
  • test_readme_usage_example_runs_and_presents_what_it_draws extracts the Usage block from README.md and runs it, so the example cannot drift from the code unnoticed.

No public member is changed, so the Phase 3 consumer-impact gate does not apply.

Test plan

• python3 -m py_compile src/main/python/preponderous/graphik/graphik.py
• Import smoke test: from preponderous.graphik import Graphik
• python3 -m pytest: 138 passed. The conftest forces the dummy SDL drivers, so this is headless.
• Throwaway mutation check (7 mutants, script not committed): all were killed, each by a new test. The mutants made each of the four draw methods present the display, removed the README's update call, moved it before the draws, and removed the QUIT handling. For drawImage and the three README mutants, the new tests were the only failures. The other three also failed existing tests.
• CI matrix (3.9 to 3.13)

Local validation used pygame 2.1.2 on Python 3.8, which is below the supported floor. CI is the check against current pygame versions.

Backlog

No tracking issue: the gap was found during triage. Each open issue was skipped for a stated reason:

• drawButton: with fractional arguments the clickable region drifts up to a pixel from the drawn box #61: a change to consumers' clickable regions, explicitly left to a maintainer.
• packaging: the empty preponderous/__init__.py ships a regular package, which will collide with any future preponderous.* distribution #40: requires confirming the sibling Preponderous-Software packaging convention, a maintainer prerequisite that cannot be settled from this repository.
• release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34, ci: test.yml's header comment claims it runs on every push, but pushes outside main are only covered via pull_request #39, release: publish.yml's wheel smoke test never imports Graphik, so a wheel missing graphik.py would still publish #46: require .github/workflows/ edits, which are on the do-not-auto-merge list. Opening them as held PRs would block later dispatches.

Not verified

• The statement that pygame refreshes mouse state only while events are processed comes from pygame's published documentation for pygame.mouse.get_pressed. It was not re-read this cycle, because pygame's installed docs were outside the permitted paths, and it could not be observed under the dummy driver, which has no mouse.
• The example's behavior in a real window was not observed. Running it headless shows that it presents the drawn frame and exits on QUIT.
• The README's claim that graphik is unpublished on PyPI, and its wiki link, were not checked. The gh api repository lookup was denied in this dispatch, and curl was not attempted because it is recorded as denied in dev-loop issue Stephenson-Software/graphik-dev-loop#35.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric, scored against the diff at a952242 and CI run 41988925282. This is an inline review by the authoring session, not an independent one. A Copilot review could not be requested (Could not resolve user with login 'copilot').

• Scope: PASS. Three files changed: the README's Usage block and note, the matching class docstring, and two tests. No unrelated churn.
• Tests-new: PASS (not applicable). No public method was added.
• Tests-fix: not applicable. No bug was fixed. The equivalent check was run instead: 7 hand-written mutants were all killed by the new tests, while the unmutated source passed.
• Sibling structure: PASS. The new tests sit beside test_draw_methods_render_to_the_bound_surface_not_the_display and reuse its _draw_* helpers and _make_graphik, _rgb and _write_solid_image.
• Sibling renames: PASS (not applicable). Nothing was renamed.
• Docs: PASS. The README and the class docstring make the same claim, and it is pinned by a test. The docstring example gained the same update call. No version or dependency statement is affected.
• Issue resolution: PASS (not applicable). No issue is referenced as resolved.
• Manual validation: PASS. py_compile, the import smoke test and pytest (138 passed) are green locally, and all five CI jobs are green on a952242.
• camelCase: PASS. No public method was added or renamed.
• Backward-compat: PASS. graphik.py changes in its docstring only, so the consumer-impact gate does not apply.
• Headless: PASS. Both tests ran under the dummy driver locally and in CI. The example's pygame.init() is covered by the dummy audio driver set in conftest.
• Version sync: PASS. No version string was touched.
• No new deps: PASS. Only the stdlib re was added, in test code.

Do-not-auto-merge paths: none matched. .github/workflows/, LICENSE and the version source are untouched, and no file deletes more than 50 lines.

Findings fixed during this review:

• src/test/python/preponderous/graphik/test_graphik.py:884 — a comment said one QUIT was queued, but the stub reports QUIT on every call. It was reworded in 9d0748d.
• src/test/python/preponderous/graphik/test_graphik.py:867 — a comment asserted how consumers batch their draws, which could not be verified because consumer code was not read this cycle. It was reworded in a952242.

Findings accepted without change:

• src/test/python/preponderous/graphik/test_graphik.py:904 — the sampled pixel (105, 105) hard-codes the rectangle position used in the README, so moving that rectangle fails the test. This is judged acceptable: the failure is loud and points at the right file, and it is what proves the frame was painted before being presented.
• src/test/python/preponderous/graphik/test_graphik.py:882 — the new test depends on README.md being present on disk, which holds for this source-tree suite. Running the tests from an installed wheel without the README would fail.
• The mutation check ran before three later edits: the removal of a redundant pygame.display.init() from the README test, and the two comment changes above. It was not re-run. The test's executable logic is otherwise unchanged, and pytest stayed green after each edit.
• The claim about pygame refreshing mouse state during event processing is the one README statement not checked in this cycle (see "Not verified" in the PR description).

Verdict: ready to merge.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson