Enhance documentation across various guides and examples

api/config.md

@@ -41,10 +41,17 @@ This document covers global configuration options, build flags, and compile-time
 | `PIXELROOT32_ENABLE_DIRTY_REGION_PROFILING` | Enable dirty region profiling metrics. | `0` |
 | `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK` | TFT_eSPI DMA line batch size. | `60` |
 | `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK_FALLBACK` | Fallback DMA batch size if memory fails. | `30` |
+| `PIXELROOT32_TFT_12BIT_COLOR` | Send frames as 12-bit RGB444 (2 pixels per 3 bytes) instead of RGB565. Experimental. | `0` |
 | `PIXELROOT32_DEBUG_MODE` | Enable unified logging system. | Disabled |
 | `PIXELROOT32_VELOCITY_DAMPING` | Per-frame velocity damping factor (0.0-1.0). | `0.999` |
 | `PIXELROOT32_MAX_VELOCITY` | Maximum velocity cap in units/s. | `500` |
 
+### TFT_eSPI Display Flags
+
+> **Note:** `PIXELROOT32_TFT_12BIT_COLOR=1` is **experimental and not yet verified on hardware**. It cuts 25% of the SPI bus time per frame and shrinks each DMA line buffer by 25%, and the driver silently keeps RGB565 when `PHYSICAL_DISPLAY_WIDTH` is not a multiple of 4. See [12-bit Color on the Wire (RGB444)](../guide/performance/esp32-performance.md#12-bit-color-on-the-wire-rgb444) for the bandwidth math, the width constraint and the memory trade-off.
+
+> **Note:** `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK=60` only became reachable in `d6dc9ae`. Earlier builds hit a buffer-selection bug in `buildScaleLUTs()` that always downgraded to `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK_FALLBACK`, so the documented `60` default never applied. The fallback still applies when DMA-capable internal RAM is tight.
+
 ## Memory Savings by Subsystem
 
 | Subsystem Disabled | RAM Savings | Flash Savings |

api/generated/drivers/TFT_eSPI_Drawer.md

@@ -91,6 +91,12 @@ Get pointer to sprite buffer for direct manipulation.
 
 Processes system events. Always true for embedded.
 
+### `void waitForPendingDMA()`
+
+**Description:**
+
+Blocks until the DMA transfer deferred by sendBufferScaled() completes.
+
 ### `bool needsScaling() const`
 
 **Description:**
@@ -122,3 +128,29 @@ Sends the buffer using hardware DMA and software scaling.
 **Description:**
 
 Scales a single line from 8bpp logical to 16bpp physical.
+
+### `void convertBlockRgb444(const uint8_t* spriteBase, int startY, int endY, bool is2x, uint8_t* dst)`
+
+**Description:**
+
+Converts one block of physical lines into the packed RGB444 stream.
+
+**Parameters:**
+
+- `spriteBase`: Base of the 8bpp sprite framebuffer.
+- `startY`: First physical line of the block.
+- `endY`: One past the last physical line of the block.
+- `is2x`: True when the frame is an exact 2x integer upscale.
+- `dst`: Destination line buffer, viewed as raw bytes.
+
+### `void scaleLine444(const uint8_t* spriteBase, int srcY, uint8_t* dst)`
+
+**Description:**
+
+Scales a single line from 8bpp logical to packed RGB444 physical.
+
+### `int bytesPerLine444() const`
+
+**Description:**
+
+Bytes one physical line occupies in the packed RGB444 stream.

api/generated/gameplay/GridMotion.md

@@ -0,0 +1,24 @@
+# GridMotion
+
+<Badge type="info" text="Struct" />
+
+**Source:** `GridMotion.h`
+
+## Description
+
+Plain five-`int` aggregate: logical cell, target cell, progress.
+
+At rest, `toX == cellX`, `toY == cellY` and `progress == 0`. In flight,
+`progress` runs 1..stepsPerCell-1 and the logical cell still names the cell
+being LEFT — it flips only on arrival. Gameplay rules that read the logical
+cell therefore never see an actor occupying two cells, or none.
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `cellX` | `int` | Logical cell X — the one every gameplay rule reads. |
+| `cellY` | `int` | Logical cell Y — the one every gameplay rule reads. |
+| `toX` | `int` | Target cell X; equals cellX when at rest. |
+| `toY` | `int` | Target cell Y; equals cellY when at rest. |
+| `progress` | `int` | 0..stepsPerCell-1; 0 means "at rest in (cellX, cellY)". |

api/generated/graphics/TransitionEffect.md

@@ -202,8 +202,10 @@ Fill a 256-byte LUT for the current fade direction and progress.
 
 - `scaledProgress`: Progress in Q8.8 format (0..256, where 256 = 1.0).
 
-Out: lut[i] = i * (256-p) / 256 — dims to black.
-In:  lut[i] = i * p     / 256 — brightens from black.
+Out scales by (256-p), In scales by p — but the scale is applied to each
+RGB332 channel of the index, never to the packed byte. The byte is a
+colour, not an intensity: scaling it whole carries bits between channels
+and rotates the hue instead of dimming it.
 
 ### `void applyFade(uint8_t* buffer, int width, int height)`
 

api/generated/graphics/UISprite.md

@@ -0,0 +1,126 @@
+# UISprite
+
+<Badge type="info" text="Class" />
+
+**Source:** `UISprite.h`
+
+**Inherits from:** [UIElement](./UIElement.md)
+
+## Description
+
+A UI leaf that draws a single sprite.
+
+The UI system could previously draw text and rectangles only, so anything
+with an icon — an item slot in a menu, a dialog portrait, a button glyph, a
+HUD resource — had to be drawn by hand in a `Scene::draw()` override,
+outside the entity tree. That costs three things this element gets for
+free: `setVisible()`, placement by a UILayout, and `setFixedPosition()`,
+which bypasses the camera offset so a HUD stays put while the world
+scrolls.
+
+Accepts all three sprite formats (`Sprite`, `Sprite2bpp`, `Sprite4bpp`) via
+UISpriteRef, and adopts the sprite's dimensions as its own so layouts can
+size it. It holds no clock: animating means setting a different sprite,
+which is the game's decision, not the element's.
+
+
+```cpp
+UISprite icon(Vector2(8, 8));
+icon.setSprite(kKeyIcon4bpp);
+icon.setFixedPosition(true);   // stays put while the camera scrolls
+scene.addEntity(&icon);
+```
+
+## Inheritance
+
+[UIElement](./UIElement.md) → `UISprite`
+
+## Methods
+
+### `explicit UISprite(pixelroot32::math::Vector2 position)`
+
+**Description:**
+
+Constructs an empty sprite element at `position`.
+
+### `void setSprite(const Sprite& sprite, Color tint = Color::White)`
+
+**Description:**
+
+Sets a 1bpp sprite, drawn in `tint`.
+
+**Parameters:**
+
+- `sprite`: Sprite to reference. Must outlive this element.
+- `tint`: Color the set pixels are drawn in.
+
+### `void setSprite(const Sprite2bpp& sprite, uint8_t paletteSlot = 0)`
+
+**Description:**
+
+Sets a 2bpp sprite, drawn through `paletteSlot`.
+
+**Parameters:**
+
+- `sprite`: Sprite to reference. Must outlive this element.
+- `paletteSlot`: Sprite palette slot to resolve colors through.
+
+### `void setSprite(const Sprite4bpp& sprite, uint8_t paletteSlot = 0)`
+
+**Description:**
+
+Sets a 4bpp sprite, drawn through `paletteSlot`.
+
+**Parameters:**
+
+- `sprite`: Sprite to reference. Must outlive this element.
+- `paletteSlot`: Sprite palette slot to resolve colors through.
+
+### `void clearSprite()`
+
+**Description:**
+
+Removes the sprite, returning the element to 0x0 and drawing
+       nothing.
+
+### `UISpriteFormat getFormat() const`
+
+### `bool hasSprite() const`
+
+### `Color getTint() const`
+
+### `uint8_t getPaletteSlot() const`
+
+### `void setFlipX(bool flip)`
+
+**Description:**
+
+Mirrors the sprite horizontally when drawn.
+
+### `bool getFlipX() const`
+
+### `void update(unsigned long deltaTime)`
+
+**Description:**
+
+No-op. A sprite leaf has no internal animation clock.
+
+**Parameters:**
+
+- `deltaTime`: Ignored.
+
+### `void draw(pixelroot32::graphics::Renderer& renderer)`
+
+**Description:**
+
+Draws the sprite, honoring isVisible and fixedPosition.
+
+**Parameters:**
+
+- `renderer`: Reference to the renderer.
+
+### `void recalcSize()`
+
+**Description:**
+
+Re-reads width/height from the current sprite.

api/generated/graphics/UISpriteFormat.md

@@ -0,0 +1,9 @@
+# UISpriteFormat
+
+<Badge type="info" text="Enum" />
+
+**Source:** `UISpriteRef.h`
+
+## Description
+
+Which member of a UISpriteRef's storage is live.

api/generated/graphics/UISpriteRef.md

@@ -0,0 +1,19 @@
+# UISpriteRef
+
+<Badge type="info" text="Struct" />
+
+**Source:** `UISpriteRef.h`
+
+## Description
+
+Non-owning, format-tagged pointer to one sprite plus its draw
+       parameters.
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `storage` | `Storage` | The referenced sprite. |
+| `format` | `UISpriteFormat` | Live member of `storage`. |
+| `tint` | `Color` | Mono only; ignored otherwise. |
+| `paletteSlot` | `uint8_t` | 2bpp/4bpp only; ignored otherwise. |