[dmccoystephenson]

Summary

Stage B (unit-test expansion) for off-surface drawing, with the matching doc addition.

• No test pinned what happens when a draw method is given a position that puts part of the shape past the edge of the surface. Consumers that scroll a tiled view (e.g. Roam's map) do this every frame and rely on the on-surface part being painted and the rest dropped, with no raise and no shifting to fit.
• test_draw_methods_clip_a_shape_that_crosses_the_surface_edge is added, parametrized over drawRectangle, drawImage and drawButton (empty label) × all four corners (-5/15 offsets of a 10×10 shape on a 20×20 display). Every pixel of the display is checked: inside the clipped intersection it carries the drawn color, and everywhere else it stays black.
• test_draw_text_centered_on_a_surface_corner_paints_the_visible_part is added. It centers a size-24 "W" on (0, 0) and requires ink to be painted, all of it inside the quadrant around the corner.
• One sentence stating the clipping behavior is added to the Graphik class docstring and to the README's public-method section.

No production behavior is changed. The docstring edit is comment-only, and no public signature is touched, so no consumer-impact check applies.

No tracking issue — gap found during triage.

Test plan

• python3 -m py_compile src/main/python/preponderous/graphik/graphik.py
• python3 -m pytest (headless via conftest.py): 82 passed (69 previously plus 13 new)
• Mutation check: coordinate clamps were temporarily injected (max(0, …) in drawRectangle, clamp_ip to the surface in drawText, min(xpos, 10) in drawImage). 9 of the 13 new tests failed. The 4 that passed are the cases a given clamp cannot affect. The source was then restored, and all 82 tests passed.

Deferred issues

• 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: each requires a change under .github/workflows/ or to the release/tagging process, both excluded from autonomous change.
• packaging: the empty preponderous/__init__.py ships a regular package, which will collide with any future preponderous.* distribution #40: deleting preponderous/__init__.py depends on a maintainer decision about the namespace convention used by sibling preponderous.* projects, which 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 (posted as a plain comment; Copilot reviewer could not be added — Could not resolve user with login 'copilot'):

• Scope: PASS — three files: the new tests, plus one documentation sentence each in the class docstring and README describing exactly the pinned behavior.
• Tests-new: PASS — no new public method; 13 new test cases added.
• Tests-fix: N/A — no bug fix. Mutation check was performed instead: injected coordinate clamps in drawRectangle/drawText/drawImage made 9 of 13 new cases fail (the 4 passing cases are ones a given clamp cannot affect), then the source was restored and all passed.
• Sibling structure: FAIL → fixed in dfe61ec — the first revision parametrized over lambdas, while the neighbouring test_draw_methods_render_to_the_bound_surface_not_the_display uses named _draw_* helpers; switched to named helpers.
• Additional finding, fixed in e1712d1 — src/test/python/preponderous/graphik/test_graphik.py (drawText corner test): the hard-coded < 12 bound was one pixel from its limit (a size-24 "W" renders 23×24 under pygame 2.1.2), and the comment claimed the glyph was "far" larger than 24px. The bound is now derived from Font.size("W"); the clamp_ip mutation still makes it fail.
• Sibling renames: N/A — nothing renamed.
• Docs: PASS — README and class docstring both state the clipping behavior; no version strings changed.
• Issue resolution: N/A — no Closes; gap found during triage.
• Manual validation: PASS — py_compile clean; local pytest 82 passed; CI Test run 40061556095 green on e1712d1 across 3.9–3.13.
• camelCase: N/A — no new public method.
• Backward-compat: PASS — no public member touched; the graphik.py change is docstring-only.
• Headless: PASS — new tests use the existing conftest.py dummy drivers and run in CI.
• Version sync: N/A — _version.py untouched.
• No new deps: PASS — no imports added.

Two findings were fixed mechanically; no judgment calls remain open.

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

---

drafted by Claude on behalf of Daniel Stephenson