Update documentation

- Update README with new examples and features
- Expand COMPOSITOR_EFFECTS.md with PreBufferPaint usage
- Update RENDERING_PIPELINE.md with buffer paint events
- Add EXAMPLES.md documenting all example applications

Author: nickprotop

README.md

@@ -574,20 +574,35 @@ windowSystem.Theme = new MyDarkTheme();
 
 ### Compositor Effects
 
-SharpConsoleUI v2.0+ exposes the rendering buffer for post-processing effects, enabling compositor-style visual enhancements:
+SharpConsoleUI v2.0+ exposes the rendering buffer for custom backgrounds and post-processing effects via `PreBufferPaint` and `PostBufferPaint` events:
 
 ```csharp
-// Apply fade-in transition effect
+// Custom animated background (renders BEFORE controls)
+public class FractalWindow : Window
+{
+    public FractalWindow(ConsoleWindowSystem windowSystem) : base(windowSystem)
+    {
+        // PreBufferPaint: fires after clear, before controls paint
+        Renderer.PreBufferPaint += (buffer, dirtyRegion, clipRect) =>
+        {
+            // Render fractal/gradient/pattern - controls appear on top
+            for (int y = 0; y < buffer.Height; y++)
+                for (int x = 0; x < buffer.Width; x++)
+                    buffer.SetCell(x, y, '█', ComputeFractalColor(x, y), Color.Black);
+        };
+    }
+}
+
+// Post-processing effect (renders AFTER controls)
 public class FadeInWindow : Window
 {
     private float _fadeProgress = 0f;
 
     public FadeInWindow(ConsoleWindowSystem windowSystem) : base(windowSystem)
     {
-        // Subscribe to post-paint event
+        // PostBufferPaint: fires after controls paint, before display
         Renderer.PostBufferPaint += (buffer, dirtyRegion, clipRect) =>
         {
-            // Manipulate buffer after painting, before display
             for (int y = 0; y < buffer.Height; y++)
             {
                 for (int x = 0; x < buffer.Width; x++)
@@ -604,8 +619,9 @@ public class FadeInWindow : Window
 ```
 
 **Use Cases:**
-- **Transitions**: Fade-in/fade-out, slide, dissolve effects
-- **Filters**: Blur, sharpen, color grading, sepia tone
+- **Custom Backgrounds**: Animated fractals, gradients, patterns (PreBufferPaint)
+- **Transitions**: Fade-in/fade-out, slide, dissolve effects (PostBufferPaint)
+- **Filters**: Blur, sharpen, color grading, sepia tone (PostBufferPaint)
 - **Overlays**: Glow effects, borders, highlights on focused controls
 - **Screenshots**: Capture immutable buffer snapshots with `buffer.CreateSnapshot()`
 - **Recording**: Frame-by-frame capture for replay or analysis

docs/COMPOSITOR_EFFECTS.md

@@ -20,7 +20,8 @@ The compositor effects system allows you to manipulate the rendered buffer **aft
 
 ### Key Features
 
-- **Post-Paint Hook**: `PostBufferPaint` event fires after painting, before ANSI conversion
+- **Pre-Paint Hook**: `PreBufferPaint` event fires after buffer clear, before controls paint (for backgrounds)
+- **Post-Paint Hook**: `PostBufferPaint` event fires after painting, before ANSI conversion (for effects)
 - **Direct Buffer Access**: Full `CharacterBuffer` API for cell-level manipulation
 - **Immutable Snapshots**: `BufferSnapshot` for safe buffer capture (screenshots, recording)
 - **Zero Overhead**: Event system has no cost when not used
@@ -40,12 +41,21 @@ Window Rendering Pipeline:
 └──────────┬──────────┘
            │
 ┌──────────▼──────────┐
+│ Buffer.Clear()      │  Clear buffer with background color
+└──────────┬──────────┘
+           │
+┌──────────▼──────────────────────┐
+│ PreBufferPaint Event Fires      │  ◄── BACKGROUNDS GO HERE
+│ (Paint backgrounds, fractals)   │      (before controls)
+└──────────┬──────────────────────┘
+           │
+┌──────────▼──────────┐
 │ PaintDOM()          │  Paint controls to CharacterBuffer
 └──────────┬──────────┘
            │
 ┌──────────▼──────────────────────┐
-│ PostBufferPaint Event Fires     │  ◄── YOUR EFFECTS GO HERE
-│ (Buffer manipulation allowed)   │
+│ PostBufferPaint Event Fires     │  ◄── EFFECTS GO HERE
+│ (Fade, blur, overlays)          │      (after controls)
 └──────────┬──────────────────────┘
            │
 ┌──────────▼──────────┐
@@ -73,25 +83,53 @@ public CharacterBuffer? Buffer { get; }
 
 **CAUTION**: Direct buffer manipulation should only be done via the `PostBufferPaint` event to avoid race conditions. Reading is safe at any time.
 
-### 3. WindowRenderer.PostBufferPaint Event
+### 3. WindowRenderer.PreBufferPaint Event
+
+Event that fires after the buffer is cleared but before controls are painted. Ideal for custom backgrounds.
+
+```csharp
+public delegate void BufferPaintDelegate(
+    CharacterBuffer buffer,
+    LayoutRect dirtyRegion,
+    LayoutRect clipRect);
+
+public event BufferPaintDelegate? PreBufferPaint;
+```
+
+**Parameters**:
+- `buffer`: The character buffer (cleared with background color)
+- `dirtyRegion`: The region being painted (or full bounds if entire buffer)
+- `clipRect`: The clipping rectangle used during paint
+
+**Use cases**:
+- Animated backgrounds (fractals, patterns)
+- Custom window backgrounds
+- Full-buffer graphics that controls render ON TOP of
+
+### 4. WindowRenderer.PostBufferPaint Event
 
 Event that fires after painting controls but before converting to ANSI strings.
 
 ```csharp
-public delegate void PostBufferPaintDelegate(
+public delegate void BufferPaintDelegate(
     CharacterBuffer buffer,
     LayoutRect dirtyRegion,
     LayoutRect clipRect);
 
-public event PostBufferPaintDelegate? PostBufferPaint;
+public event BufferPaintDelegate? PostBufferPaint;
 ```
 
 **Parameters**:
 - `buffer`: The character buffer that was just painted
 - `dirtyRegion`: The region that was painted (or full bounds if entire buffer)
 - `clipRect`: The clipping rectangle used during paint
 
-### 4. BufferSnapshot
+**Use cases**:
+- Transitions (fade in/out)
+- Filters (blur, color grading)
+- Overlays (glow, highlights)
+
+### 5. BufferSnapshot
 
 Immutable snapshot of a CharacterBuffer at a point in time.