Update documentation for API changes #229, #230, #184

CLAUDE.md updates:
- Fix Python version 3.12 -> 3.14
- Update keypressScene -> scene.on_key pattern
- Add API examples for new callback signatures
- Document animation callbacks (target, prop, value)
- Document hover callbacks (position-only)
- Document enum types (Key, MouseButton, InputState)

stubs/mcrfpy.pyi updates:
- Add Key, MouseButton, InputState, Easing enum classes
- Fix Drawable hover callback signatures per #230
- Fix Grid cell callback signatures per #230
- Fix Scene.on_key signature to use enums per #184
- Update Animation class with correct callback signature per #229
- Add deprecation notes to keypressScene, setTimer, delTimer

Regenerated docs:
- API_REFERENCE_DYNAMIC.md
- api_reference_dynamic.html
- mcrfpy.3 man page

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

CLAUDE.md

@@ -309,12 +309,12 @@ McRogueFace is a C++ game engine with Python scripting support, designed for cre
 
 ### Key Python API (`mcrfpy` module)
 The C++ engine exposes these primary functions to Python:
-- Scene Management: `Scene("name")` object
+- Scene Management: `Scene("name")` object with `scene.on_key` for keyboard events
 - Entity Creation: `Entity()` with position and sprite properties
-- Grid Management: `Grid()` for tilemap rendering
+- Grid Management: `Grid()` for tilemap rendering with cell callbacks
-- Input Handling: `keypressScene()` for keyboard events
+- Input Handling: `scene.on_key = handler` receives `(Key, InputState)` enums
 - Audio: `createSoundBuffer()`, `playSound()`, `setVolume()`
-- Timers: `Timer("name")` object for event scheduling
+- Timers: `Timer("name", callback, interval)` object for event scheduling
 
 ## Development Workflow
 
@@ -322,7 +322,7 @@ The C++ engine exposes these primary functions to Python:
 After building, the executable expects:
 - `assets/` directory with sprites, fonts, and audio
 - `scripts/` directory with Python game files
-- Python 3.12 shared libraries in `./lib/`
+- Python 3.14 shared libraries in `./lib/`
 
 ### Modifying Game Logic
 - Game scripts are in `src/scripts/`
@@ -591,6 +591,11 @@ demo_scene = mcrfpy.Scene("demo")
 # preferred: create animations directly against the targeted object; use Enum of easing functions
 frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT)
 
+# Animation callbacks (#229) receive (target, property, final_value):
+def on_anim_complete(target, prop, value):
+    print(f"{type(target).__name__}.{prop} reached {value}")
+frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT, callback=on_anim_complete)
+
 # Caption: use keyword arguments to avoid positional conflicts
 cap = mcrfpy.Caption(text="Hello", pos=(100, 100))
 
@@ -601,10 +606,27 @@ grid.center = (120, 80)  # pixels: (cells * cell_size / 2)
 # set grid.center to focus on that position. To position the camera in tile coordinates, use grid.center_camera():
 grid.center_camera((14.5, 8.5)) # offset of 0.5 tiles to point at the middle of the tile
 
-# Keyboard handler: key names are "Num1", "Num2", "Escape", "Q", etc.
+# Keyboard handler (#184): receives Key and InputState enums
-def on_key(key, state):
+def on_key(key, action):
-    if key == "Num1" and state == "start":
+    if key == mcrfpy.Key.Num1 and action == mcrfpy.InputState.PRESSED:
         demo_scene.activate()
+scene.on_key = on_key
+
+# Mouse callbacks (#230):
+# on_click receives (pos: Vector, button: MouseButton, action: InputState)
+def on_click(pos, button, action):
+    if button == mcrfpy.MouseButton.LEFT and action == mcrfpy.InputState.PRESSED:
+        print(f"Clicked at {pos.x}, {pos.y}")
+frame.on_click = on_click
+
+# Hover callbacks (#230) receive only position:
+def on_enter(pos):
+    print(f"Entered at {pos.x}, {pos.y}")
+frame.on_enter = on_enter  # Also: on_exit, on_move
+
+# Grid cell callbacks (#230):
+# on_cell_click receives (cell_pos: Vector, button: MouseButton, action: InputState)
+# on_cell_enter/on_cell_exit receive only (cell_pos: Vector)
 ```
 
 ## Development Best Practices

docs/API_REFERENCE_DYNAMIC.md

@@ -1,6 +1,6 @@
 # McRogueFace API Reference
 
-*Generated on 2026-01-23 20:45:13*
+*Generated on 2026-01-28 19:16:58*
 
 *This documentation was dynamically generated from the compiled module.*
 
@@ -13,6 +13,7 @@
   - [Animation](#animation)
   - [Arc](#arc)
   - [BSP](#bsp)
+  - [CallableBinding](#callablebinding)
   - [Caption](#caption)
   - [Circle](#circle)
   - [Color](#color)
@@ -34,7 +35,9 @@
   - [MouseButton](#mousebutton)
   - [Music](#music)
   - [NoiseSource](#noisesource)
+  - [PropertyBinding](#propertybinding)
   - [Scene](#scene)
+  - [Shader](#shader)
   - [Sound](#sound)
   - [Sprite](#sprite)
   - [Texture](#texture)
@@ -508,9 +511,12 @@ Attributes:
 - `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.
 - `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.
 - `pos`: Position as a Vector (same as center).
 - `radius`: Arc radius in pixels
+- `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.
 - `start_angle`: Starting angle in degrees
 - `thickness`: Line thickness
 - `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
@@ -682,6 +688,32 @@ Note:
 
 **Returns:** Iterator yielding BSPNode objects Orders: PRE_ORDER, IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER
 
+### CallableBinding
+
+CallableBinding(callable: Callable[[], float])
+
+A binding that calls a Python function to get its value.
+
+Args:
+    callable: A function that takes no arguments and returns a float
+
+The callable is invoked every frame when the shader is rendered.
+Keep the callable lightweight to avoid performance issues.
+
+Example:
+    player_health = 100
+    frame.uniforms['health_pct'] = mcrfpy.CallableBinding(
+        lambda: player_health / 100.0
+    )
+
+
+**Properties:**
+- `callable` *(read-only)*: The Python callable (read-only).
+- `is_valid` *(read-only)*: True if the callable is still valid (bool, read-only).
+- `value` *(read-only)*: Current value from calling the callable (float, read-only). Returns None on error.
+
+**Methods:**
+
 ### Caption
 
 *Inherits from: Drawable*
@@ -750,12 +782,17 @@ Attributes:
 - `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.
 - `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
 - `outline_color`: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
 - `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`: (x, y) vector
+- `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.
 - `size` *(read-only)*: Text dimensions as Vector (read-only)
 - `text`: The text displayed
+- `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.
 - `w` *(read-only)*: Text width in pixels (read-only)
@@ -873,11 +910,14 @@ Attributes:
 - `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.
 - `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 (0 for no outline)
 - `outline_color`: Outline color of the circle
 - `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 a Vector (same as center).
 - `radius`: Circle radius in pixels
+- `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.
 - `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.
 - `z_index`: Z-order for rendering (lower values rendered first).
@@ -1351,8 +1391,10 @@ Attributes:
 - `name`: Name for finding elements
 - `opacity`: Opacity (0.0 = transparent, 1.0 = opaque)
 - `pos`: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.
+- `shader`: Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.
 - `sprite_index`: Sprite index on the texture on the display
 - `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
+- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
 - `visible`: Visibility flag
 - `x`: Pixel X position relative to grid. Requires entity to be attached to a grid.
 - `y`: Pixel Y position relative to grid. Requires entity to be attached to a grid.
@@ -1605,10 +1647,15 @@ Attributes:
 - `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.
 - `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
 - `outline_color`: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
 - `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 a Vector
+- `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.
+- `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.
 - `w`: width of the rectangle
@@ -1729,6 +1776,7 @@ 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)).
+- `camera_rotation`: Rotation of grid contents around camera center (degrees). The grid widget stays axis-aligned; only the view into the world rotates.
 - `center`: Grid coordinate at the center of the Grid's view (pan)
 - `center_x`: center of the view X-coordinate
 - `center_y`: center of the view Y-coordinate
@@ -1758,13 +1806,18 @@ Attributes:
 - `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.
 - `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.
 - `perspective`: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.
 - `perspective_enabled`: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.
 - `pos`: Position of the grid as Vector
 - `position`: Position of the grid (x, y)
+- `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.
 - `size`: Size of the grid as Vector (width, height)
 - `texture`: Texture of the grid
+- `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.
 - `w`: visible widget width
@@ -2615,8 +2668,11 @@ Attributes:
 - `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.
 - `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.
 - `pos`: Position as a Vector (midpoint of line).
+- `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.
 - `start`: Starting point of the line as a Vector.
 - `thickness`: Line thickness in pixels.
 - `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
@@ -2900,6 +2956,33 @@ Get turbulence (absolute fbm) value at coordinates.
 
 **Raises:** ValueError: Position tuple length doesn't match dimensions
 
+### PropertyBinding
+
+PropertyBinding(target: UIDrawable, property: str)
+
+A binding that reads a property value from a UI drawable.
+
+Args:
+    target: The drawable to read the property from
+    property: Name of the property to read (e.g., 'x', 'opacity')
+
+Use this to create dynamic shader uniforms that follow a drawable's
+properties. The binding automatically handles cases where the target
+is destroyed.
+
+Example:
+    other_frame = mcrfpy.Frame(pos=(100, 100))
+    frame.uniforms['offset_x'] = mcrfpy.PropertyBinding(other_frame, 'x')
+
+
+**Properties:**
+- `is_valid` *(read-only)*: True if the binding target still exists and property is valid (bool, read-only).
+- `property` *(read-only)*: The property name being read (str, read-only).
+- `target` *(read-only)*: The drawable this binding reads from (read-only).
+- `value` *(read-only)*: Current value of the binding (float, read-only). Returns None if invalid.
+
+**Methods:**
+
 ### Scene
 
 Scene(name: str)
@@ -2948,7 +3031,7 @@ Example:
 - `active` *(read-only)*: Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.
 - `children` *(read-only)*: UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.
 - `name` *(read-only)*: Scene name (str, read-only). Unique identifier for this scene.
-- `on_key`: Keyboard event handler (callable or None). Function receives (key: str, action: str) for keyboard events. Set to None to remove the handler.
+- `on_key`: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.
 - `opacity`: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.
 - `pos`: Scene position offset (Vector). Applied to all UI elements during rendering.
 - `visible`: Scene visibility (bool). If False, scene is not rendered.
@@ -2974,6 +3057,59 @@ Recalculate alignment for all children with alignment set.
 Note:
     Call this after window resize or when game_resolution changes. For responsive layouts, connect this to on_resize callback.
 
+### Shader
+
+Shader(fragment_source: str, dynamic: bool = False)
+
+A GPU shader program for visual effects.
+
+Args:
+    fragment_source: GLSL fragment shader source code
+    dynamic: If True, shader uses time-varying effects and will
+             invalidate parent caches each frame
+
+Shaders enable GPU-accelerated visual effects like glow, distortion,
+color manipulation, and more. Assign to drawable.shader to apply.
+
+Engine-provided uniforms (automatically available):
+    - float time: Seconds since engine start
+    - float delta_time: Seconds since last frame
+    - vec2 resolution: Texture size in pixels
+    - vec2 mouse: Mouse position in window coordinates
+
+Example:
+    shader = mcrfpy.Shader('''
+        uniform sampler2D texture;
+        uniform float time;
+        void main() {
+            vec2 uv = gl_TexCoord[0].xy;
+            vec4 color = texture2D(texture, uv);
+            color.rgb *= 0.5 + 0.5 * sin(time);
+            gl_FragColor = color;
+        }
+    ''', dynamic=True)
+    frame.shader = shader
+
+
+**Properties:**
+- `dynamic`: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.
+- `is_valid` *(read-only)*: True if the shader compiled successfully (bool, read-only).
+- `source` *(read-only)*: The GLSL fragment shader source code (str, read-only).
+
+**Methods:**
+
+#### `set_uniform(name: str, value: float|tuple) -> None`
+
+Set a custom uniform value on this shader.
+
+Note:
+
+**Arguments:**
+- `name`: Uniform variable name in the shader
+- `value`: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4 (4-tuple)
+
+**Raises:** ValueError: If uniform type cannot be determined Engine uniforms (time, resolution, etc.) are set automatically
+
 ### Sound
 
 Sound effect object for short audio clips
@@ -3062,14 +3198,19 @@ Attributes:
 - `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.
 - `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.
 - `pos`: Position as a Vector
+- `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.
 - `scale`: Uniform size factor
 - `scale_x`: Horizontal scale factor
 - `scale_y`: Vertical scale factor
+- `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.
 - `sprite_index`: Which sprite on the texture is shown
 - `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
 - `texture`: Texture object
+- `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.
 - `x`: X coordinate of top-left corner

docs/api_reference_dynamic.html

@@ -108,7 +108,7 @@
 <body>
     <div class="container">
         <h1>McRogueFace API Reference</h1>
-        <p><em>Generated on 2026-01-23 20:45:13</em></p>
+        <p><em>Generated on 2026-01-28 19:16:58</em></p>
         <p><em>This documentation was dynamically generated from the compiled module.</em></p>
         
         <div class="toc">
@@ -122,6 +122,7 @@
                         <li><a href="#Animation">Animation</a></li>
                         <li><a href="#Arc">Arc</a></li>
                         <li><a href="#BSP">BSP</a></li>
+                        <li><a href="#CallableBinding">CallableBinding</a></li>
                         <li><a href="#Caption">Caption</a></li>
                         <li><a href="#Circle">Circle</a></li>
                         <li><a href="#Color">Color</a></li>
@@ -143,7 +144,9 @@
                         <li><a href="#MouseButton">MouseButton</a></li>
                         <li><a href="#Music">Music</a></li>
                         <li><a href="#NoiseSource">NoiseSource</a></li>
+                        <li><a href="#PropertyBinding">PropertyBinding</a></li>
                         <li><a href="#Scene">Scene</a></li>
+                        <li><a href="#Shader">Shader</a></li>
                         <li><a href="#Sound">Sound</a></li>
                         <li><a href="#Sprite">Sprite</a></li>
                         <li><a href="#Texture">Texture</a></li>
@@ -630,9 +633,12 @@ Attributes:
                 <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'>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>
                 <li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
                 <li><span class='property-name'>radius</span>: Arc radius in pixels</li>
+                <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'>start_angle</span>: Starting angle in degrees</li>
                 <li><span class='property-name'>thickness</span>: Line thickness</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>
@@ -807,6 +813,33 @@ Note:</p>
             </div>
         </div>
 
+        <div class="method-section">
+            <h3 id="CallableBinding"><span class="class-name">CallableBinding</span></h3>
+            <p>CallableBinding(callable: Callable[[], float])
+
+A binding that calls a Python function to get its value.
+
+Args:
+    callable: A function that takes no arguments and returns a float
+
+The callable is invoked every frame when the shader is rendered.
+Keep the callable lightweight to avoid performance issues.
+
+Example:
+    player_health = 100
+    frame.uniforms[&#x27;health_pct&#x27;] = mcrfpy.CallableBinding(
+        lambda: player_health / 100.0
+    )
+</p>
+            <h4>Properties:</h4>
+            <ul>
+                <li><span class='property-name'>callable</span> (read-only): The Python callable (read-only).</li>
+                <li><span class='property-name'>is_valid</span> (read-only): True if the callable is still valid (bool, read-only).</li>
+                <li><span class='property-name'>value</span> (read-only): Current value from calling the callable (float, read-only). Returns None on error.</li>
+            </ul>
+            <h4>Methods:</h4>
+        </div>
+
         <div class="method-section">
             <h3 id="Caption"><span class="class-name">Caption</span></h3>
             <p><em>Inherits from: Drawable</em></p>
@@ -874,12 +907,17 @@ Attributes:
                 <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'>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</li>
                 <li><span class='property-name'>outline_color</span>: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</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>: (x, y) vector</li>
+                <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'>size</span> (read-only): Text dimensions as Vector (read-only)</li>
                 <li><span class='property-name'>text</span>: The text displayed</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>
                 <li><span class='property-name'>w</span> (read-only): Text width in pixels (read-only)</li>
@@ -999,11 +1037,14 @@ Attributes:
                 <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'>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 (0 for no outline)</li>
                 <li><span class='property-name'>outline_color</span>: Outline color of the circle</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 a Vector (same as center).</li>
                 <li><span class='property-name'>radius</span>: Circle radius in pixels</li>
+                <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'>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>
                 <li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
@@ -1501,8 +1542,10 @@ Attributes:
                 <li><span class='property-name'>name</span>: Name for finding elements</li>
                 <li><span class='property-name'>opacity</span>: Opacity (0.0 = transparent, 1.0 = opaque)</li>
                 <li><span class='property-name'>pos</span>: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.</li>
+                <li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.</li>
                 <li><span class='property-name'>sprite_index</span>: Sprite index on the texture on the display</li>
                 <li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</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: entity.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
                 <li><span class='property-name'>visible</span>: Visibility flag</li>
                 <li><span class='property-name'>x</span>: Pixel X position relative to grid. Requires entity to be attached to a grid.</li>
                 <li><span class='property-name'>y</span>: Pixel Y position relative to grid. Requires entity to be attached to a grid.</li>
@@ -1768,10 +1811,15 @@ Attributes:
                 <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'>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</li>
                 <li><span class='property-name'>outline_color</span>: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</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 a Vector</li>
+                <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'>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>
                 <li><span class='property-name'>w</span>: width of the rectangle</li>
@@ -1894,6 +1942,7 @@ Attributes:
             <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'>camera_rotation</span>: Rotation of grid contents around camera center (degrees). The grid widget stays axis-aligned; only the view into the world rotates.</li>
                 <li><span class='property-name'>center</span>: Grid coordinate at the center of the Grid&#x27;s view (pan)</li>
                 <li><span class='property-name'>center_x</span>: center of the view X-coordinate</li>
                 <li><span class='property-name'>center_y</span>: center of the view Y-coordinate</li>
@@ -1923,13 +1972,18 @@ Attributes:
                 <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'>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>
                 <li><span class='property-name'>perspective</span>: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.</li>
                 <li><span class='property-name'>perspective_enabled</span>: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.</li>
                 <li><span class='property-name'>pos</span>: Position of the grid as Vector</li>
                 <li><span class='property-name'>position</span>: Position of the grid (x, y)</li>
+                <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'>size</span>: Size of the grid as Vector (width, height)</li>
                 <li><span class='property-name'>texture</span>: Texture of the grid</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>
                 <li><span class='property-name'>w</span>: visible widget width</li>
@@ -2798,8 +2852,11 @@ Attributes:
                 <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'>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>
                 <li><span class='property-name'>pos</span>: Position as a Vector (midpoint of line).</li>
+                <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'>start</span>: Starting point of the line as a Vector.</li>
                 <li><span class='property-name'>thickness</span>: Line thickness in pixels.</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>
@@ -3096,6 +3153,34 @@ Note:</p>
             </div>
         </div>
 
+        <div class="method-section">
+            <h3 id="PropertyBinding"><span class="class-name">PropertyBinding</span></h3>
+            <p>PropertyBinding(target: UIDrawable, property: str)
+
+A binding that reads a property value from a UI drawable.
+
+Args:
+    target: The drawable to read the property from
+    property: Name of the property to read (e.g., &#x27;x&#x27;, &#x27;opacity&#x27;)
+
+Use this to create dynamic shader uniforms that follow a drawable&#x27;s
+properties. The binding automatically handles cases where the target
+is destroyed.
+
+Example:
+    other_frame = mcrfpy.Frame(pos=(100, 100))
+    frame.uniforms[&#x27;offset_x&#x27;] = mcrfpy.PropertyBinding(other_frame, &#x27;x&#x27;)
+</p>
+            <h4>Properties:</h4>
+            <ul>
+                <li><span class='property-name'>is_valid</span> (read-only): True if the binding target still exists and property is valid (bool, read-only).</li>
+                <li><span class='property-name'>property</span> (read-only): The property name being read (str, read-only).</li>
+                <li><span class='property-name'>target</span> (read-only): The drawable this binding reads from (read-only).</li>
+                <li><span class='property-name'>value</span> (read-only): Current value of the binding (float, read-only). Returns None if invalid.</li>
+            </ul>
+            <h4>Methods:</h4>
+        </div>
+
         <div class="method-section">
             <h3 id="Scene"><span class="class-name">Scene</span></h3>
             <p>Scene(name: str)
@@ -3144,7 +3229,7 @@ Example:
                 <li><span class='property-name'>active</span> (read-only): Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.</li>
                 <li><span class='property-name'>children</span> (read-only): UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.</li>
                 <li><span class='property-name'>name</span> (read-only): Scene name (str, read-only). Unique identifier for this scene.</li>
-                <li><span class='property-name'>on_key</span>: Keyboard event handler (callable or None). Function receives (key: str, action: str) for keyboard events. Set to None to remove the handler.</li>
+                <li><span class='property-name'>on_key</span>: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.</li>
                 <li><span class='property-name'>opacity</span>: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.</li>
                 <li><span class='property-name'>pos</span>: Scene position offset (Vector). Applied to all UI elements during rendering.</li>
                 <li><span class='property-name'>visible</span>: Scene visibility (bool). If False, scene is not rendered.</li>
@@ -3172,6 +3257,60 @@ Note:
             </div>
         </div>
 
+        <div class="method-section">
+            <h3 id="Shader"><span class="class-name">Shader</span></h3>
+            <p>Shader(fragment_source: str, dynamic: bool = False)
+
+A GPU shader program for visual effects.
+
+Args:
+    fragment_source: GLSL fragment shader source code
+    dynamic: If True, shader uses time-varying effects and will
+             invalidate parent caches each frame
+
+Shaders enable GPU-accelerated visual effects like glow, distortion,
+color manipulation, and more. Assign to drawable.shader to apply.
+
+Engine-provided uniforms (automatically available):
+    - float time: Seconds since engine start
+    - float delta_time: Seconds since last frame
+    - vec2 resolution: Texture size in pixels
+    - vec2 mouse: Mouse position in window coordinates
+
+Example:
+    shader = mcrfpy.Shader(&#x27;&#x27;&#x27;
+        uniform sampler2D texture;
+        uniform float time;
+        void main() {
+            vec2 uv = gl_TexCoord[0].xy;
+            vec4 color = texture2D(texture, uv);
+            color.rgb *= 0.5 + 0.5 * sin(time);
+            gl_FragColor = color;
+        }
+    &#x27;&#x27;&#x27;, dynamic=True)
+    frame.shader = shader
+</p>
+            <h4>Properties:</h4>
+            <ul>
+                <li><span class='property-name'>dynamic</span>: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.</li>
+                <li><span class='property-name'>is_valid</span> (read-only): True if the shader compiled successfully (bool, read-only).</li>
+                <li><span class='property-name'>source</span> (read-only): The GLSL fragment shader source code (str, read-only).</li>
+            </ul>
+            <h4>Methods:</h4>
+
+            <div style="margin-left: 20px; margin-bottom: 15px;">
+                <h5><code class="method-name">set_uniform(name: str, value: float|tuple) -> None</code></h5>
+                <p>Set a custom uniform value on this shader.
+
+Note:</p>
+                <div style='margin-left: 20px;'>
+                    <div><span class='arg-name'>name</span>: Uniform variable name in the shader</div>
+                    <div><span class='arg-name'>value</span>: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4 (4-tuple)</div>
+                </div>
+                <p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If uniform type cannot be determined Engine uniforms (time, resolution, etc.) are set automatically</p>
+            </div>
+        </div>
+
         <div class="method-section">
             <h3 id="Sound"><span class="class-name">Sound</span></h3>
             <p>Sound effect object for short audio clips</p>
@@ -3263,14 +3402,19 @@ Attributes:
                 <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'>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>
                 <li><span class='property-name'>pos</span>: Position as a Vector</li>
+                <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'>scale</span>: Uniform size factor</li>
                 <li><span class='property-name'>scale_x</span>: Horizontal scale factor</li>
                 <li><span class='property-name'>scale_y</span>: Vertical scale factor</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'>sprite_index</span>: Which sprite on the texture is shown</li>
                 <li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</li>
                 <li><span class='property-name'>texture</span>: Texture object</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>
                 <li><span class='property-name'>x</span>: X coordinate of top-left corner</li>

docs/mcrfpy.3

@@ -14,11 +14,11 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "MCRFPY" "3" "2026-01-23" "McRogueFace 0.2.1-prerelease-7drl2026-15-g3fea641" ""
+.TH "MCRFPY" "3" "2026-01-28" "McRogueFace 0.2.2-prerelease-7drl2026-12-g55f6ea9" ""
 .hy
 .SH McRogueFace API Reference
 .PP
-\f[I]Generated on 2026-01-23 20:45:13\f[R]
+\f[I]Generated on 2026-01-28 19:16:58\f[R]
 .PP
 \f[I]This documentation was dynamically generated from the compiled
 module.\f[R]
@@ -39,6 +39,8 @@ Arc
 .IP \[bu] 2
 BSP
 .IP \[bu] 2
+CallableBinding
+.IP \[bu] 2
 Caption
 .IP \[bu] 2
 Circle
@@ -81,8 +83,12 @@ Music
 .IP \[bu] 2
 NoiseSource
 .IP \[bu] 2
+PropertyBinding
+.IP \[bu] 2
 Scene
 .IP \[bu] 2
+Shader
+.IP \[bu] 2
 Sound
 .IP \[bu] 2
 Sprite
@@ -599,14 +605,25 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]parent\f[R]: 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.
 - \f[V]pos\f[R]: Position as a Vector (same as center).
-- \f[V]radius\f[R]: Arc radius in pixels - \f[V]start_angle\f[R]:
+- \f[V]radius\f[R]: Arc radius in pixels - \f[V]rotate_with_camera\f[R]:
-Starting angle in degrees - \f[V]thickness\f[R]: Line thickness -
+Whether to rotate visually with parent Grid\[cq]s camera_rotation
-\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
+(bool).
-margin).
+False (default): stay screen-aligned.
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]start_angle\f[R]: Starting angle in degrees -
+\f[V]thickness\f[R]: Line thickness - \f[V]vert_margin\f[R]: Vertical
+margin override (float, 0 = use general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -789,6 +806,29 @@ Default: LEVEL_ORDER.
 .PP
 \f[B]Returns:\f[R] Iterator yielding BSPNode objects Orders: PRE_ORDER,
 IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER
+.SS CallableBinding
+.PP
+CallableBinding(callable: Callable[[], float])
+.PP
+A binding that calls a Python function to get its value.
+.PP
+Args: callable: A function that takes no arguments and returns a float
+.PP
+The callable is invoked every frame when the shader is rendered.
+Keep the callable lightweight to avoid performance issues.
+.PP
+Example: player_health = 100 frame.uniforms[`health_pct'] =
+mcrfpy.CallableBinding( lambda: player_health / 100.0 )
+.PP
+\f[B]Properties:\f[R] - \f[V]callable\f[R] \f[I](read-only)\f[R]: The
+Python callable (read-only).
+- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the callable is
+still valid (bool, read-only).
+- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value from calling the
+callable (float, read-only).
+Returns None on error.
+.PP
+\f[B]Methods:\f[R]
 .SS Caption
 .PP
 \f[I]Inherits from: Drawable\f[R]
@@ -878,6 +918,9 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
 Outline color of the text.
 Returns a copy; modifying components requires reassignment.
@@ -885,10 +928,25 @@ For animation, use `outline_color.r', `outline_color.g', etc.
 - \f[V]parent\f[R]: 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.
-- \f[V]pos\f[R]: (x, y) vector - \f[V]size\f[R] \f[I](read-only)\f[R]:
+- \f[V]pos\f[R]: (x, y) vector - \f[V]rotate_with_camera\f[R]: Whether
-Text dimensions as Vector (read-only) - \f[V]text\f[R]: The text
+to rotate visually with parent Grid\[cq]s camera_rotation (bool).
-displayed - \f[V]vert_margin\f[R]: Vertical margin override (float, 0 =
+False (default): stay screen-aligned.
-use general margin).
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]shader\f[R]: 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.
+- \f[V]size\f[R] \f[I](read-only)\f[R]: Text dimensions as Vector
+(read-only) - \f[V]text\f[R]: The text displayed - \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.
+Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
+- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
+general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -1023,14 +1081,26 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]outline\f[R]: Outline thickness (0 for no outline) -
 \f[V]outline_color\f[R]: Outline color of the circle - \f[V]parent\f[R]:
 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.
 - \f[V]pos\f[R]: Position as a Vector (same as center).
-- \f[V]radius\f[R]: Circle radius in pixels - \f[V]vert_margin\f[R]:
+- \f[V]radius\f[R]: Circle radius in pixels -
-Vertical margin override (float, 0 = use general margin).
+\f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
+Grid\[cq]s camera_rotation (bool).
+False (default): stay screen-aligned.
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
+general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -1485,10 +1555,17 @@ The logical cell this entity occupies.
 relative to grid (Vector).
 Computed as draw_pos * tile_size.
 Requires entity to be attached to a grid.
+- \f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
+When set, the entity is rendered through the shader program.
+Set to None to disable shader effects.
 - \f[V]sprite_index\f[R]: Sprite index on the texture on the display -
 \f[V]sprite_number\f[R]: Sprite index (DEPRECATED: use sprite_index
-instead) - \f[V]visible\f[R]: Visibility flag - \f[V]x\f[R]: Pixel X
+instead) - \f[V]uniforms\f[R] \f[I](read-only)\f[R]: Collection of
-position relative to grid.
+shader uniforms (read-only access to collection).
+Set uniforms via dict-like syntax: entity.uniforms[`name'] = value.
+Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
+- \f[V]visible\f[R]: Visibility flag - \f[V]x\f[R]: Pixel X position
+relative to grid.
 Requires entity to be attached to a grid.
 - \f[V]y\f[R]: Pixel Y position relative to grid.
 Requires entity to be attached to a grid.
@@ -1750,6 +1827,9 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
 Outline color of the rectangle.
 Returns a copy; modifying components requires reassignment.
@@ -1757,8 +1837,24 @@ For animation, use `outline_color.r', `outline_color.g', etc.
 - \f[V]parent\f[R]: 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.
-- \f[V]pos\f[R]: Position as a Vector - \f[V]vert_margin\f[R]: Vertical
+- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
-margin override (float, 0 = use general margin).
+Whether to rotate visually with parent Grid\[cq]s camera_rotation
+(bool).
+False (default): stay screen-aligned.
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]shader\f[R]: 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.
+- \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.
+Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
+- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
+general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -1875,6 +1971,10 @@ 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]camera_rotation\f[R]: Rotation of grid contents around camera
+center (degrees).
+The grid widget stays axis-aligned; only the view into the world
+rotates.
 - \f[V]center\f[R]: Grid coordinate at the center of the Grid\[cq]s view
 (pan) - \f[V]center_x\f[R]: center of the view X-coordinate -
 \f[V]center_y\f[R]: center of the view Y-coordinate -
@@ -1933,6 +2033,9 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]parent\f[R]: 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.
@@ -1943,10 +2046,25 @@ Setting an entity automatically enables perspective mode.
 rendering.
 When True with no valid entity, all cells appear undiscovered.
 - \f[V]pos\f[R]: Position of the grid as Vector - \f[V]position\f[R]:
-Position of the grid (x, y) - \f[V]size\f[R]: Size of the grid as Vector
+Position of the grid (x, y) - \f[V]rotate_with_camera\f[R]: Whether to
-(width, height) - \f[V]texture\f[R]: Texture of the grid -
+rotate visually with parent Grid\[cq]s camera_rotation (bool).
-\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
+False (default): stay screen-aligned.
-margin).
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]shader\f[R]: 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.
+- \f[V]size\f[R]: Size of the grid as Vector (width, height) -
+\f[V]texture\f[R]: Texture of the grid - \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.
+Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
+- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
+general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).
@@ -2743,10 +2861,21 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]parent\f[R]: 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.
 - \f[V]pos\f[R]: Position as a Vector (midpoint of line).
+- \f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
+Grid\[cq]s camera_rotation (bool).
+False (default): stay screen-aligned.
+True: tilt with camera.
+Only affects children of UIGrid; ignored for other parents.
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
 - \f[V]start\f[R]: Starting point of the line as a Vector.
 - \f[V]thickness\f[R]: Line thickness in pixels.
 - \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
@@ -3041,6 +3170,34 @@ combine (default: 4)
 .PP
 \f[B]Raises:\f[R] ValueError: Position tuple length doesn\[cq]t match
 dimensions
+.SS PropertyBinding
+.PP
+PropertyBinding(target: UIDrawable, property: str)
+.PP
+A binding that reads a property value from a UI drawable.
+.PP
+Args: target: The drawable to read the property from property: Name of
+the property to read (e.g., `x', `opacity')
+.PP
+Use this to create dynamic shader uniforms that follow a drawable\[cq]s
+properties.
+The binding automatically handles cases where the target is destroyed.
+.PP
+Example: other_frame = mcrfpy.Frame(pos=(100, 100))
+frame.uniforms[`offset_x'] = mcrfpy.PropertyBinding(other_frame, `x')
+.PP
+\f[B]Properties:\f[R] - \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True
+if the binding target still exists and property is valid (bool,
+read-only).
+- \f[V]property\f[R] \f[I](read-only)\f[R]: The property name being read
+(str, read-only).
+- \f[V]target\f[R] \f[I](read-only)\f[R]: The drawable this binding
+reads from (read-only).
+- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value of the binding
+(float, read-only).
+Returns None if invalid.
+.PP
+\f[B]Methods:\f[R]
 .SS Scene
 .PP
 Scene(name: str)
@@ -3100,7 +3257,7 @@ Changes are reflected immediately.
 - \f[V]name\f[R] \f[I](read-only)\f[R]: Scene name (str, read-only).
 Unique identifier for this scene.
 - \f[V]on_key\f[R]: Keyboard event handler (callable or None).
-Function receives (key: str, action: str) for keyboard events.
+Function receives (key: Key, action: InputState) for keyboard events.
 Set to None to remove the handler.
 - \f[V]opacity\f[R]: Scene opacity (0.0-1.0).
 Applied to all UI elements during rendering.
@@ -3131,6 +3288,53 @@ Recalculate alignment for all children with alignment set.
 .PP
 Note: Call this after window resize or when game_resolution changes.
 For responsive layouts, connect this to on_resize callback.
+.SS Shader
+.PP
+Shader(fragment_source: str, dynamic: bool = False)
+.PP
+A GPU shader program for visual effects.
+.PP
+Args: fragment_source: GLSL fragment shader source code dynamic: If
+True, shader uses time-varying effects and will invalidate parent caches
+each frame
+.PP
+Shaders enable GPU-accelerated visual effects like glow, distortion,
+color manipulation, and more.
+Assign to drawable.shader to apply.
+.PP
+Engine-provided uniforms (automatically available): - float time:
+Seconds since engine start - float delta_time: Seconds since last frame
+- vec2 resolution: Texture size in pixels - vec2 mouse: Mouse position
+in window coordinates
+.PP
+Example: shader = mcrfpy.Shader(\[cq]\[cq]\[cq] uniform sampler2D
+texture; uniform float time; void main() { vec2 uv = gl_TexCoord[0].xy;
+vec4 color = texture2D(texture, uv); color.rgb \f[I]= 0.5 + 0.5 \f[R]
+sin(time); gl_FragColor = color; } \[cq]\[cq]\[cq], dynamic=True)
+frame.shader = shader
+.PP
+\f[B]Properties:\f[R] - \f[V]dynamic\f[R]: Whether this shader uses
+time-varying effects (bool).
+Dynamic shaders invalidate parent caches each frame.
+- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the shader compiled
+successfully (bool, read-only).
+- \f[V]source\f[R] \f[I](read-only)\f[R]: The GLSL fragment shader
+source code (str, read-only).
+.PP
+\f[B]Methods:\f[R]
+.SS \f[V]set_uniform(name: str, value: float|tuple) -> None\f[R]
+.PP
+Set a custom uniform value on this shader.
+.PP
+Note:
+.PP
+\f[B]Arguments:\f[R] - \f[V]name\f[R]: Uniform variable name in the
+shader - \f[V]value\f[R]: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4
+(4-tuple)
+.PP
+\f[B]Raises:\f[R] ValueError: If uniform type cannot be determined
+Engine uniforms (time, resolution, etc.)
+are set automatically
 .SS Sound
 .PP
 Sound effect object for short audio clips
@@ -3238,16 +3442,35 @@ Performance note: Called frequently during movement - keep handlers
 fast.
 - \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
 Automatically clamped to valid range [0.0, 1.0].
+- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
+rotation).
+Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
 - \f[V]parent\f[R]: 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.
-- \f[V]pos\f[R]: Position as a Vector - \f[V]scale\f[R]: Uniform size
+- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
-factor - \f[V]scale_x\f[R]: Horizontal scale factor - \f[V]scale_y\f[R]:
+Whether to rotate visually with parent Grid\[cq]s camera_rotation
-Vertical scale factor - \f[V]sprite_index\f[R]: Which sprite on the
+(bool).
-texture is shown - \f[V]sprite_number\f[R]: Sprite index (DEPRECATED:
+False (default): stay screen-aligned.
-use sprite_index instead) - \f[V]texture\f[R]: Texture object -
+True: tilt with camera.
-\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
+Only affects children of UIGrid; ignored for other parents.
-margin).
+- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
+origin).
+Animatable property.
+- \f[V]scale\f[R]: Uniform size factor - \f[V]scale_x\f[R]: Horizontal
+scale factor - \f[V]scale_y\f[R]: Vertical scale factor -
+\f[V]shader\f[R]: 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.
+- \f[V]sprite_index\f[R]: Which sprite on the texture is shown -
+\f[V]sprite_number\f[R]: Sprite index (DEPRECATED: use sprite_index
+instead) - \f[V]texture\f[R]: Texture object - \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.
+Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
+- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
+general margin).
 Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
 CENTER).
 - \f[V]visible\f[R]: Whether the object is visible (bool).

stubs/mcrfpy.pyi

@@ -9,6 +9,88 @@ from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload
 UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid', 'Line', 'Circle', 'Arc']
 Transition = Union[str, None]
 
+# Enums
+
+class Key:
+    """Keyboard key codes enum.
+
+    All standard keyboard keys are available as class attributes:
+    A-Z, Num0-Num9, F1-F15, Arrow keys, modifiers, etc.
+    """
+    A: 'Key'
+    B: 'Key'
+    C: 'Key'
+    # ... (all letters A-Z)
+    Num0: 'Key'
+    Num1: 'Key'
+    Num2: 'Key'
+    # ... (Num0-Num9)
+    ESCAPE: 'Key'
+    ENTER: 'Key'
+    SPACE: 'Key'
+    TAB: 'Key'
+    BACKSPACE: 'Key'
+    DELETE: 'Key'
+    UP: 'Key'
+    DOWN: 'Key'
+    LEFT: 'Key'
+    RIGHT: 'Key'
+    LSHIFT: 'Key'
+    RSHIFT: 'Key'
+    LCTRL: 'Key'
+    RCTRL: 'Key'
+    LALT: 'Key'
+    RALT: 'Key'
+    # ... (additional keys)
+
+class MouseButton:
+    """Mouse button enum for click callbacks."""
+    LEFT: 'MouseButton'
+    RIGHT: 'MouseButton'
+    MIDDLE: 'MouseButton'
+
+class InputState:
+    """Input action state enum for callbacks."""
+    PRESSED: 'InputState'
+    RELEASED: 'InputState'
+
+class Easing:
+    """Animation easing function enum.
+
+    Available easing functions for smooth animations.
+    """
+    LINEAR: 'Easing'
+    EASE_IN: 'Easing'
+    EASE_OUT: 'Easing'
+    EASE_IN_OUT: 'Easing'
+    EASE_IN_QUAD: 'Easing'
+    EASE_OUT_QUAD: 'Easing'
+    EASE_IN_OUT_QUAD: 'Easing'
+    EASE_IN_CUBIC: 'Easing'
+    EASE_OUT_CUBIC: 'Easing'
+    EASE_IN_OUT_CUBIC: 'Easing'
+    EASE_IN_QUART: 'Easing'
+    EASE_OUT_QUART: 'Easing'
+    EASE_IN_OUT_QUART: 'Easing'
+    EASE_IN_SINE: 'Easing'
+    EASE_OUT_SINE: 'Easing'
+    EASE_IN_OUT_SINE: 'Easing'
+    EASE_IN_EXPO: 'Easing'
+    EASE_OUT_EXPO: 'Easing'
+    EASE_IN_OUT_EXPO: 'Easing'
+    EASE_IN_CIRC: 'Easing'
+    EASE_OUT_CIRC: 'Easing'
+    EASE_IN_OUT_CIRC: 'Easing'
+    EASE_IN_ELASTIC: 'Easing'
+    EASE_OUT_ELASTIC: 'Easing'
+    EASE_IN_OUT_ELASTIC: 'Easing'
+    EASE_IN_BACK: 'Easing'
+    EASE_OUT_BACK: 'Easing'
+    EASE_IN_OUT_BACK: 'Easing'
+    EASE_IN_BOUNCE: 'Easing'
+    EASE_OUT_BOUNCE: 'Easing'
+    EASE_IN_OUT_BOUNCE: 'Easing'
+
 # Classes
 
 class Color:
@@ -83,11 +165,13 @@ class Drawable:
     name: str
     pos: Vector
 
-    # Mouse event callbacks (#140, #141)
+    # Mouse event callbacks (#140, #141, #230)
-    on_click: Optional[Callable[[float, float, int, str], None]]
+    # on_click receives (pos: Vector, button: MouseButton, action: InputState)
-    on_enter: Optional[Callable[[float, float, int, str], None]]
+    on_click: Optional[Callable[['Vector', 'MouseButton', 'InputState'], None]]
-    on_exit: Optional[Callable[[float, float, int, str], None]]
+    # Hover callbacks receive only position per #230
-    on_move: Optional[Callable[[float, float, int, str], None]]
+    on_enter: Optional[Callable[['Vector'], None]]
+    on_exit: Optional[Callable[['Vector'], None]]
+    on_move: Optional[Callable[['Vector'], None]]
 
     # Read-only hover state (#140)
     hovered: bool
@@ -222,10 +306,12 @@ class Grid(Drawable):
     fov: 'FOV'  # FOV algorithm enum
     fov_radius: int  # Default FOV radius
 
-    # Cell-level mouse events
+    # Cell-level mouse events (#230)
+    # on_cell_click receives (cell_pos: Vector, button: MouseButton, action: InputState)
+    on_cell_click: Optional[Callable[['Vector', 'MouseButton', 'InputState'], None]]
+    # Cell hover callbacks receive only position per #230
     on_cell_enter: Optional[Callable[['Vector'], None]]
     on_cell_exit: Optional[Callable[['Vector'], None]]
-    on_cell_click: Optional[Callable[['Vector'], None]]
     hovered_cell: Optional[Tuple[int, int]]  # Read-only
 
     def at(self, x: int, y: int) -> 'GridPoint':
@@ -655,7 +741,8 @@ class Scene:
 
     name: str
     children: UICollection  # #151: UI elements collection (read-only alias for get_ui())
-    on_key: Optional[Callable[[str, str], None]]  # Keyboard handler (key, action)
+    # Keyboard handler receives (key: Key, action: InputState) per #184
+    on_key: Optional[Callable[['Key', 'InputState'], None]]
 
     def __init__(self, name: str) -> None: ...
 
@@ -733,25 +820,29 @@ class Window:
         ...
 
 class Animation:
-    """Animation object for animating UI properties."""
+    """Animation object for animating UI properties.
+
+    Note: The preferred way to create animations is via the .animate() method
+    on drawable objects:
+        frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT)
+
+    Animation callbacks (#229) receive (target, property, final_value):
+        def on_complete(target, prop, value):
+            print(f"{type(target).__name__}.{prop} = {value}")
+    """
 
-    target: Any
     property: str
     duration: float
-    easing: str
+    easing: 'Easing'
-    loop: bool
+    # Callback receives (target: Any, property: str, final_value: Any) per #229
-    on_complete: Optional[Callable]
+    callback: Optional[Callable[[Any, str, Any], None]]
 
-    def __init__(self, target: Any, property: str, start_value: Any, end_value: Any,
+    def __init__(self, property: str, end_value: Any, duration: float,
-                 duration: float, easing: str = 'linear', loop: bool = False,
+                 easing: Union[str, 'Easing'] = 'linear',
-                 on_complete: Optional[Callable] = None) -> None: ...
+                 callback: Optional[Callable[[Any, str, Any], None]] = None) -> None: ...
 
-    def start(self) -> None:
+    def start(self, target: Any) -> None:
-        """Start the animation."""
+        """Start the animation on a target object."""
-        ...
-    
-    def update(self, dt: float) -> bool:
-        """Update animation, returns True if still running."""
         ...
 
     def get_current_value(self) -> Any:
@@ -805,15 +896,25 @@ def createScene(name: str) -> None:
     ...
 
 def keypressScene(handler: Callable[[str, bool], None]) -> None:
-    """Set the keyboard event handler for the current scene."""
+    """Set the keyboard event handler for the current scene.
+
+    DEPRECATED: Use scene.on_key = handler instead.
+    The new handler receives (key: Key, action: InputState) enums.
+    """
     ...
 
 def setTimer(name: str, handler: Callable[[float], None], interval: int) -> None:
-    """Create or update a recurring timer."""
+    """Create or update a recurring timer.
+
+    DEPRECATED: Use Timer(name, callback, interval) object instead.
+    """
     ...
 
 def delTimer(name: str) -> None:
-    """Stop and remove a timer."""
+    """Stop and remove a timer.
+
+    DEPRECATED: Use timer.cancel() method instead.
+    """
     ...
 
 def exit() -> None: