[dmccoystephenson]

Summary

• drawImage calls convert_alpha() on the loaded image, which raises pygame.error: No video mode has been set when pygame.display.set_mode has not been called. This happens even when the Graphik is bound to an off-screen surface. drawRectangle and drawText work in that state, as was confirmed empirically before the change.
• Before this change the drawImage docstring's Raises: section mentioned pygame.error only for undecodable files, and the README said nothing about the requirement. Both now document it.
• A characterization test pins the current behavior. With no display mode set, the other draw methods succeed and drawImage raises pygame.error without painting anything. After a mode is set, the same instance draws the image, so the failure caches nothing.

No production behavior is changed. Only the docstring, the README and the tests are modified. Removing the requirement (for example, by converting against the bound surface when no display exists) would be a behavior change and is left for a separate decision.

Test plan

• python3 -m py_compile src/main/python/preponderous/graphik/graphik.py
• python3 -m pytest -q: 61 passed (headless via conftest.py)
• The new test passes when run alone (-k requires_a_display_mode), so it does not depend on state left by earlier tests

Skipped issues

No tracking issue exists. The gap was found during a documentation-accuracy sweep (Stage A). The open issues were left alone for these reasons:

• 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 and release: publish.yml's wheel smoke test never imports Graphik, so a wheel missing graphik.py would still publish #46 require changes to .github/workflows/ or the release process, which are excluded from autonomous change and wait on a maintainer decision.
• packaging: the empty preponderous/__init__.py ships a regular package, which will collide with any future preponderous.* distribution #40 depends on a cross-repo packaging-convention decision that cannot be settled from this repository.

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 (anchored on CI run 38365016372, green on 3.9–3.13, and a local pytest run with 61 passed):

• Scope: PASS. Three files are changed: the drawImage docstring, the matching README bullet, and one test that pins the newly documented behavior. Nothing unrelated is touched.
• Tests-new: PASS (not applicable). No public method was added.
• Tests-fix: not applicable. No production behavior was changed. This is a characterization test, so it passes against both main and the PR head by design.
• Sibling structure: PASS. The test sits beside the other drawImage failure-mode tests. It uses the existing _write_solid_image and _rgb helpers and follows the camelCase local naming that the neighbouring tests use.
• Sibling renames: not applicable.
• Docs: PASS. The README bullet and the docstring (prose plus Raises:) agree. pyproject.toml, RELEASING.md and _version.py are unaffected.
• Issue resolution: not applicable. There is no tracking issue, and the PR body records that the gap came from a Stage A sweep.
• Manual validation: PASS. Compile check, import smoke test and pytest are green in CI on every supported Python version.
• camelCase / Backward-compat: PASS. No public member was renamed or changed.
• Headless: PASS. The test runs under the conftest.py dummy drivers. It calls pygame.display.quit()/init() to reach the no-mode state, and later tests are unaffected because each one sets its own mode. The full suite passed after the test was added.
• Version sync / No new deps: PASS. No version string or import was changed.

Finding fixed during review:

• src/test/python/preponderous/graphik/test_graphik.py:217: the docs say drawImage differs from "the other draw methods", but the first push exercised only drawRectangle and drawText in the no-mode state. A drawButton call was added in the second commit so the claim is pinned for all three. The button area (0..7, 12..19) does not overlap the probed image pixel (15, 15).

Judgment call flagged for the maintainer: the requirement could be removed instead of documented, for example by skipping convert_alpha() when pygame.display.get_surface() is None. That would change behavior, so it is left out of this PR.

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

---

drafted by Claude on behalf of Daniel Stephenson