F15: correct docstring accuracy from adversarial verify pass (#314)

Follow-up to the macro conversion: an adversarial verify pass (one agent per
file vs. the C++ implementation + stubs) found 62 content issues; the real
ones are fixed here.

Callbacks (centralized):
- on_click: receives (pos, MouseButton, InputState), not str (8 files).
- on_enter/on_exit/on_move (UIBase.h): hover passes only (pos) -- removed the
  fictional button/action args.
- bounds/global_bounds (UIBase.h): mark (tuple, read-only).

Signatures / types:
- Grid.find_path: document heuristic + weight; get_dijkstra_map: document roots;
  compute_fov: FOV | int = FOV.BASIC (not the C constant FOV_BASIC) + Returns;
  at/is_in_fov: document (pos) and (x, y) call forms.
- get_metrics: document all 16 returned dict keys (was 8); bresenham: drop the
  bogus '*' keyword-only separator.
- Nullable defaults typed correctly: BSP seed/size, ColorLayer draw_fov/
  apply_perspective Color|None, Entity.visible_entities radius int=-1 (None is
  rejected by the 'i' parser -> see #319).
- Type-token fixes: GridView.center -> Vector; GridView.texture -> (None,
  read-only) (unimplemented, #318); GridPoint.grid_pos -> (tuple, read-only);
  EntityCollection.find -> Entity | list[Entity] | None; extend RuntimeError;
  UniformCollection.values -> list[float | tuple | None].
- automation: onScreen (x, y) form documented; scroll notes x is ignored (#317).

Also: correct stale AStarPath/DijkstraMap signatures in docs/api-audit-2026-04.md
(the bindings were right, the audit table was outdated). Rebaseline the API
snapshot golden and regenerate docs/stubs.

Code-level bugs surfaced by the pass are filed as #317, #318, #319.

Refs #314, #317, #318, #319

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/API_REFERENCE_DYNAMIC.md

@@ -1,6 +1,6 @@
 # McRogueFace API Reference
 
-*Generated on 2026-06-21 01:18:30*
+*Generated on 2026-06-21 06:42:31*
 
 *This documentation was dynamically generated from the compiled module.*
 
@@ -70,7 +70,7 @@
 
 ## Functions
 
-### `bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]`
+### `bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]`
 
 Compute grid cells along a line using Bresenham's algorithm.
 
@@ -130,7 +130,7 @@ Note:
 
 Get current performance metrics.
 
-**Returns:** dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)
+**Returns:** dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids)
 
 ### `lock() -> _LockContext`
 
@@ -402,11 +402,11 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `center`: Center position of the arc (Vector).
 - `color`: Arc fill color (Color).
 - `end_angle`: Ending angle in degrees (float).
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid).
 - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -414,10 +414,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding this element (str).
-- `on_click`: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -583,14 +583,16 @@ Remove all children, keeping only the root node with original bounds. WARNING: I
 
 **Returns:** BSP: self, for method chaining
 
-#### `find(pos: tuple[int, int]) -> BSPNode | None`
+#### `find(pos: tuple[int, int] | list | Vector) -> BSPNode | None`
 
 Find the smallest (deepest) node containing the position.
 
+Note:
+
 **Arguments:**
 - `pos`: Position as (x, y) tuple, list, or Vector
 
-**Returns:** BSPNode if found, None if position is outside bounds
+**Returns:** BSPNode if found, None if position is outside bounds Also accepts two separate int arguments: find(x, y)
 
 #### `get_leaf(index: int) -> BSPNode`
 
@@ -619,7 +621,7 @@ Split the root node once at the specified position. horizontal=True creates a ho
 
 **Returns:** BSP: self, for method chaining
 
-#### `split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP`
+#### `split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP`
 
 Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree.
 
@@ -631,7 +633,7 @@ Recursively split to the specified depth. WARNING: Invalidates all existing BSPN
 
 **Returns:** BSP: self, for method chaining
 
-#### `to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap`
+#### `to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap`
 
 Convert BSP node selection to a HeightMap.
 
@@ -867,10 +869,10 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `fill_color`: Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
 - `font_size`: Font size in points (int). Clamped to the range [0, 65535].
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector). Only valid when parent is a Grid.
 - `grid_size`: Size in grid tile coordinates (Vector). Only valid when parent is a Grid.
@@ -879,10 +881,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding elements (str).
-- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `outline`: Thickness of the text outline border (float). Clamped to non-negative values.
@@ -997,10 +999,10 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `center`: Center position of the circle (Vector).
 - `fill_color`: Fill color of the circle (Color).
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
 - `grid_size`: Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
@@ -1008,10 +1010,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding this element (str).
-- `on_click`: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `outline`: Outline thickness in pixels (float). Use 0 for no outline.
@@ -1207,7 +1209,7 @@ Interpolate between two colors based on HeightMap value within a range. Uses the
 
 **Returns:** self for method chaining
 
-#### `apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None`
+#### `apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None`
 
 Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.
 
@@ -1240,7 +1242,7 @@ Set a fixed color for cells where the HeightMap value falls within a range.
 
 **Returns:** self for method chaining
 
-#### `at(pos) or (x: int, y: int) -> Color`
+#### `at(pos: tuple | Vector) or (x: int, y: int) -> Color`
 
 Get the color at a cell position.
 
@@ -1255,7 +1257,7 @@ Get the color at a cell position.
 
 Remove the perspective binding from this layer.
 
-#### `draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None`
+#### `draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None`
 
 Paint cells based on field-of-view visibility from a source position.
 
@@ -1657,7 +1659,7 @@ Convert to HeightMap, optionally mapping values to floats.
 Base class for all drawable UI elements
 
 **Properties:**
-- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
+- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
 - `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
@@ -1860,7 +1862,7 @@ Create and start an animation on this entity's property.
 Note:
 
 **Arguments:**
-- `property`: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index'
+- `property`: Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index', 'sprite_offset_x', 'sprite_offset_y'
 - `target`: Target value - float, int, or list of int (for sprite frame sequences)
 - `duration`: Animation duration in seconds
 - `easing`: Easing function: Easing enum value, string name, or None for linear
@@ -1871,7 +1873,7 @@ Note:
 
 **Returns:** Animation object for monitoring progress
 
-**Raises:** ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations.
+**Raises:** ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y) Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. 'x' and 'y' are accepted as aliases for 'draw_x' and 'draw_y'.
 
 #### `at(x: int, y: int) -> GridPoint | None`
 
@@ -1987,17 +1989,19 @@ Note:
 
 **Returns:** None Called automatically when the entity moves if the grid has FOV configured.
 
-#### `visible_entities(fov=None, radius: int = None) -> list[Entity]`
+#### `visible_entities(fov=None, radius: int = -1) -> 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 (int or None to use grid.fov_radius)
+- `radius`: FOV radius as int; 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
+**Raises:** ValueError: If entity is not associated with a grid radius does not accept None; omit the argument entirely to use the grid default.
 
 ### Entity3D
 
@@ -2292,12 +2296,12 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `cache_subtree`: Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees.
 - `children` *(read-only)*: UICollection of child drawable objects rendered on top of this frame (UICollection, read-only).
 - `clip_children`: Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True.
 - `fill_color`: Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
 - `grid_size`: Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
@@ -2306,10 +2310,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding elements (str).
-- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `outline`: Thickness of the border in pixels (float).
@@ -2412,13 +2416,13 @@ Keyword Args:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `camera_rotation`: Rotation of grid contents around camera center in degrees (float).
-- `center`: Camera center point in pixel coordinates (tuple).
+- `center`: Camera center point in pixel coordinates (Vector).
 - `center_x`: Camera center X-coordinate in pixel space (float).
 - `center_y`: Camera center Y-coordinate in pixel space (float).
 - `fill_color`: Background fill color (Color). Drawn behind all tiles and entities.
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_data`: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
 - `h`: Visible widget height (float).
@@ -2427,9 +2431,9 @@ Keyword Args:
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding elements (str).
 - `on_click`: Callable executed when object is clicked (Callable | None).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -2437,7 +2441,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 (Texture | None, read-only).
+- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
 - `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.
@@ -2532,13 +2536,13 @@ Keyword Args:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `camera_rotation`: Rotation of grid contents around camera center in degrees (float).
-- `center`: Camera center point in pixel coordinates (tuple).
+- `center`: Camera center point in pixel coordinates (Vector).
 - `center_x`: Camera center X-coordinate in pixel space (float).
 - `center_y`: Camera center Y-coordinate in pixel space (float).
 - `fill_color`: Background fill color (Color). Drawn behind all tiles and entities.
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_data`: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
 - `h`: Visible widget height (float).
@@ -2547,9 +2551,9 @@ Keyword Args:
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding elements (str).
 - `on_click`: Callable executed when object is clicked (Callable | None).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -2557,7 +2561,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 (Texture | None, read-only).
+- `texture` *(read-only)*: Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
 - `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.
@@ -3427,10 +3431,10 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `color`: Line color as a Color object.
 - `end`: Ending point of the line as a Vector.
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid).
 - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -3438,10 +3442,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding this element.
-- `on_click`: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -4264,8 +4268,8 @@ Attributes:
 
 **Properties:**
 - `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_pos`: Position in grid tile coordinates (Vector, only when parent is Grid).
 - `grid_size`: Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -4273,10 +4277,10 @@ Attributes:
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
 - `margin`: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
 - `name`: Name for finding elements (str).
-- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -4508,7 +4512,7 @@ Set a tile index for cells where the HeightMap value falls within a range.
 
 **Returns:** self for method chaining
 
-#### `at(pos) or (x: int, y: int) -> int`
+#### `at(pos: tuple | Vector) or (x: int, y: int) -> int`
 
 Get the tile index at a cell position. Returns -1 if no tile is set.
 
@@ -5169,7 +5173,7 @@ Keyword Args:
 
 **Properties:**
 - `bg_color`: Background clear color.
-- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+- `bounds` *(read-only)*: Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `camera_pos`: Camera position as (x, y, z) tuple.
 - `camera_target`: Camera look-at target as (x, y, z) tuple.
 - `cell_size`: World units per navigation grid cell.
@@ -5182,15 +5186,15 @@ Keyword Args:
 - `fog_far`: Fog end distance.
 - `fog_near`: Fog start distance.
 - `fov`: Camera field of view in degrees.
-- `global_bounds`: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+- `global_bounds` *(read-only)*: Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
 - `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
 - `grid_size`: Navigation grid dimensions as (width, depth) tuple.
 - `h`: Display height in pixels.
 - `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
-- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-- `on_enter`: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
+- `on_click`: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+- `on_enter`: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+- `on_exit`: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
 - `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
 - `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
 - `pos`: Position as Vector (x, y).

docs/api-audit-2026-04.md

@@ -660,8 +660,8 @@ NoiseSource(dimensions=2, algorithm='simplex', hurst=0.5, lacunarity=2.0, seed=N
 
 | Methods | Signature |
 |---------|-----------|
-| `walk` | `() -> tuple` |
-| `peek` | `() -> tuple` |
+| `walk` | `() -> Vector` |
+| `peek` | `() -> Vector` |
 
 Protocols: `len`, `bool`, iteration
 
@@ -673,10 +673,10 @@ Protocols: `len`, `bool`, iteration
 
 | Methods | Signature |
 |---------|-----------|
-| `distance` | `(x, y) -> float` |
-| `path_from` | `(x, y) -> list` |
-| `step_from` | `(x, y) -> tuple` |
-| `to_heightmap` | `() -> HeightMap` |
+| `distance` | `(pos) -> float \| None` |
+| `path_from` | `(pos) -> AStarPath` |
+| `step_from` | `(pos) -> Vector \| None` |
+| `to_heightmap` | `(size=None, unreachable=-1.0) -> HeightMap` |
 
 ---
 

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 01:18:30</em></p>
+        <p><em>Generated on 2026-06-21 06:42:31</em></p>
         <p><em>This documentation was dynamically generated from the compiled module.</em></p>
         
         <div class="toc">
@@ -184,7 +184,7 @@
         <h2 id="functions">Functions</h2>
 
         <div class="method-section">
-            <h3><code class="function-signature">bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]</code></h3>
+            <h3><code class="function-signature">bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]</code></h3>
             <p>Compute grid cells along a line using Bresenham&#x27;s algorithm.
 
 Note:</p>
@@ -244,7 +244,7 @@ Note:</p>
         <div class="method-section">
             <h3><code class="function-signature">get_metrics() -> dict</code></h3>
             <p>Get current performance metrics.</p>
-            <p><span class='returns'>Returns:</span> dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)</p>
+            <p><span class='returns'>Returns:</span> dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids)</p>
         </div>
 
         <div class="method-section">
@@ -524,11 +524,11 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>center</span>: Center position of the arc (Vector).</li>
                 <li><span class='property-name'>color</span>: Arc fill color (Color).</li>
                 <li><span class='property-name'>end_angle</span>: Ending angle in degrees (float).</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector, only when parent is Grid).</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector, only when parent is Grid).</li>
@@ -536,10 +536,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding this element (str).</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
@@ -711,12 +711,14 @@ Example:
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">find(pos: tuple[int, int]) -> BSPNode | None</code></h5>
-                <p>Find the smallest (deepest) node containing the position.</p>
+                <h5><code class="method-name">find(pos: tuple[int, int] | list | Vector) -> BSPNode | None</code></h5>
+                <p>Find the smallest (deepest) node containing the position.
+
+Note:</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
                 </div>
-                <p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSPNode if found, None if position is outside bounds</p>
+                <p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSPNode if found, None if position is outside bounds Also accepts two separate int arguments: find(x, y)</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
@@ -746,7 +748,7 @@ Example:
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP</code></h5>
+                <h5><code class="method-name">split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP</code></h5>
                 <p>Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree.</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>depth</span>: Maximum recursion depth (1-16). Creates up to 2^depth leaves.</div>
@@ -758,7 +760,7 @@ Example:
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap</code></h5>
+                <h5><code class="method-name">to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap</code></h5>
                 <p>Convert BSP node selection to a HeightMap.</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>size</span>: Output size (width, height). Default: bounds size.</div>
@@ -1002,10 +1004,10 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>fill_color</span>: Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use &#x27;fill_color.r&#x27;, &#x27;fill_color.g&#x27;, etc.</li>
                 <li><span class='property-name'>font_size</span>: Font size in points (int). Clamped to the range [0, 65535].</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector). Only valid when parent is a Grid.</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector). Only valid when parent is a Grid.</li>
@@ -1014,10 +1016,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding elements (str).</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>outline</span>: Thickness of the text outline border (float). Clamped to non-negative values.</li>
@@ -1134,10 +1136,10 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>center</span>: Center position of the circle (Vector).</li>
                 <li><span class='property-name'>fill_color</span>: Fill color of the circle (Color).</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid.</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid.</li>
@@ -1145,10 +1147,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding this element (str).</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>outline</span>: Outline thickness in pixels (float). Use 0 for no outline.</li>
@@ -1348,7 +1350,7 @@ Example:
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None</code></h5>
+                <h5><code class="method-name">apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None</code></h5>
                 <p>Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>entity</span>: The entity whose perspective to track</div>
@@ -1382,7 +1384,7 @@ Note:</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">at(pos) or (x: int, y: int) -> Color</code></h5>
+                <h5><code class="method-name">at(pos: tuple | Vector) or (x: int, y: int) -> Color</code></h5>
                 <p>Get the color at a cell position.</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector; or pass x and y separately</div>
@@ -1397,7 +1399,7 @@ Note:</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None</code></h5>
+                <h5><code class="method-name">draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None</code></h5>
                 <p>Paint cells based on field-of-view visibility from a source position.
 
 Note:</p>
@@ -1802,7 +1804,7 @@ Example:
             <p>Base class for all drawable UI elements</p>
             <h4>Properties:</h4>
             <ul>
-                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
                 <li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
@@ -2015,7 +2017,7 @@ Attributes:
 
 Note:</p>
                 <div style='margin-left: 20px;'>
-                    <div><span class='arg-name'>property</span>: Name of the property to animate: &#x27;draw_x&#x27;, &#x27;draw_y&#x27; (tile coords), &#x27;sprite_scale&#x27;, &#x27;sprite_index&#x27;</div>
+                    <div><span class='arg-name'>property</span>: Name of the property to animate: &#x27;draw_x&#x27;, &#x27;draw_y&#x27; (tile coords), &#x27;sprite_scale&#x27;, &#x27;sprite_index&#x27;, &#x27;sprite_offset_x&#x27;, &#x27;sprite_offset_y&#x27;</div>
                     <div><span class='arg-name'>target</span>: Target value - float, int, or list of int (for sprite frame sequences)</div>
                     <div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
                     <div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
@@ -2025,7 +2027,7 @@ Note:</p>
                     <div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
                 </div>
                 <p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
-                <p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index) Use &#x27;draw_x&#x27;/&#x27;draw_y&#x27; to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations.</p>
+                <p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y) Use &#x27;draw_x&#x27;/&#x27;draw_y&#x27; to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations. &#x27;x&#x27; and &#x27;y&#x27; are accepted as aliases for &#x27;draw_x&#x27; and &#x27;draw_y&#x27;.</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
@@ -2142,14 +2144,16 @@ Note:</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">visible_entities(fov=None, radius: int = None) -> list[Entity]</code></h5>
-                <p>Get list of other entities visible from this entity&#x27;s position.</p>
+                <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>
                 <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 (int or None to use grid.fov_radius)</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>
                 <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</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>
             </div>
         </div>
 
@@ -2468,12 +2472,12 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>cache_subtree</span>: Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees.</li>
                 <li><span class='property-name'>children</span> (read-only): UICollection of child drawable objects rendered on top of this frame (UICollection, read-only).</li>
                 <li><span class='property-name'>clip_children</span>: Whether to clip child elements to the frame&#x27;s bounds (bool). Enables render-texture mode when True.</li>
                 <li><span class='property-name'>fill_color</span>: Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use &#x27;fill_color.r&#x27;, &#x27;fill_color.g&#x27;, etc.</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector). Only meaningful when this element&#x27;s parent is a Grid.</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector). Only meaningful when this element&#x27;s parent is a Grid.</li>
@@ -2482,10 +2486,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding elements (str).</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>outline</span>: Thickness of the border in pixels (float).</li>
@@ -2590,13 +2594,13 @@ Keyword Args:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>camera_rotation</span>: Rotation of grid contents around camera center in degrees (float).</li>
-                <li><span class='property-name'>center</span>: Camera center point in pixel coordinates (tuple).</li>
+                <li><span class='property-name'>center</span>: Camera center point in pixel coordinates (Vector).</li>
                 <li><span class='property-name'>center_x</span>: Camera center X-coordinate in pixel space (float).</li>
                 <li><span class='property-name'>center_y</span>: Camera center Y-coordinate in pixel space (float).</li>
                 <li><span class='property-name'>fill_color</span>: Background fill color (Color). Drawn behind all tiles and entities.</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_data</span>: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.</li>
                 <li><span class='property-name'>h</span>: Visible widget height (float).</li>
@@ -2605,9 +2609,9 @@ Keyword Args:
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding elements (str).</li>
                 <li><span class='property-name'>on_click</span>: Callable executed when object is clicked (Callable | None).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
@@ -2615,7 +2619,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 (Texture | None, read-only).</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'>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>
@@ -2712,13 +2716,13 @@ Keyword Args:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>camera_rotation</span>: Rotation of grid contents around camera center in degrees (float).</li>
-                <li><span class='property-name'>center</span>: Camera center point in pixel coordinates (tuple).</li>
+                <li><span class='property-name'>center</span>: Camera center point in pixel coordinates (Vector).</li>
                 <li><span class='property-name'>center_x</span>: Camera center X-coordinate in pixel space (float).</li>
                 <li><span class='property-name'>center_y</span>: Camera center Y-coordinate in pixel space (float).</li>
                 <li><span class='property-name'>fill_color</span>: Background fill color (Color). Drawn behind all tiles and entities.</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_data</span>: The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.</li>
                 <li><span class='property-name'>h</span>: Visible widget height (float).</li>
@@ -2727,9 +2731,9 @@ Keyword Args:
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding elements (str).</li>
                 <li><span class='property-name'>on_click</span>: Callable executed when object is clicked (Callable | None).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
@@ -2737,7 +2741,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 (Texture | None, read-only).</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'>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>
@@ -3625,10 +3629,10 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>color</span>: Line color as a Color object.</li>
                 <li><span class='property-name'>end</span>: Ending point of the line as a Vector.</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector, only when parent is Grid).</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector, only when parent is Grid).</li>
@@ -3636,10 +3640,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding this element.</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
@@ -4513,8 +4517,8 @@ Attributes:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (Vector, only when parent is Grid).</li>
                 <li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (Vector, only when parent is Grid).</li>
@@ -4522,10 +4526,10 @@ Attributes:
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
                 <li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
                 <li><span class='property-name'>name</span>: Name for finding elements (str).</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
@@ -4760,7 +4764,7 @@ Note:</p>
             </div>
 
             <div style="margin-left: 20px; margin-bottom: 15px;">
-                <h5><code class="method-name">at(pos) or (x: int, y: int) -> int</code></h5>
+                <h5><code class="method-name">at(pos: tuple | Vector) or (x: int, y: int) -> int</code></h5>
                 <p>Get the tile index at a cell position. Returns -1 if no tile is set.</p>
                 <div style='margin-left: 20px;'>
                     <div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector; or pass x and y separately</div>
@@ -5446,7 +5450,7 @@ Keyword Args:
             <h4>Properties:</h4>
             <ul>
                 <li><span class='property-name'>bg_color</span>: Background clear color.</li>
-                <li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>bounds</span> (read-only): Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>camera_pos</span>: Camera position as (x, y, z) tuple.</li>
                 <li><span class='property-name'>camera_target</span>: Camera look-at target as (x, y, z) tuple.</li>
                 <li><span class='property-name'>cell_size</span>: World units per navigation grid cell.</li>
@@ -5459,15 +5463,15 @@ Keyword Args:
                 <li><span class='property-name'>fog_far</span>: Fog end distance.</li>
                 <li><span class='property-name'>fog_near</span>: Fog start distance.</li>
                 <li><span class='property-name'>fov</span>: Camera field of view in degrees.</li>
-                <li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
+                <li><span class='property-name'>global_bounds</span> (read-only): Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).</li>
                 <li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
                 <li><span class='property-name'>grid_size</span>: Navigation grid dimensions as (width, depth) tuple.</li>
                 <li><span class='property-name'>h</span>: Display height in pixels.</li>
                 <li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
-                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
-                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
-                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
+                <li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).</li>
+                <li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element&#x27;s bounds.</li>
+                <li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
                 <li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
                 <li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
                 <li><span class='property-name'>pos</span>: Position as Vector (x, y).</li>

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-103-g39c2340" ""
+.TH "MCRFPY" "3" "2026-06-21" "McRogueFace 0.2.7-prerelease-7drl2026-104-g5725a4f" ""
 .hy
 .SH McRogueFace API Reference
 .PP
-\f[I]Generated on 2026-06-21 01:18:30\f[R]
+\f[I]Generated on 2026-06-21 06:42:31\f[R]
 .PP
 \f[I]This documentation was dynamically generated from the compiled
 module.\f[R]
@@ -148,7 +148,7 @@ Window
 .IP \[bu] 2
 Constants
 .SS Functions
-.SS \f[V]bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]\f[R]
+.SS \f[V]bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]\f[R]
 .PP
 Compute grid cells along a line using Bresenham\[cq]s algorithm.
 .PP
@@ -213,7 +213,14 @@ Get current performance metrics.
 frame duration in seconds), avg_frame_time (average frame time), fps
 (frames per second), draw_calls (number of draw calls), ui_elements
 (total UI element count), visible_elements (visible element count),
-current_frame (frame counter), runtime (total runtime in seconds)
+current_frame (frame counter), runtime (total runtime in seconds),
+grid_render_time (grid rendering time in ms), entity_render_time (entity
+rendering time in ms), fov_overlay_time (FOV overlay rendering time in
+ms), python_time (Python script execution time in ms), animation_time
+(animation processing time in ms), grid_cells_rendered (number of grid
+cells rendered this frame), entities_rendered (number of entities
+rendered this frame), total_entities (total entity count across all
+grids)
 .SS \f[V]lock() -> _LockContext\f[R]
 .PP
 Get a context manager for thread-safe UI updates from background
@@ -478,14 +485,15 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]center\f[R]: Center position of the arc (Vector).
 - \f[V]color\f[R]: Arc fill color (Color).
 - \f[V]end_angle\f[R]: Ending angle in degrees (float).
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -505,16 +513,14 @@ Applied to both horizontal and vertical edges unless overridden.
 Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding this element (str).
 - \f[V]on_click\f[R]: Callable executed when arc is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -701,14 +707,17 @@ Remove all children, keeping only the root node with original bounds.
 WARNING: Invalidates all existing BSPNode references from this tree.
 .PP
 \f[B]Returns:\f[R] BSP: self, for method chaining
-.SS \f[V]find(pos: tuple[int, int]) -> BSPNode | None\f[R]
+.SS \f[V]find(pos: tuple[int, int] | list | Vector) -> BSPNode | None\f[R]
 .PP
 Find the smallest (deepest) node containing the position.
 .PP
+Note:
+.PP
 \f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
 Vector
 .PP
 \f[B]Returns:\f[R] BSPNode if found, None if position is outside bounds
+Also accepts two separate int arguments: find(x, y)
 .SS \f[V]get_leaf(index: int) -> BSPNode\f[R]
 .PP
 Get a leaf node by its index (0 to len(bsp)-1).
@@ -739,7 +748,7 @@ horizontal=False creates a vertical divider, producing left/right rooms.
 Split coordinate (y for horizontal, x for vertical)
 .PP
 \f[B]Returns:\f[R] BSP: self, for method chaining
-.SS \f[V]split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP\f[R]
+.SS \f[V]split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP\f[R]
 .PP
 Recursively split to the specified depth.
 WARNING: Invalidates all existing BSPNode references from this tree.
@@ -754,7 +763,7 @@ Default: 1.5.
 None for random.
 .PP
 \f[B]Returns:\f[R] BSP: self, for method chaining
-.SS \f[V]to_heightmap(size: tuple[int, int] = None, select: str = \[aq]leaves\[aq], shrink: int = 0, value: float = 1.0) -> HeightMap\f[R]
+.SS \f[V]to_heightmap(size: tuple[int, int] | None = None, select: str = \[aq]leaves\[aq], shrink: int = 0, value: float = 1.0) -> HeightMap\f[R]
 .PP
 Convert BSP node selection to a HeightMap.
 .PP
@@ -967,16 +976,17 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]fill_color\f[R]: Fill color of the text (Color).
 Returns a copy; modifying components requires reassignment.
 For animation, use `fill_color.r', `fill_color.g', etc.
 - \f[V]font_size\f[R]: Font size in points (int).
 Clamped to the range [0, 65535].
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -998,16 +1008,14 @@ Applied to both horizontal and vertical edges unless overridden.
 Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding elements (str).
 - \f[V]on_click\f[R]: Callable executed when object is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -1144,13 +1152,14 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]center\f[R]: Center position of the circle (Vector).
 - \f[V]fill_color\f[R]: Fill color of the circle (Color).
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -1171,16 +1180,14 @@ Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding this element (str).
 - \f[V]on_click\f[R]: Callable executed when circle is clicked (Callable
 | None).
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -1401,7 +1408,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive
 Color at range maximum
 .PP
 \f[B]Returns:\f[R] self for method chaining
-.SS \f[V]apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None\f[R]
+.SS \f[V]apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None\f[R]
 .PP
 Bind this layer to an entity for automatic FOV updates.
 After binding, call update_perspective() when the entity moves.
@@ -1434,7 +1441,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive
 range
 .PP
 \f[B]Returns:\f[R] self for method chaining
-.SS \f[V]at(pos) or (x: int, y: int) -> Color\f[R]
+.SS \f[V]at(pos: tuple | Vector) or (x: int, y: int) -> Color\f[R]
 .PP
 Get the color at a cell position.
 .PP
@@ -1447,7 +1454,7 @@ Vector; or pass x and y separately
 .SS \f[V]clear_perspective() -> None\f[R]
 .PP
 Remove the perspective binding from this layer.
-.SS \f[V]draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None\f[R]
+.SS \f[V]draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None\f[R]
 .PP
 Paint cells based on field-of-view visibility from a source position.
 .PP
@@ -1813,7 +1820,8 @@ Base class for all drawable UI elements
 .PP
 \f[B]Properties:\f[R] - \f[V]on_click\f[R]: Callable executed when
 object is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -2058,23 +2066,25 @@ Note:
 .PP
 \f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
 animate: `draw_x', `draw_y' (tile coords), `sprite_scale',
-`sprite_index' - \f[V]target\f[R]: Target value - float, int, or list of
-int (for sprite frame sequences) - \f[V]duration\f[R]: Animation
-duration in seconds - \f[V]easing\f[R]: Easing function: Easing enum
-value, string name, or None for linear - \f[V]delta\f[R]: If True,
-target is relative to current value; if False, target is absolute -
-\f[V]loop\f[R]: If True, animation repeats from start when it reaches
-the end (default False) - \f[V]callback\f[R]: Optional callable invoked
-when animation completes (not called for looping animations) -
-\f[V]conflict_mode\f[R]: `replace' (default), `queue', or `error' if
-property already animating
+`sprite_index', `sprite_offset_x', `sprite_offset_y' - \f[V]target\f[R]:
+Target value - float, int, or list of int (for sprite frame sequences) -
+\f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
+Easing function: Easing enum value, string name, or None for linear -
+\f[V]delta\f[R]: If True, target is relative to current value; if False,
+target is absolute - \f[V]loop\f[R]: If True, animation repeats from
+start when it reaches the end (default False) - \f[V]callback\f[R]:
+Optional callable invoked when animation completes (not called for
+looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
+`queue', or `error' if property already animating
 .PP
 \f[B]Returns:\f[R] Animation object for monitoring progress
 .PP
 \f[B]Raises:\f[R] ValueError: If property name is not valid for Entity
-(draw_x, draw_y, sprite_scale, sprite_index) Use `draw_x'/`draw_y' to
-animate tile coordinates for smooth movement between grid cells.
+(draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x,
+sprite_offset_y) Use `draw_x'/`draw_y' to animate tile coordinates for
+smooth movement between grid cells.
 Use list target with loop=True for repeating sprite frame animations.
+`x' and `y' are accepted as aliases for `draw_x' and `draw_y'.
 .SS \f[V]at(x: int, y: int) -> GridPoint | None\f[R]
 .PP
 Return the GridPoint at (x, y) if currently VISIBLE to this entity\[cq]s
@@ -2184,18 +2194,22 @@ 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 = None) -> list[Entity]\f[R]
+.SS \f[V]visible_entities(fov=None, radius: int = -1) -> 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 (int or None to use
-grid.fov_radius)
+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
 .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.
 .SS Entity3D
 .PP
 Entity3D(pos=None, **kwargs)
@@ -2469,8 +2483,9 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]cache_subtree\f[R]: Cache the frame and all children to a render
 texture for performance (bool).
 Useful for complex static subtrees.
@@ -2483,9 +2498,9 @@ Enables render-texture mode when True.
 - \f[V]fill_color\f[R]: Fill color of the rectangle (Color).
 Returns a copy; modifying components requires reassignment.
 For animation, use `fill_color.r', `fill_color.g', etc.
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -2506,16 +2521,14 @@ Applied to both horizontal and vertical edges unless overridden.
 Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding elements (str).
 - \f[V]on_click\f[R]: Callable executed when object is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -2643,18 +2656,19 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]camera_rotation\f[R]: Rotation of grid contents around camera
 center in degrees (float).
-- \f[V]center\f[R]: Camera center point in pixel coordinates (tuple).
+- \f[V]center\f[R]: Camera center point in pixel coordinates (Vector).
 - \f[V]center_x\f[R]: Camera center X-coordinate in pixel space (float).
 - \f[V]center_y\f[R]: Camera center Y-coordinate in pixel space (float).
 - \f[V]fill_color\f[R]: Background fill color (Color).
 Drawn behind all tiles and entities.
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -2675,14 +2689,11 @@ Invalid for CENTER alignment (raises ValueError).
 - \f[V]on_click\f[R]: Callable executed when object is clicked (Callable
 | None).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -2706,7 +2717,8 @@ 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 (Texture | None, read-only).
+rendering (None, read-only).
+Texture return is not yet implemented; always returns None.
 - \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.
@@ -2809,18 +2821,19 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]camera_rotation\f[R]: Rotation of grid contents around camera
 center in degrees (float).
-- \f[V]center\f[R]: Camera center point in pixel coordinates (tuple).
+- \f[V]center\f[R]: Camera center point in pixel coordinates (Vector).
 - \f[V]center_x\f[R]: Camera center X-coordinate in pixel space (float).
 - \f[V]center_y\f[R]: Camera center Y-coordinate in pixel space (float).
 - \f[V]fill_color\f[R]: Background fill color (Color).
 Drawn behind all tiles and entities.
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -2841,14 +2854,11 @@ Invalid for CENTER alignment (raises ValueError).
 - \f[V]on_click\f[R]: Callable executed when object is clicked (Callable
 | None).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -2872,7 +2882,8 @@ 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 (Texture | None, read-only).
+rendering (None, read-only).
+Texture return is not yet implemented; always returns None.
 - \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.
@@ -3666,13 +3677,14 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]color\f[R]: Line color as a Color object.
 - \f[V]end\f[R]: Ending point of the line as a Vector.
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -3692,16 +3704,14 @@ Applied to both horizontal and vertical edges unless overridden.
 Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding this element.
 - \f[V]on_click\f[R]: Callable executed when line is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -4527,11 +4537,12 @@ bounds (Alignment enum or None).
 When set, position is automatically calculated when parent is assigned
 or resized.
 Set to None to disable alignment and use manual positioning.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -4551,16 +4562,14 @@ Applied to both horizontal and vertical edges unless overridden.
 Invalid for CENTER alignment (raises ValueError).
 - \f[V]name\f[R]: Name for finding elements (str).
 - \f[V]on_click\f[R]: Callable executed when object is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
@@ -4837,7 +4846,7 @@ layer dimensions) - \f[V]range\f[R]: Value range as (min, max) inclusive
 - \f[V]tile\f[R]: Tile index to set for cells in range
 .PP
 \f[B]Returns:\f[R] self for method chaining
-.SS \f[V]at(pos) or (x: int, y: int) -> int\f[R]
+.SS \f[V]at(pos: tuple | Vector) or (x: int, y: int) -> int\f[R]
 .PP
 Get the tile index at a cell position.
 Returns -1 if no tile is set.
@@ -5459,8 +5468,9 @@ Default: 10 fog_far (float): Fog end distance.
 Default: 100
 .PP
 \f[B]Properties:\f[R] - \f[V]bg_color\f[R]: Background clear color.
-- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding box
+(tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y),
+Vector(width, height)).
 - \f[V]camera_pos\f[R]: Camera position as (x, y, z) tuple.
 - \f[V]camera_target\f[R]: Camera look-at target as (x, y, z) tuple.
 - \f[V]cell_size\f[R]: World units per navigation grid cell.
@@ -5477,9 +5487,9 @@ Use append/remove to modify.
 - \f[V]fog_far\f[R]: Fog end distance.
 - \f[V]fog_near\f[R]: Fog start distance.
 - \f[V]fov\f[R]: Camera field of view in degrees.
-- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
-in screen coordinates.
-Returns (Vector(x, y), Vector(width, height)).
+- \f[V]global_bounds\f[R] \f[I](read-only)\f[R]: Axis-aligned bounding
+box in screen coordinates (tuple, read-only) as a (pos, size) pair of
+Vectors: (Vector(x, y), Vector(width, height)).
 - \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
 position (read-only).
 Calculates absolute position by walking up the parent chain.
@@ -5490,16 +5500,14 @@ tuple.
 over this element (read-only).
 Updated automatically by the engine during mouse movement.
 - \f[V]on_click\f[R]: Callable executed when object is clicked.
-Function receives (pos: Vector, button: str, action: str).
+Function receives (pos: Vector, button: MouseButton, action:
+InputState).
 - \f[V]on_enter\f[R]: Callback for mouse enter events.
-Called with (pos: Vector, button: str, action: str) when mouse enters
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse enters this element\[cq]s bounds.
 - \f[V]on_exit\f[R]: Callback for mouse exit events.
-Called with (pos: Vector, button: str, action: str) when mouse leaves
-this element\[cq]s bounds.
+Called with (pos: Vector) when mouse leaves this element\[cq]s bounds.
 - \f[V]on_move\f[R]: Callback for mouse movement within bounds.
-Called with (pos: Vector, button: str, action: str) for each mouse
-movement while inside.
+Called with (pos: Vector) for each mouse movement while inside.
 Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).

src/GridLayers.cpp

@@ -701,7 +701,7 @@ void TileLayer::render(sf::RenderTarget& target,
 PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = {
     {"at", (PyCFunction)PyGridLayerAPI::ColorLayer_at, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(ColorLayer, at,
-         MCRF_SIG("(pos) or (x: int, y: int)", "Color"),
+         MCRF_SIG("(pos: tuple | Vector) or (x: int, y: int)", "Color"),
          MCRF_DESC("Get the color at a cell position.")
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector; or pass x and y separately")
@@ -735,7 +735,7 @@ PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = {
      )},
     {"draw_fov", (PyCFunction)PyGridLayerAPI::ColorLayer_draw_fov, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(ColorLayer, draw_fov,
-         MCRF_SIG("(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None)", "None"),
+         MCRF_SIG("(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None)", "None"),
          MCRF_DESC("Paint cells based on field-of-view visibility from a source position.")
          MCRF_ARGS_START
          MCRF_ARG("source", "FOV origin as (x, y)")
@@ -748,7 +748,7 @@ PyMethodDef PyGridLayerAPI::ColorLayer_methods[] = {
      )},
     {"apply_perspective", (PyCFunction)PyGridLayerAPI::ColorLayer_apply_perspective, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(ColorLayer, apply_perspective,
-         MCRF_SIG("(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None)", "None"),
+         MCRF_SIG("(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None)", "None"),
          MCRF_DESC("Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves.")
          MCRF_ARGS_START
          MCRF_ARG("entity", "The entity whose perspective to track")
@@ -1881,7 +1881,7 @@ PyObject* PyGridLayerAPI::ColorLayer_repr(PyColorLayerObject* self) {
 PyMethodDef PyGridLayerAPI::TileLayer_methods[] = {
     {"at", (PyCFunction)PyGridLayerAPI::TileLayer_at, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(TileLayer, at,
-         MCRF_SIG("(pos) or (x: int, y: int)", "int"),
+         MCRF_SIG("(pos: tuple | Vector) or (x: int, y: int)", "int"),
          MCRF_DESC("Get the tile index at a cell position. Returns -1 if no tile is set.")
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector; or pass x and y separately")

src/McRFPy_API.cpp

@@ -306,7 +306,7 @@ static PyMethodDef mcrfpyMethods[] = {
      MCRF_METHOD(mcrfpy, get_metrics,
          MCRF_SIG("()", "dict"),
          MCRF_DESC("Get current performance metrics."),
-         MCRF_RETURNS("dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds)")
+         MCRF_RETURNS("dict: Performance data with keys: frame_time (last frame duration in seconds), avg_frame_time (average frame time), fps (frames per second), draw_calls (number of draw calls), ui_elements (total UI element count), visible_elements (visible element count), current_frame (frame counter), runtime (total runtime in seconds), grid_render_time (grid rendering time in ms), entity_render_time (entity rendering time in ms), fov_overlay_time (FOV overlay rendering time in ms), python_time (Python script execution time in ms), animation_time (animation processing time in ms), grid_cells_rendered (number of grid cells rendered this frame), entities_rendered (number of entities rendered this frame), total_entities (total entity count across all grids)")
      )},
 
     {"set_dev_console", McRFPy_API::_setDevConsole, METH_VARARGS,
@@ -369,7 +369,7 @@ static PyMethodDef mcrfpyMethods[] = {
     // #215: Bresenham line algorithm (replaces mcrfpy.libtcod.line)
     {"bresenham", (PyCFunction)McRFPy_API::_bresenham, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(mcrfpy, bresenham,
-         MCRF_SIG("(start, end, *, include_start=True, include_end=True)", "list[tuple[int, int]]"),
+         MCRF_SIG("(start, end, include_start=True, include_end=True)", "list[tuple[int, int]]"),
          MCRF_DESC("Compute grid cells along a line using Bresenham's algorithm."),
          MCRF_ARGS_START
          MCRF_ARG("start", "(x, y) tuple or Vector - starting point")

src/McRFPy_Automation.cpp

@@ -853,20 +853,22 @@ static PyMethodDef automationMethods[] = {
     {"position", McRFPy_Automation::_position, METH_NOARGS,
      MCRF_METHOD(automation, position,
          MCRF_SIG("()", "Vector"),
-         MCRF_DESC("Get the current mouse position as a Vector.")
+         MCRF_DESC("Get the current mouse position as a Vector."),
          MCRF_RETURNS("Vector: current mouse position in screen coordinates")
      )},
     {"size", McRFPy_Automation::_size, METH_NOARGS,
      MCRF_METHOD(automation, size,
          MCRF_SIG("()", "Vector"),
-         MCRF_DESC("Get the current screen (render target) size as a Vector.")
+         MCRF_DESC("Get the current screen (render target) size as a Vector."),
          MCRF_RETURNS("Vector: screen width and height in pixels")
      )},
     {"onScreen", (PyCFunction)McRFPy_Automation::_onScreen, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(automation, onScreen,
-         MCRF_SIG("(pos: tuple | list | Vector)", "bool"),
+         MCRF_SIG("(x: int, y: int) or (pos: tuple | list | Vector)", "bool"),
          MCRF_DESC("Check if a position is within the screen bounds."),
          MCRF_ARGS_START
+         MCRF_ARG("x", "X coordinate (int), when passing two separate int arguments")
+         MCRF_ARG("y", "Y coordinate (int), when passing two separate int arguments")
          MCRF_ARG("pos", "Position as (x, y) tuple, [x, y] list, or Vector")
          MCRF_RETURNS("True if the position is on screen, False otherwise")
      )},
@@ -951,6 +953,7 @@ static PyMethodDef automationMethods[] = {
          MCRF_ARGS_START
          MCRF_ARG("clicks", "Number of scroll steps (positive = up, negative = down)")
          MCRF_ARG("pos", "Position as (x, y) tuple, [x, y] list, Vector, or None for current position")
+         MCRF_NOTE("The x-coordinate of pos is currently unused; only the y-coordinate is applied to the scroll event position.")
      )},
     {"mouseDown", (PyCFunction)McRFPy_Automation::_mouseDown, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(automation, mouseDown,

src/PyBSP.cpp

@@ -342,7 +342,7 @@ PyMethodDef PyBSP::methods[] = {
      )},
     {"split_recursive", (PyCFunction)PyBSP::split_recursive, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(BSP, split_recursive,
-         MCRF_SIG("(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None)", "BSP"),
+         MCRF_SIG("(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None)", "BSP"),
          MCRF_DESC("Recursively split to the specified depth. "
                    "WARNING: Invalidates all existing BSPNode references from this tree."),
          MCRF_ARGS_START
@@ -376,15 +376,16 @@ PyMethodDef PyBSP::methods[] = {
      )},
     {"find", (PyCFunction)PyBSP::find, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(BSP, find,
-         MCRF_SIG("(pos: tuple[int, int])", "BSPNode | None"),
+         MCRF_SIG("(pos: tuple[int, int] | list | Vector)", "BSPNode | None"),
          MCRF_DESC("Find the smallest (deepest) node containing the position."),
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
          MCRF_RETURNS("BSPNode if found, None if position is outside bounds")
+         MCRF_NOTE("Also accepts two separate int arguments: find(x, y)")
      )},
     {"to_heightmap", (PyCFunction)PyBSP::to_heightmap, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(BSP, to_heightmap,
-         MCRF_SIG("(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0)", "HeightMap"),
+         MCRF_SIG("(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0)", "HeightMap"),
          MCRF_DESC("Convert BSP node selection to a HeightMap."),
          MCRF_ARGS_START
          MCRF_ARG("size", "Output size (width, height). Default: bounds size.")
@@ -1055,11 +1056,12 @@ PyGetSetDef PyBSPNode::getsetters[] = {
 PyMethodDef PyBSPNode::methods[] = {
     {"contains", (PyCFunction)PyBSPNode::contains, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(BSPNode, contains,
-         MCRF_SIG("(pos: tuple[int, int])", "bool"),
+         MCRF_SIG("(pos: tuple[int, int] | list | Vector)", "bool"),
          MCRF_DESC("Check if position is inside this node's bounds."),
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
          MCRF_RETURNS("bool: True if position is inside bounds")
+         MCRF_NOTE("Also accepts two separate int arguments: contains(x, y)")
      )},
     {"center", (PyCFunction)PyBSPNode::center, METH_NOARGS,
      MCRF_METHOD(BSPNode, center,

src/PyDrawable.cpp

@@ -104,7 +104,7 @@ static PyGetSetDef PyDrawable_getsetters[] = {
     {"on_click", (getter)PyDrawable_get_click, (setter)PyDrawable_set_click,
      MCRF_PROPERTY(on_click,
          "Callable executed when object is clicked. "
-         "Function receives (pos: Vector, button: str, action: str)."
+         "Function receives (pos: Vector, button: MouseButton, action: InputState)."
      ), NULL},
     {"z_index", (getter)PyDrawable_get_z_index, (setter)PyDrawable_set_z_index,
      MCRF_PROPERTY(z_index,

src/PyLock.cpp

@@ -21,8 +21,12 @@ static PyMethodDef PyLockContext_methods[] = {
      )},
     {"__exit__", (PyCFunction)PyLockContext_exit, METH_VARARGS,
      MCRF_METHOD(LockContext, __exit__,
-         MCRF_SIG("(exc_type, exc_val, exc_tb)", "bool"),
+         MCRF_SIG("(exc_type, exc_val, exc_tb)", "bool | None"),
          MCRF_DESC("Release the frame lock. Does not suppress exceptions."),
+         MCRF_ARGS_START
+         MCRF_ARG("exc_type", "Exception type, or None if no exception occurred")
+         MCRF_ARG("exc_val", "Exception value, or None if no exception occurred")
+         MCRF_ARG("exc_tb", "Exception traceback, or None if no exception occurred")
          MCRF_RETURNS("False, so any active exception propagates normally")
      )},
     {NULL}

src/PyUniformCollection.cpp

@@ -121,7 +121,7 @@ PyMethodDef PyUniformCollectionType::methods[] = {
      MCRF_METHOD(UniformCollection, values,
          MCRF_SIG("()", "list"),
          MCRF_DESC("Return a list of all uniform values in this collection.")
-         MCRF_RETURNS("list of float or tuple: the values of all uniforms currently set")
+         MCRF_RETURNS("list[float | tuple | None]: values of all uniforms; PropertyBinding/CallableBinding entries are None if not yet evaluable")
      )},
     {"items", (PyCFunction)PyUniformCollectionType::items, METH_NOARGS,
      MCRF_METHOD(UniformCollection, items,

src/UIArc.cpp

@@ -506,7 +506,7 @@ PyGetSetDef UIArc::getsetters[] = {
     {"thickness", (getter)UIArc::get_thickness, (setter)UIArc::set_thickness,
      MCRF_PROPERTY(thickness, "Line thickness in pixels (float)."), NULL},
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
-     MCRF_PROPERTY(on_click, "Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str)."), (void*)PyObjectsEnum::UIARC},
+     MCRF_PROPERTY(on_click, "Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState)."), (void*)PyObjectsEnum::UIARC},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index, "Z-order for rendering (int, lower values rendered first)."), (void*)PyObjectsEnum::UIARC},
     {"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name,

src/UIBase.h

@@ -259,21 +259,21 @@ static int UIDrawable_set_opacity(T* self, PyObject* value, void* closure)
      ), (void*)type_enum}, \
     {"bounds", (getter)UIDrawable::get_bounds_py, NULL, \
      MCRF_PROPERTY(bounds, \
-         "Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height))." \
+         "Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height))." \
      ), (void*)type_enum}, \
     {"global_bounds", (getter)UIDrawable::get_global_bounds_py, NULL, \
      MCRF_PROPERTY(global_bounds, \
-         "Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height))." \
+         "Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height))." \
      ), (void*)type_enum}, \
     {"on_enter", (getter)UIDrawable::get_on_enter, (setter)UIDrawable::set_on_enter, \
      MCRF_PROPERTY(on_enter, \
          "Callback for mouse enter events. " \
-         "Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds." \
+         "Called with (pos: Vector) when mouse enters this element's bounds." \
      ), (void*)type_enum}, \
     {"on_exit", (getter)UIDrawable::get_on_exit, (setter)UIDrawable::set_on_exit, \
      MCRF_PROPERTY(on_exit, \
          "Callback for mouse exit events. " \
-         "Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds." \
+         "Called with (pos: Vector) when mouse leaves this element's bounds." \
      ), (void*)type_enum}, \
     {"hovered", (getter)UIDrawable::get_hovered, NULL, \
      MCRF_PROPERTY(hovered, \
@@ -283,7 +283,7 @@ static int UIDrawable_set_opacity(T* self, PyObject* value, void* closure)
     {"on_move", (getter)UIDrawable::get_on_move, (setter)UIDrawable::set_on_move, \
      MCRF_PROPERTY(on_move, \
          "Callback for mouse movement within bounds. " \
-         "Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. " \
+         "Called with (pos: Vector) for each mouse movement while inside. " \
          "Performance note: Called frequently during movement - keep handlers fast." \
      ), (void*)type_enum}
 

src/UICaption.cpp

@@ -421,7 +421,7 @@ PyGetSetDef UICaption::getsetters[] = {
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
      MCRF_PROPERTY(on_click,
          "Callable executed when object is clicked. "
-         "Function receives (pos: Vector, button: str, action: str)."
+         "Function receives (pos: Vector, button: MouseButton, action: InputState)."
      ), (void*)PyObjectsEnum::UICAPTION},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index,

src/UICircle.cpp

@@ -450,7 +450,7 @@ PyGetSetDef UICircle::getsetters[] = {
     {"outline", (getter)UICircle::get_outline, (setter)UICircle::set_outline,
      MCRF_PROPERTY(outline, "Outline thickness in pixels (float). Use 0 for no outline."), NULL},
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
-     MCRF_PROPERTY(on_click, "Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str)."), (void*)PyObjectsEnum::UICIRCLE},
+     MCRF_PROPERTY(on_click, "Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState)."), (void*)PyObjectsEnum::UICIRCLE},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index, "Z-order for rendering (int). Lower values are rendered first."), (void*)PyObjectsEnum::UICIRCLE},
     {"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name,

src/UICollection.cpp

@@ -1056,7 +1056,7 @@ PyMethodDef UICollection::methods[] = {
 	 )},
 	{"extend", (PyCFunction)UICollection::extend, METH_O,
 	 MCRF_METHOD(UICollection, extend,
-	     MCRF_SIG("(iterable)", "None"),
+	     MCRF_SIG("(iterable: Iterable[Drawable])", "None"),
 	     MCRF_DESC("Add all elements from an iterable to the collection.")
 	     MCRF_ARGS_START
 	     MCRF_ARG("iterable", "Iterable of Drawable objects to add")

src/UIEntity.cpp

@@ -1394,13 +1394,14 @@ PyMethodDef UIEntity::methods[] = {
      )},
     {"visible_entities", (PyCFunction)UIEntity::visible_entities, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Entity, visible_entities,
-         MCRF_SIG("(fov=None, radius: int = None)", "list[Entity]"),
+         MCRF_SIG("(fov=None, radius: int = -1)", "list[Entity]"),
          MCRF_DESC("Get list of other entities visible from this entity's position."),
          MCRF_ARGS_START
          MCRF_ARG("fov", "FOV algorithm to use (FOV enum or None to use grid.fov)")
-         MCRF_ARG("radius", "FOV radius (int or None to use grid.fov_radius)")
+         MCRF_ARG("radius", "FOV radius as int; omit or pass -1 to use the grid's default fov_radius")
          MCRF_RETURNS("List of Entity objects within field of view, excluding self")
          MCRF_RAISES("ValueError", "If entity is not associated with a grid")
+         MCRF_NOTE("radius does not accept None; omit the argument entirely to use the grid default.")
      )},
     {NULL, NULL, 0, NULL}
 };
@@ -1735,7 +1736,7 @@ PyMethodDef UIEntity_all_methods[] = {
          MCRF_SIG("(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace')", "Animation"),
          MCRF_DESC("Create and start an animation on this entity's property."),
          MCRF_ARGS_START
-         MCRF_ARG("property", "Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index'")
+         MCRF_ARG("property", "Name of the property to animate: 'draw_x', 'draw_y' (tile coords), 'sprite_scale', 'sprite_index', 'sprite_offset_x', 'sprite_offset_y'")
          MCRF_ARG("target", "Target value - float, int, or list of int (for sprite frame sequences)")
          MCRF_ARG("duration", "Animation duration in seconds")
          MCRF_ARG("easing", "Easing function: Easing enum value, string name, or None for linear")
@@ -1744,9 +1745,10 @@ PyMethodDef UIEntity_all_methods[] = {
          MCRF_ARG("callback", "Optional callable invoked when animation completes (not called for looping animations)")
          MCRF_ARG("conflict_mode", "'replace' (default), 'queue', or 'error' if property already animating")
          MCRF_RETURNS("Animation object for monitoring progress")
-         MCRF_RAISES("ValueError", "If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index)")
+         MCRF_RAISES("ValueError", "If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index, sprite_offset_x, sprite_offset_y)")
          MCRF_NOTE("Use 'draw_x'/'draw_y' to animate tile coordinates for smooth movement between grid cells. "
-                   "Use list target with loop=True for repeating sprite frame animations.")
+                   "Use list target with loop=True for repeating sprite frame animations. "
+                   "'x' and 'y' are accepted as aliases for 'draw_x' and 'draw_y'.")
      )},
     {"at", (PyCFunction)UIEntity::at, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Entity, at,
@@ -1802,13 +1804,14 @@ PyMethodDef UIEntity_all_methods[] = {
      )},
     {"visible_entities", (PyCFunction)UIEntity::visible_entities, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Entity, visible_entities,
-         MCRF_SIG("(fov=None, radius: int = None)", "list[Entity]"),
+         MCRF_SIG("(fov=None, radius: int = -1)", "list[Entity]"),
          MCRF_DESC("Get list of other entities visible from this entity's position."),
          MCRF_ARGS_START
          MCRF_ARG("fov", "FOV algorithm to use (FOV enum or None to use grid.fov)")
-         MCRF_ARG("radius", "FOV radius (int or None to use grid.fov_radius)")
+         MCRF_ARG("radius", "FOV radius as int; omit or pass -1 to use the grid's default fov_radius")
          MCRF_RETURNS("List of Entity objects within field of view, excluding self")
          MCRF_RAISES("ValueError", "If entity is not associated with a grid")
+         MCRF_NOTE("radius does not accept None; omit the argument entirely to use the grid default.")
      )},
     // #296 - Label methods
     {"add_label", (PyCFunction)UIEntity::py_add_label, METH_O,

src/UIEntityCollection.cpp

@@ -974,6 +974,7 @@ PyMethodDef UIEntityCollection::methods[] = {
          MCRF_ARG("iterable", "Iterable of Entity objects to add")
          MCRF_RETURNS("None")
          MCRF_RAISES("TypeError", "If any item is not an Entity object")
+         MCRF_RAISES("RuntimeError", "If an Entity object in the iterable has invalid (null) internal state")
      )},
     {"insert", (PyCFunction)UIEntityCollection::insert, METH_VARARGS,
      MCRF_METHOD(EntityCollection, insert,
@@ -1021,7 +1022,7 @@ PyMethodDef UIEntityCollection::methods[] = {
      )},
     {"find", (PyCFunction)UIEntityCollection::find, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(EntityCollection, find,
-         MCRF_SIG("(name: str)", "Entity | list | None"),
+         MCRF_SIG("(name: str)", "Entity | list[Entity] | None"),
          MCRF_DESC("Find entities by name. Returns a single entity for exact matches or a list for wildcard patterns."),
          MCRF_ARGS_START
          MCRF_ARG("name", "Name to search for; supports wildcards: 'exact', 'prefix*', '*suffix', '*substring*'")

src/UIFrame.cpp

@@ -553,7 +553,7 @@ PyGetSetDef UIFrame::getsetters[] = {
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
      MCRF_PROPERTY(on_click,
          "Callable executed when object is clicked. "
-         "Function receives (pos: Vector, button: str, action: str)."
+         "Function receives (pos: Vector, button: MouseButton, action: InputState)."
      ), (void*)PyObjectsEnum::UIFRAME},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index,

src/UIGridPoint.cpp

@@ -143,7 +143,7 @@ PyGetSetDef UIGridPoint::getsetters[] = {
     {"entities", (getter)UIGridPoint::get_entities, NULL,
      MCRF_PROPERTY(entities, "List of Entity objects currently occupying this cell (list, read-only)."), NULL},
     {"grid_pos", (getter)UIGridPoint::get_grid_pos, NULL,
-     MCRF_PROPERTY(grid_pos, "Grid coordinates as (x, y) tuple (read-only)."), NULL},
+     MCRF_PROPERTY(grid_pos, "Grid coordinates as an (x, y) position (tuple, read-only)."), NULL},
     {NULL}  /* Sentinel */
 };
 

src/UIGridPyMethods.cpp

@@ -899,44 +899,51 @@ PyMethodDef UIGrid::methods[] = {
          MCRF_ARG("y", "Row index (0-based)")
          MCRF_RETURNS("GridPoint: the cell at the given position")
          MCRF_RAISES("IndexError", "If x or y is out of range")
+         MCRF_NOTE("Also accepts a single positional tuple/list/Vector: at((x, y)) or at(vec), or keyword form: at(pos=(x, y)).")
      )},
     {"compute_fov", (PyCFunction)UIGrid::py_compute_fov, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, compute_fov,
-         MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC)", "None"),
+         MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC)", "None"),
          MCRF_DESC("Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."),
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
          MCRF_ARG("radius", "Maximum view distance (0 = unlimited)")
          MCRF_ARG("light_walls", "Whether walls are lit when visible")
-         MCRF_ARG("algorithm", "FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)")
+         MCRF_ARG("algorithm", "FOV algorithm to use (FOV.BASIC, FOV.DIAMOND, FOV.SHADOW, FOV.PERMISSIVE_0-8)")
+         MCRF_RETURNS("None")
      )},
     {"is_in_fov", (PyCFunction)UIGrid::py_is_in_fov, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, is_in_fov,
-         MCRF_SIG("(pos)", "bool"),
+         MCRF_SIG("(x: int, y: int)", "bool"),
          MCRF_DESC("Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."),
          MCRF_ARGS_START
-         MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
+         MCRF_ARG("x", "Column index (0-based)")
+         MCRF_ARG("y", "Row index (0-based)")
          MCRF_RETURNS("True if the cell is visible, False otherwise")
+         MCRF_NOTE("Also accepts a single positional tuple/list/Vector: is_in_fov((x, y)) or is_in_fov(vec), or keyword form: is_in_fov(pos=(x, y)).")
      )},
     {"find_path", (PyCFunction)UIGridPathfinding::Grid_find_path, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, find_path,
-         MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None)", "AStarPath | None"),
+         MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0)", "AStarPath | None"),
          MCRF_DESC("Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."),
          MCRF_ARGS_START
          MCRF_ARG("start", "Starting position as Vector, Entity, or (x, y) tuple")
          MCRF_ARG("end", "Target position as Vector, Entity, or (x, y) tuple")
          MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)")
          MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.")
+         MCRF_ARG("heuristic", "Heuristic enum member, string name, or int (EUCLIDEAN=0, MANHATTAN=1, CHEBYSHEV=2). None uses default (Euclidean).")
+         MCRF_ARG("weight", "Heuristic weight multiplier. Values > 1.0 trade optimality for speed (weighted A*).")
          MCRF_RETURNS("AStarPath object if path exists, None otherwise")
      )},
     {"get_dijkstra_map", (PyCFunction)UIGridPathfinding::Grid_get_dijkstra_map, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, get_dijkstra_map,
-         MCRF_SIG("(root, diagonal_cost: float = 1.41, collide: str = None)", "DijkstraMap"),
+         MCRF_SIG("(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None)", "DijkstraMap"),
          MCRF_DESC("Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."),
          MCRF_ARGS_START
-         MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple")
+         MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple. Use 'root' for single-source maps (cached by position).")
          MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)")
          MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.")
+         MCRF_ARG("roots", "Sequence of root positions or a DiscreteMap mask for multi-source Dijkstra. Pass 'roots' instead of 'root' for multi-source maps (not cached).")
          MCRF_RETURNS("DijkstraMap object for querying distances and paths")
      )},
     {"clear_dijkstra_maps", (PyCFunction)UIGridPathfinding::Grid_clear_dijkstra_maps, METH_NOARGS,
@@ -1024,44 +1031,51 @@ PyMethodDef UIGrid_all_methods[] = {
          MCRF_ARG("y", "Row index (0-based)")
          MCRF_RETURNS("GridPoint: the cell at the given position")
          MCRF_RAISES("IndexError", "If x or y is out of range")
+         MCRF_NOTE("Also accepts a single positional tuple/list/Vector: at((x, y)) or at(vec), or keyword form: at(pos=(x, y)).")
      )},
     {"compute_fov", (PyCFunction)UIGrid::py_compute_fov, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, compute_fov,
-         MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC)", "None"),
+         MCRF_SIG("(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC)", "None"),
          MCRF_DESC("Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."),
          MCRF_ARGS_START
          MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
          MCRF_ARG("radius", "Maximum view distance (0 = unlimited)")
          MCRF_ARG("light_walls", "Whether walls are lit when visible")
-         MCRF_ARG("algorithm", "FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)")
+         MCRF_ARG("algorithm", "FOV algorithm to use (FOV.BASIC, FOV.DIAMOND, FOV.SHADOW, FOV.PERMISSIVE_0-8)")
+         MCRF_RETURNS("None")
      )},
     {"is_in_fov", (PyCFunction)UIGrid::py_is_in_fov, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, is_in_fov,
-         MCRF_SIG("(pos)", "bool"),
+         MCRF_SIG("(x: int, y: int)", "bool"),
          MCRF_DESC("Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."),
          MCRF_ARGS_START
-         MCRF_ARG("pos", "Position as (x, y) tuple, list, or Vector")
+         MCRF_ARG("x", "Column index (0-based)")
+         MCRF_ARG("y", "Row index (0-based)")
          MCRF_RETURNS("True if the cell is visible, False otherwise")
+         MCRF_NOTE("Also accepts a single positional tuple/list/Vector: is_in_fov((x, y)) or is_in_fov(vec), or keyword form: is_in_fov(pos=(x, y)).")
      )},
     {"find_path", (PyCFunction)UIGridPathfinding::Grid_find_path, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, find_path,
-         MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None)", "AStarPath | None"),
+         MCRF_SIG("(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0)", "AStarPath | None"),
          MCRF_DESC("Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."),
          MCRF_ARGS_START
          MCRF_ARG("start", "Starting position as Vector, Entity, or (x, y) tuple")
          MCRF_ARG("end", "Target position as Vector, Entity, or (x, y) tuple")
          MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)")
          MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.")
+         MCRF_ARG("heuristic", "Heuristic enum member, string name, or int (EUCLIDEAN=0, MANHATTAN=1, CHEBYSHEV=2). None uses default (Euclidean).")
+         MCRF_ARG("weight", "Heuristic weight multiplier. Values > 1.0 trade optimality for speed (weighted A*).")
          MCRF_RETURNS("AStarPath object if path exists, None otherwise")
      )},
     {"get_dijkstra_map", (PyCFunction)UIGridPathfinding::Grid_get_dijkstra_map, METH_VARARGS | METH_KEYWORDS,
      MCRF_METHOD(Grid, get_dijkstra_map,
-         MCRF_SIG("(root, diagonal_cost: float = 1.41, collide: str = None)", "DijkstraMap"),
+         MCRF_SIG("(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None)", "DijkstraMap"),
          MCRF_DESC("Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."),
          MCRF_ARGS_START
-         MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple")
+         MCRF_ARG("root", "Root position as Vector, Entity, or (x, y) tuple. Use 'root' for single-source maps (cached by position).")
          MCRF_ARG("diagonal_cost", "Cost of diagonal movement (default: 1.41)")
          MCRF_ARG("collide", "Label string. Entities with this label block pathfinding.")
+         MCRF_ARG("roots", "Sequence of root positions or a DiscreteMap mask for multi-source Dijkstra. Pass 'roots' instead of 'root' for multi-source maps (not cached).")
          MCRF_RETURNS("DijkstraMap object for querying distances and paths")
      )},
     {"clear_dijkstra_maps", (PyCFunction)UIGridPathfinding::Grid_clear_dijkstra_maps, METH_NOARGS,

src/UIGridPyProperties.cpp

@@ -571,7 +571,7 @@ PyGetSetDef UIGrid::getsetters[] = {
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
      MCRF_PROPERTY(on_click,
          "Callable executed when object is clicked. "
-         "Function receives (pos: Vector, button: str, action: str)."
+         "Function receives (pos: Vector, button: MouseButton, action: InputState)."
      ), (void*)PyObjectsEnum::UIGRID},
 
     {"texture", (getter)UIGrid::get_texture, NULL,

src/UIGridView.cpp

@@ -888,13 +888,13 @@ PyGetSetDef UIGridView::getsetters[] = {
     {"grid_data", (getter)UIGridView::get_grid, (setter)UIGridView::set_grid,
      MCRF_PROPERTY(grid_data, "The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid."), NULL},
     {"center", (getter)UIGridView::get_center, (setter)UIGridView::set_center,
-     MCRF_PROPERTY(center, "Camera center point in pixel coordinates (tuple)."), NULL},
+     MCRF_PROPERTY(center, "Camera center point in pixel coordinates (Vector)."), NULL},
     {"zoom", (getter)UIGridView::get_zoom, (setter)UIGridView::set_zoom,
      MCRF_PROPERTY(zoom, "Zoom level for rendering (float). Values greater than 1.0 magnify; less than 1.0 shrink."), NULL},
     {"fill_color", (getter)UIGridView::get_fill_color, (setter)UIGridView::set_fill_color,
      MCRF_PROPERTY(fill_color, "Background fill color (Color). Drawn behind all tiles and entities."), NULL},
     {"texture", (getter)UIGridView::get_texture, NULL,
-     MCRF_PROPERTY(texture, "Texture used for tile rendering (Texture | None, read-only)."), NULL},
+     MCRF_PROPERTY(texture, "Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None."), NULL},
     // UIDrawable base properties - applied to GridView (the rendered object)
     {"pos", (getter)UIDrawable::get_pos, (setter)UIDrawable::set_pos,
      MCRF_PROPERTY(pos, "Position of the grid as Vector (Vector)."), (void*)PyObjectsEnum::UIGRIDVIEW},

src/UILine.cpp

@@ -517,7 +517,7 @@ PyGetSetDef UILine::getsetters[] = {
     {"thickness", (getter)UILine::get_thickness, (setter)UILine::set_thickness,
      MCRF_PROPERTY(thickness, "Line thickness in pixels."), NULL},
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
-     MCRF_PROPERTY(on_click, "Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str)."),
+     MCRF_PROPERTY(on_click, "Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState)."),
      (void*)PyObjectsEnum::UILINE},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index, "Z-order for rendering (lower values rendered first)."),

src/UISprite.cpp

@@ -441,7 +441,7 @@ PyGetSetDef UISprite::getsetters[] = {
     {"on_click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
      MCRF_PROPERTY(on_click,
          "Callable executed when object is clicked. "
-         "Function receives (pos: Vector, button: str, action: str)."
+         "Function receives (pos: Vector, button: MouseButton, action: InputState)."
      ), (void*)PyObjectsEnum::UISPRITE},
     {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
      MCRF_PROPERTY(z_index,

stubs/mcrfpy.pyi

@@ -267,11 +267,11 @@ class Arc:
     """An arc UI element for drawing curved line segments."""
     def __init__(self, center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     center: Vector  # Center position of the arc (Vector).
     color: Color  # Arc fill color (Color).
     end_angle: float  # Ending angle in degrees (float).
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector, only when parent is Grid).
     grid_size: Vector  # Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -279,10 +279,10 @@ class Arc:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: str  # Name for finding this element (str).
-    on_click: Any  # Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -338,7 +338,7 @@ class BSP:
     def clear(self) -> BSP:
         """Remove all children, keeping only the root node with original bounds. WARNING: Invalidates all existing BSPNode references from this tree."""
         ...
-    def find(self, pos: tuple[int, int]) -> BSPNode | None:
+    def find(self, pos: tuple[int, int] | list | Vector) -> BSPNode | None:
         """Find the smallest (deepest) node containing the position."""
         ...
     def get_leaf(self, index: int) -> BSPNode:
@@ -350,10 +350,10 @@ class BSP:
     def split_once(self, horizontal: bool, position: int) -> BSP:
         """Split the root node once at the specified position. horizontal=True creates a horizontal divider, producing top/bottom rooms. horizontal=False creates a vert..."""
         ...
-    def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP:
+    def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP:
         """Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree."""
         ...
-    def to_heightmap(self, size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap:
+    def to_heightmap(self, size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap:
         """Convert BSP node selection to a HeightMap."""
         ...
     def traverse(self, order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]:
@@ -384,10 +384,10 @@ class Caption:
     """A text display UI element with customizable font and styling."""
     def __init__(self, pos=None, font=None, text='', **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     fill_color: Color  # Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
     font_size: int  # Font size in points (int). Clamped to the range [0, 65535].
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector). Only valid when parent is a Grid.
     grid_size: Vector  # Size in grid tile coordinates (Vector). Only valid when parent is a Grid.
@@ -396,10 +396,10 @@ class Caption:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: str  # Name for finding elements (str).
-    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     outline: float  # Thickness of the text outline border (float). Clamped to non-negative values.
@@ -435,10 +435,10 @@ class Circle:
     """A circle UI element for drawing filled or outlined circles."""
     def __init__(self, radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     center: Vector  # Center position of the circle (Vector).
     fill_color: Color  # Fill color of the circle (Color).
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
     grid_size: Vector  # Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
@@ -446,10 +446,10 @@ class Circle:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: str  # Name for finding this element (str).
-    on_click: Callable | None  # Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Callable | None  # Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     outline: float  # Outline thickness in pixels (float). Use 0 for no outline.
@@ -503,7 +503,7 @@ class ColorLayer:
     def apply_gradient(self, source: HeightMap, range: tuple, color_low: Color, color_high: Color) -> ColorLayer:
         """Interpolate between two colors based on HeightMap value within a range. Uses the original heightmap value for smooth transitions."""
         ...
-    def apply_perspective(self, entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None:
+    def apply_perspective(self, entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None:
         """Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves."""
         ...
     def apply_ranges(self, source: HeightMap, ranges: list) -> ColorLayer:
@@ -513,12 +513,12 @@ class ColorLayer:
         """Set a fixed color for cells where the HeightMap value falls within a range."""
         ...
     def at(self, *args, **kwargs) -> Any:
-        """at(pos) or (x: int, y: int) -> Color"""
+        """at(pos: tuple | Vector) or (x: int, y: int) -> Color"""
         ...
     def clear_perspective(self) -> None:
         """Remove the perspective binding from this layer."""
         ...
-    def draw_fov(self, source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None:
+    def draw_fov(self, source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None:
         """Paint cells based on field-of-view visibility from a source position."""
         ...
     def fill(self, color: Color) -> None:
@@ -638,7 +638,7 @@ class DiscreteMap:
 class Drawable:
     """Base class for all drawable UI elements"""
     def __init__(self, *args, **kwargs) -> None: ...
-    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
+    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     visible: bool  # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
     z_index: Any  # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
@@ -725,7 +725,7 @@ class Entity:
     def update_visibility(self) -> None:
         """Recompute which cells are visible from this entity's position and update perspective_map."""
         ...
-    def visible_entities(self, fov=None, radius: int = None) -> list[Entity]:
+    def visible_entities(self, fov=None, radius: int = -1) -> list[Entity]:
         """Get list of other entities visible from this entity's position."""
         ...
 
@@ -811,12 +811,12 @@ class Frame:
     """A rectangular frame UI element that can contain other drawable elements."""
     def __init__(self, pos=None, size=None, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     cache_subtree: bool  # Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees.
     children: UICollection  # UICollection of child drawable objects rendered on top of this frame (UICollection, read-only).
     clip_children: bool  # Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True.
     fill_color: Color  # Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
     grid_size: Vector  # Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
@@ -825,10 +825,10 @@ class Frame:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: str  # Name for finding elements (str).
-    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     outline: float  # Thickness of the border in pixels (float).
@@ -862,9 +862,9 @@ class Grid:
     """A grid-based UI element for tile-based rendering and entity management."""
     def __init__(self, grid_size=None, pos=None, size=None, texture=None, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     camera_rotation: float  # Rotation of grid contents around camera center in degrees (float).
-    center: tuple  # Camera center point in pixel coordinates (tuple).
+    center: Vector  # Camera center point in pixel coordinates (Vector).
     center_x: float  # Camera center X-coordinate in pixel space (float).
     center_y: float  # Camera center Y-coordinate in pixel space (float).
     children: UICollection  # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only).
@@ -872,7 +872,7 @@ class Grid:
     fill_color: Color  # Background fill color (Color). Drawn behind all tiles and entities.
     fov: Any  # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
     fov_radius: int  # Default FOV radius for this grid (int). Used when radius is not specified.
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_data: Grid | None  # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
     grid_h: int  # Grid height in cells (int, read-only).
@@ -890,9 +890,9 @@ class Grid:
     on_cell_enter: Callable | None  # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector).
     on_cell_exit: Callable | None  # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector).
     on_click: Callable | None  # Callable executed when object is clicked (Callable | None).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -903,7 +903,7 @@ class Grid:
     rotation: Any  # Rotation angle in degrees (clockwise around origin). Animatable property.
     shader: Any  # 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.
     size: Vector  # Size of the grid widget as Vector (Vector, width x height in pixels).
-    texture: Texture | None  # Texture used for tile rendering (Texture | None, read-only).
+    texture: None  # Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
     uniforms: Any  # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
     vert_margin: float  # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
     view: GridView | None  # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders.
@@ -934,19 +934,19 @@ class Grid:
     def clear_dijkstra_maps(self) -> None:
         """Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data."""
         ...
-    def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None:
+    def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None:
         """Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."""
         ...
     def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list:
         """Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
         ...
-    def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None:
+    def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None:
         """Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."""
         ...
-    def get_dijkstra_map(self, root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap:
+    def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap:
         """Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."""
         ...
-    def is_in_fov(self, pos) -> bool:
+    def is_in_fov(self, x: int, y: int) -> bool:
         """Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."""
         ...
     def layer(self, name: str) -> ColorLayer | TileLayer | None:
@@ -972,9 +972,9 @@ class GridView:
     """A grid-based UI element for tile-based rendering and entity management."""
     def __init__(self, *args, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     camera_rotation: float  # Rotation of grid contents around camera center in degrees (float).
-    center: tuple  # Camera center point in pixel coordinates (tuple).
+    center: Vector  # Camera center point in pixel coordinates (Vector).
     center_x: float  # Camera center X-coordinate in pixel space (float).
     center_y: float  # Camera center Y-coordinate in pixel space (float).
     children: UICollection  # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only).
@@ -982,7 +982,7 @@ class GridView:
     fill_color: Color  # Background fill color (Color). Drawn behind all tiles and entities.
     fov: Any  # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
     fov_radius: int  # Default FOV radius for this grid (int). Used when radius is not specified.
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_data: Grid | None  # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
     grid_h: int  # Grid height in cells (int, read-only).
@@ -1000,9 +1000,9 @@ class GridView:
     on_cell_enter: Callable | None  # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector).
     on_cell_exit: Callable | None  # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector).
     on_click: Callable | None  # Callable executed when object is clicked (Callable | None).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -1013,7 +1013,7 @@ class GridView:
     rotation: Any  # Rotation angle in degrees (clockwise around origin). Animatable property.
     shader: Any  # 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.
     size: Vector  # Size of the grid widget as Vector (Vector, width x height in pixels).
-    texture: Texture | None  # Texture used for tile rendering (Texture | None, read-only).
+    texture: None  # Texture used for tile rendering (None, read-only). Texture return is not yet implemented; always returns None.
     uniforms: Any  # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
     vert_margin: float  # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
     view: GridView | None  # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders.
@@ -1044,19 +1044,19 @@ class GridView:
     def clear_dijkstra_maps(self) -> None:
         """Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data."""
         ...
-    def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None:
+    def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None:
         """Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."""
         ...
     def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list:
         """Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
         ...
-    def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None:
+    def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None:
         """Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."""
         ...
-    def get_dijkstra_map(self, root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap:
+    def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap:
         """Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."""
         ...
-    def is_in_fov(self, pos) -> bool:
+    def is_in_fov(self, x: int, y: int) -> bool:
         """Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."""
         ...
     def layer(self, name: str) -> ColorLayer | TileLayer | None:
@@ -1218,10 +1218,10 @@ class Line:
     """A line UI element for drawing straight lines between two points."""
     def __init__(self, start=None, end=None, thickness=1.0, color=None, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     color: Any  # Line color as a Color object.
     end: Any  # Ending point of the line as a Vector.
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector, only when parent is Grid).
     grid_size: Vector  # Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -1229,10 +1229,10 @@ class Line:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: Any  # Name for finding this element.
-    on_click: Any  # Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -1459,8 +1459,8 @@ class Sprite:
     """A sprite UI element that displays a texture or portion of a texture atlas."""
     def __init__(self, pos=None, texture=None, sprite_index=0, **kwargs) -> None: ...
     align: Any  # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_pos: Vector  # Position in grid tile coordinates (Vector, only when parent is Grid).
     grid_size: Vector  # Size in grid tile coordinates (Vector, only when parent is Grid).
@@ -1468,10 +1468,10 @@ class Sprite:
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
     margin: float  # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
     name: str  # Name for finding elements (str).
-    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     origin: Any  # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@@ -1542,7 +1542,7 @@ class TileLayer:
         """Set a tile index for cells where the HeightMap value falls within a range."""
         ...
     def at(self, *args, **kwargs) -> Any:
-        """at(pos) or (x: int, y: int) -> int"""
+        """at(pos: tuple | Vector) or (x: int, y: int) -> int"""
         ...
     def fill(self, index: int) -> None:
         """Fill the entire layer with the specified tile index."""
@@ -1667,7 +1667,7 @@ class Viewport3D:
     """A 3D rendering viewport that displays a 3D scene as a UI element."""
     def __init__(self, pos=None, size=None, **kwargs) -> None: ...
     bg_color: Any  # Background clear color.
-    bounds: Any  # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
+    bounds: tuple  # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     camera_pos: Any  # Camera position as (x, y, z) tuple.
     camera_target: Any  # Camera look-at target as (x, y, z) tuple.
     cell_size: Any  # World units per navigation grid cell.
@@ -1680,15 +1680,15 @@ class Viewport3D:
     fog_far: Any  # Fog end distance.
     fog_near: Any  # Fog start distance.
     fov: Any  # Camera field of view in degrees.
-    global_bounds: Any  # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
+    global_bounds: tuple  # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
     global_position: Any  # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
     grid_size: Any  # Navigation grid dimensions as (width, depth) tuple.
     h: Any  # Display height in pixels.
     hovered: Any  # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
-    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
-    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
-    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
-    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
+    on_click: Any  # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
+    on_enter: Any  # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
+    on_exit: Any  # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
+    on_move: Any  # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
     opacity: Any  # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
     parent: Any  # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
     pos: Any  # Position as Vector (x, y).
@@ -1980,8 +1980,8 @@ class _automation_module:
         """Move the mouse cursor to the specified position."""
         ...
     @staticmethod
-    def onScreen(pos: tuple | list | Vector) -> bool:
-        """Check if a position is within the screen bounds."""
+    def onScreen(self, *args, **kwargs) -> Any:
+        """onScreen(x: int, y: int) or (pos: tuple | list | Vector) -> bool"""
         ...
     @staticmethod
     def position() -> Vector:
@@ -2014,7 +2014,7 @@ class _automation_module:
 automation: _automation_module
 
 # --- Module-level functions ---------------------------------------------
-def bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]:
+def bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]:
     """Compute grid cells along a line using Bresenham's algorithm."""
     ...
 def end_benchmark() -> str:

tests/snapshots/api_surface.golden.txt

@@ -3,7 +3,7 @@
 # Singleton/constant VALUES are intentionally NOT captured.
 
 === MODULE FUNCTIONS (12) ===
-func bresenham :: bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]
+func bresenham :: bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]
 func end_benchmark :: end_benchmark() -> str
 func exit :: exit() -> None
 func find :: find(name: str, scene: str = None) -> UIDrawable | None
@@ -253,11 +253,11 @@ submodule automation
   meth walk :: walk() -> Vector
 [Arc]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop center: Vector (rw)
   prop color: Color (rw)
   prop end_angle: float (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -292,19 +292,19 @@ submodule automation
   prop root: Any (ro)
   prop size: Any (ro)
   meth clear :: clear() -> BSP
-  meth find :: find(pos: tuple[int, int]) -> BSPNode | None
+  meth find :: find(pos: tuple[int, int] | list | Vector) -> BSPNode | None
   meth get_leaf :: get_leaf(index: int) -> BSPNode
   meth leaves :: leaves() -> Iterator[BSPNode]
   meth split_once :: split_once(horizontal: bool, position: int) -> BSP
-  meth split_recursive :: split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP
-  meth to_heightmap :: to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap
+  meth split_recursive :: split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP
+  meth to_heightmap :: to_heightmap(size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap
   meth traverse :: traverse(order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]
 [Caption]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop fill_color: Color (rw)
   prop font_size: int (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -341,10 +341,10 @@ submodule automation
   meth resize :: resize(width, height) or (size) -> None
 [Circle]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop center: Vector (rw)
   prop fill_color: Color (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -387,12 +387,12 @@ submodule automation
   prop visible: bool (rw)
   prop z_index: int (rw)
   meth apply_gradient :: apply_gradient(source: HeightMap, range: tuple, color_low: Color, color_high: Color) -> ColorLayer
-  meth apply_perspective :: apply_perspective(entity: Entity, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None
+  meth apply_perspective :: apply_perspective(entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None
   meth apply_ranges :: apply_ranges(source: HeightMap, ranges: list) -> ColorLayer
   meth apply_threshold :: apply_threshold(source: HeightMap, range: tuple, color: Color) -> ColorLayer
-  meth at :: at(pos) or (x: int, y: int) -> Color
+  meth at :: at(pos: tuple | Vector) or (x: int, y: int) -> Color
   meth clear_perspective :: clear_perspective() -> None
-  meth draw_fov :: draw_fov(source: tuple, radius: int = None, fov: FOV = None, visible: Color = None, discovered: Color = None, unknown: Color = None) -> None
+  meth draw_fov :: draw_fov(source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None
   meth fill :: fill(color: Color) -> None
   meth fill_rect :: fill_rect(pos: tuple, size: tuple, color: Color) -> None
   meth set :: set(pos, color: Color) -> None
@@ -487,18 +487,18 @@ submodule automation
   meth resize :: resize(width, height) or (size) -> None
   meth set_behavior :: set_behavior(type, waypoints=None, turns: int = 0, path=None, pathfinder=None) -> None
   meth update_visibility :: update_visibility() -> None
-  meth visible_entities :: visible_entities(fov=None, radius: int = None) -> list[Entity]
+  meth visible_entities :: visible_entities(fov=None, radius: int = -1) -> list[Entity]
 [Font]
   prop family: str (ro)
   prop source: str (ro)
 [Frame]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop cache_subtree: bool (rw)
   prop children: UICollection (ro)
   prop clip_children: bool (rw)
   prop fill_color: Color (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -533,13 +533,13 @@ submodule automation
   meth resize :: resize(width, height) or (size) -> None
 [Grid]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop camera_rotation: float (rw)
-  prop center: tuple (rw)
+  prop center: Vector (rw)
   prop center_x: float (rw)
   prop center_y: float (rw)
   prop fill_color: Color (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_data: Grid | None (rw)
   prop h: float (rw)
@@ -558,7 +558,7 @@ submodule automation
   prop rotate_with_camera: bool (rw)
   prop rotation: Any (rw)
   prop shader: Any (rw)
-  prop texture: Texture | None (ro)
+  prop texture: None (ro)
   prop uniforms: Any (ro)
   prop vert_margin: float (rw)
   prop visible: bool (rw)
@@ -573,13 +573,13 @@ submodule automation
   meth resize :: resize(width, height) or (size) -> None
 [GridView]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop camera_rotation: float (rw)
-  prop center: tuple (rw)
+  prop center: Vector (rw)
   prop center_x: float (rw)
   prop center_y: float (rw)
   prop fill_color: Color (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_data: Grid | None (rw)
   prop h: float (rw)
@@ -598,7 +598,7 @@ submodule automation
   prop rotate_with_camera: bool (rw)
   prop rotation: Any (rw)
   prop shader: Any (rw)
-  prop texture: Texture | None (ro)
+  prop texture: None (ro)
   prop uniforms: Any (ro)
   prop vert_margin: float (rw)
   prop visible: bool (rw)
@@ -655,10 +655,10 @@ submodule automation
   prop system: Any (ro)
 [Line]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop color: Any (rw)
   prop end: Any (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -764,8 +764,8 @@ submodule automation
   meth tone :: tone(frequency: float, duration: float, waveform: str = 'sine', ...) -> SoundBuffer
 [Sprite]
   prop align: Any (rw)
-  prop bounds: Any (rw)
-  prop global_bounds: Any (rw)
+  prop bounds: tuple (ro)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_pos: Vector (rw)
   prop grid_size: Vector (rw)
@@ -822,7 +822,7 @@ submodule automation
   prop z_index: int (rw)
   meth apply_ranges :: apply_ranges(source: HeightMap, ranges: list) -> TileLayer
   meth apply_threshold :: apply_threshold(source: HeightMap, range: tuple, tile: int) -> TileLayer
-  meth at :: at(pos) or (x: int, y: int) -> int
+  meth at :: at(pos: tuple | Vector) or (x: int, y: int) -> int
   meth fill :: fill(index: int) -> None
   meth fill_rect :: fill_rect(pos: tuple, size: tuple, index: int) -> None
   meth set :: set(pos, index: int) -> None
@@ -989,7 +989,7 @@ submodule automation
   meth wang_set :: wang_set(name: str) -> WangSet
 [Viewport3D]
   prop bg_color: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop camera_pos: Any (rw)
   prop camera_target: Any (rw)
   prop cell_size: Any (rw)
@@ -1002,7 +1002,7 @@ submodule automation
   prop fog_far: Any (rw)
   prop fog_near: Any (rw)
   prop fov: Any (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_size: Any (rw)
   prop h: Any (rw)
@@ -1105,7 +1105,7 @@ submodule automation
 === INTERNAL TYPES (reached via live instances) ===
 [_GridData]
   prop align: Any (rw)
-  prop bounds: Any (rw)
+  prop bounds: tuple (ro)
   prop camera_rotation: float (rw)
   prop center: Vector (rw)
   prop center_x: float (rw)
@@ -1115,7 +1115,7 @@ submodule automation
   prop fill_color: Color (rw)
   prop fov: Any (rw)
   prop fov_radius: int (rw)
-  prop global_bounds: Any (rw)
+  prop global_bounds: tuple (ro)
   prop global_position: Any (ro)
   prop grid_h: int (ro)
   prop grid_pos: Vector (rw)
@@ -1162,11 +1162,11 @@ submodule automation
   meth at :: at(x: int, y: int) -> GridPoint
   meth center_camera :: center_camera(pos: tuple = None) -> None
   meth clear_dijkstra_maps :: clear_dijkstra_maps() -> None
-  meth compute_fov :: compute_fov(pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None
+  meth compute_fov :: compute_fov(pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None
   meth entities_in_radius :: entities_in_radius(pos: tuple | Vector, radius: float) -> list
-  meth find_path :: find_path(start, end, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None
-  meth get_dijkstra_map :: get_dijkstra_map(root, diagonal_cost: float = 1.41, collide: str = None) -> DijkstraMap
-  meth is_in_fov :: is_in_fov(pos) -> bool
+  meth find_path :: find_path(start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None
+  meth get_dijkstra_map :: get_dijkstra_map(root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap
+  meth is_in_fov :: is_in_fov(x: int, y: int) -> bool
   meth layer :: layer(name: str) -> ColorLayer | TileLayer | None
   meth move :: move(dx, dy) or (delta) -> None
   meth realign :: realign() -> None
@@ -1175,14 +1175,14 @@ submodule automation
   meth step :: step(n: int = 1, turn_order: int = None) -> None
 [GridPoint]
   prop entities: list (ro)
-  prop grid_pos: Any (ro)
+  prop grid_pos: tuple (ro)
   prop transparent: bool (rw)
   prop walkable: bool (rw)
 [EntityCollection]
   meth append :: append(entity: Entity) -> None
   meth count :: count(entity: Entity) -> int
   meth extend :: extend(iterable) -> None
-  meth find :: find(name: str) -> Entity | list | None
+  meth find :: find(name: str) -> Entity | list[Entity] | None
   meth index :: index(entity: Entity) -> int
   meth insert :: insert(index: int, entity: Entity) -> None
   meth pop :: pop(index: int = -1) -> Entity
@@ -1190,7 +1190,7 @@ submodule automation
 [UICollection]
   meth append :: append(element: Drawable) -> None
   meth count :: count(element: Drawable) -> int
-  meth extend :: extend(iterable) -> None
+  meth extend :: extend(iterable: Iterable[Drawable]) -> None
   meth find :: find(name: str, recursive: bool = False) -> Drawable | list | None
   meth index :: index(element: Drawable) -> int
   meth insert :: insert(index: int, element: Drawable) -> None
@@ -1215,7 +1215,7 @@ func mouseDown :: mouseDown(pos: tuple | list | Vector | None = None, button: st
 func mouseUp :: mouseUp(pos: tuple | list | Vector | None = None, button: str = 'left') -> None
 func moveRel :: moveRel(offset: tuple | list | Vector, duration: float = 0.0) -> None
 func moveTo :: moveTo(pos: tuple | list | Vector, duration: float = 0.0) -> None
-func onScreen :: onScreen(pos: tuple | list | Vector) -> bool
+func onScreen :: onScreen(x: int, y: int) or (pos: tuple | list | Vector) -> bool
 func position :: position() -> Vector
 func rightClick :: rightClick(pos: tuple | list | Vector | None = None) -> None
 func screenshot :: screenshot(filename: str) -> bool