[dmccoystephenson]

Summary

Stage A (documentation accuracy sweep) cycle. drawButton's docstring and the README both stated that the clickable region is "exactly the region the box is drawn over". That only holds when the Graphik is bound to the display itself. The hit test compares pygame.mouse.get_pos(), which is window-relative, against (xpos, ypos) unchanged. As a result, when the instance is bound to a subsurface (or to an off-screen surface that is later blitted somewhere other than the window origin), the box is painted at the surface's offset but stays clickable at the raw (xpos, ypos) in window coordinates.

• graphik.py: a paragraph was added to the drawButton docstring describing the window-coordinate hit test. No code was changed.
• README.md: the drawButton entry now carries the same qualification.
• test_graphik.py: a new characterization test, test_draw_button_hit_tests_in_window_coordinates_not_the_bound_surface, binds a Graphik to a subsurface offset by (100, 100). It asserts that a press over the painted box does not fire and that a press at the raw window coordinates does. Each case is backed by a pixel check, so the test is tied to what is actually drawn.

This is a docs-and-test change only, and the behavior is deliberately left as it is. Translating the mouse position into the bound surface's coordinates would change behavior for the vendored consumers (Roam, Apex, Ophidian, Patchwork, Tic-Tak-Toe), so that decision belongs to a maintainer and is out of scope for a docs cycle. No public member changed, so the consumer-impact gate does not apply.

No tracking issue: the gap was found during the documentation sweep.

Skipped issues

None of the open issues was taken up this cycle, because each one waits on a human:

• 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 need changes under .github/workflows/, which is excluded from autonomous change. release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34 also needs a maintainer decision on tagging.
• packaging: the empty preponderous/__init__.py ships a regular package, which will collide with any future preponderous.* distribution #40 depends on a maintainer decision about the preponderous.* namespace convention used across sibling projects.

Test plan

• python3 -m py_compile src/main/python/preponderous/graphik/graphik.py
• python3 -m pytest: 67 passed (66 existing + 1 new), headless via the conftest dummy SDL drivers
• The new test was run before the docs edit and confirmed the behavior it describes (a first draft probed a label pixel and failed on the color check, not on the hit test, and was adjusted)

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 (performed inline during a headless dispatch, not an independent review):

• Scope: PASS. The 3 files touched are the drawButton docstring, its README entry, and one test that pins the documented behavior. There is no unrelated churn.
• Tests-new: PASS (n/a). No new public method was added. The added test is a characterization of existing behavior.
• Tests-fix: n/a. No production behavior was changed. The new test was run against unmodified code and confirmed the documented behavior. Its first draft failed only because of a probe pixel that landed on the label, and it was corrected to probe the box corner.
• Sibling structure: PASS. The test reuses the existing _click_at and _rgb helpers and follows the comment style of neighboring drawButton tests.
• Sibling renames: n/a. Nothing was renamed.
• Docs: PASS after one fix. The first push of the README entry limited the claim to "the display itself", which was narrower than the docstring's "or another surface whose top-left sits at the window's origin". This was aligned in a follow-up commit.
• Issue resolution: n/a. No Closes #N, because the gap was found during the sweep.
• Manual validation: PASS. py_compile is clean, and pytest reports 67 passed locally. The CI Compile and test jobs are green on 3.9 through 3.13, and they include the import smoke test.
• camelCase / Backward-compat: PASS. No public member was added, renamed, or re-signatured. The behavior was deliberately left unchanged, because translating mouse coordinates would alter semantics for vendored consumers.
• Headless: PASS. The test runs under the conftest dummy SDL drivers.
• Version sync / No new deps: PASS. No version strings or imports were touched.

Judgment call flagged for a maintainer: whether drawButton should eventually hit-test relative to the bound surface (via get_abs_offset() for subsurfaces) is left open. This PR only documents the current behavior.

Do-not-auto-merge path check: no workflow, LICENSE, or security/ paths are touched, and no file has more than 50 deleted lines.

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

---

drafted by Claude on behalf of Daniel Stephenson