Fix verify-pass code bugs #317/#318/#319

Three small bugs surfaced by the #314 docstring-accuracy verify pass: #317 automation.scroll() dropped the x of its position argument: scroll() resolved (x, y) but called injectMouseEvent(MouseWheelScrolled, clicks, y), passing the scroll amount as x. injectMouseEvent now takes the scroll delta as its own parameter and scroll() forwards the real x/y. #318 GridView.texture always returned None (a TODO stub). It now returns a Texture wrapper sharing the underlying shared_ptr<PyTexture>, mirroring Grid.texture. (mcrfpy.Grid and mcrfpy.GridView are the same type post-#252, so this fixes both names.) #319 Entity.visible_entities(radius=None) raised TypeError: radius was parsed with the 'i' format code, which rejects None. It now parses radius as an object and treats None / omitted / -1 as "use the grid's default fov_radius"; a non-int, non-None radius raises a clear TypeError. - regression tests for each under tests/regression/ - api_surface snapshot re-baselined (visible_entities signature; texture property now Texture | None) and docs/stubs regenerated; frozen docstring gate still 100% closes #317 closes #318 closes #319 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KnywUddaFRhkxo5kijxJnv
2026-06-21 10:12:41 -04:00 · 2026-06-21 10:12:41 -04:00 · 98489a96fd
commit 98489a96fd
parent 265425321c
12 changed files with 303 additions and 55 deletions
--- a/docs/API_REFERENCE_DYNAMIC.md
+++ b/docs/API_REFERENCE_DYNAMIC.md
@ -1,6 +1,6 @@
 # McRogueFace API Reference

-*Generated on 2026-06-21 09:39:04*
+*Generated on 2026-06-21 10:11:50*

 *This documentation was dynamically generated from the compiled module.*

@ -1989,19 +1989,17 @@ Note:

 **Returns:** None Called automatically when the entity moves if the grid has FOV configured.

-#### `visible_entities(fov=None, radius: int = -1) -> list[Entity]`
+#### `visible_entities(fov=None, radius: int | None = None) -> list[Entity]`

 Get list of other entities visible from this entity's position.

-Note:
-
 **Arguments:**
 - `fov`: FOV algorithm to use (FOV enum or None to use grid.fov)
- `radius`: FOV radius as int; omit or pass -1 to use the grid's default fov_radius
+- `radius`: FOV radius as int; pass None, omit, or pass -1 to use the grid's default fov_radius

 **Returns:** List of Entity objects within field of view, excluding self

-**Raises:** ValueError: If entity is not associated with a grid radius does not accept None; omit the argument entirely to use the grid default.
+**Raises:** ValueError: If entity is not associated with a grid TypeError: If radius is neither an int nor None

 ### Entity3D

@ -2441,7 +2439,7 @@ Keyword Args:
 - `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
 - `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
 - `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
+- `texture` *(read-only)*: Texture used for tile rendering (Texture | None, read-only).
 - `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
 - `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
 - `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
@ -2561,7 +2559,7 @@ Keyword Args:
 - `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
 - `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
 - `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
+- `texture` *(read-only)*: Texture used for tile rendering (Texture | None, read-only).
 - `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
 - `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
 - `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
--- a/docs/api_reference_dynamic.html
+++ b/docs/api_reference_dynamic.html
@ -108,7 +108,7 @@
 <body>
    <div class="container">
        <h1>McRogueFace API Reference</h1>
-        <p><em>Generated on 2026-06-21 09:39:04</em></p>
+        <p><em>Generated on 2026-06-21 10:11:50</em></p>
        <p><em>This documentation was dynamically generated from the compiled module.</em></p>
        
        <div class="toc">
@ -2144,16 +2144,14 @@ Note:</p>
            </div>

            <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">visible_entities(fov=None, radius: int = -1) -> list[Entity]</code></h5>
-                <p>Get list of other entities visible from this entity&#x27;s position.
-
-Note:</p>
+                <h5><code class="method-name">visible_entities(fov=None, radius: int | None = None) -> list[Entity]</code></h5>
+                <p>Get list of other entities visible from this entity&#x27;s position.</p>
                <div style='margin-left: 20px;'>
                    <div><span class='arg-name'>fov</span>: FOV algorithm to use (FOV enum or None to use grid.fov)</div>
-                    <div><span class='arg-name'>radius</span>: FOV radius as int; omit or pass -1 to use the grid&#x27;s default fov_radius</div>
+                    <div><span class='arg-name'>radius</span>: FOV radius as int; pass None, omit, or pass -1 to use the grid&#x27;s default fov_radius</div>
                </div>
                <p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of Entity objects within field of view, excluding self</p>
-                <p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If entity is not associated with a grid radius does not accept None; omit the argument entirely to use the grid default.</p>
+                <p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If entity is not associated with a grid TypeError: If radius is neither an int nor None</p>
            </div>
        </div>

@ -2619,7 +2617,7 @@ Keyword Args:
                <li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
                <li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
                <li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
-                <li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.</li>
+                <li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (Texture | None, read-only).</li>
                <li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
                <li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
                <li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
@ -2741,7 +2739,7 @@ Keyword Args:
                <li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
                <li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
                <li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
-                <li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.</li>
+                <li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (Texture | None, read-only).</li>
                <li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
                <li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
                <li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
--- a/docs/mcrfpy.3
+++ b/docs/mcrfpy.3
@ -14,11 +14,11 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "MCRFPY" "3" "2026-06-21" "McRogueFace 0.2.7-prerelease-7drl2026-107-g3f39ee0" ""
+.TH "MCRFPY" "3" "2026-06-21" "McRogueFace 0.2.7-prerelease-7drl2026-108-g2654253" ""
 .hy
 .SH McRogueFace API Reference
 .PP
-\f[I]Generated on 2026-06-21 09:39:04\f[R]
+\f[I]Generated on 2026-06-21 10:11:50\f[R]
 .PP
 \f[I]This documentation was dynamically generated from the compiled
 module.\f[R]
@ -2201,22 +2201,19 @@ Note:
 .PP
 \f[B]Returns:\f[R] None Called automatically when the entity moves if
 the grid has FOV configured.
-.SS \f[V]visible_entities(fov=None, radius: int = -1) -> list[Entity]\f[R]
+.SS \f[V]visible_entities(fov=None, radius: int | None = None) -> list[Entity]\f[R]
 .PP
 Get list of other entities visible from this entity\[cq]s position.
 .PP
-Note:
-.PP
 \f[B]Arguments:\f[R] - \f[V]fov\f[R]: FOV algorithm to use (FOV enum or
-None to use grid.fov) - \f[V]radius\f[R]: FOV radius as int; omit or
-pass -1 to use the grid\[cq]s default fov_radius
+None to use grid.fov) - \f[V]radius\f[R]: FOV radius as int; pass None,
+omit, or pass -1 to use the grid\[cq]s default fov_radius
 .PP
 \f[B]Returns:\f[R] List of Entity objects within field of view,
 excluding self
 .PP
 \f[B]Raises:\f[R] ValueError: If entity is not associated with a grid
-radius does not accept None; omit the argument entirely to use the grid
-default.
+TypeError: If radius is neither an int nor None
 .SS Entity3D
 .PP
 Entity3D(pos=None, **kwargs)
@ -2724,8 +2721,7 @@ Animatable property.
 When set, the drawable is rendered through the shader program.
 Set to None to disable shader effects.
 - \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile
-rendering (None, read-only).
-Texture return is not yet implemented; always returns None.
+rendering (Texture | None, read-only).
 - \f[V]uniforms\f[R] \f[I](read-only)\f[R]: Collection of shader
 uniforms (read-only access to collection).
 Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.
@ -2889,8 +2885,7 @@ Animatable property.
 When set, the drawable is rendered through the shader program.
 Set to None to disable shader effects.
 - \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile
-rendering (None, read-only).
-Texture return is not yet implemented; always returns None.
+rendering (Texture | None, read-only).
 - \f[V]uniforms\f[R] \f[I](read-only)\f[R]: Collection of shader
 uniforms (read-only access to collection).
 Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.