diff --git a/docs/wiki/epaper-emulation.md b/docs/wiki/epaper-emulation.md
index 03c5bb4b..1ad3bdfa 100644
--- a/docs/wiki/epaper-emulation.md
+++ b/docs/wiki/epaper-emulation.md
@@ -1,11 +1,16 @@
 # ePaper / e-Ink emulation in Velxio
 
-Velxio emulates the SSD168x family of mono ePaper panels (Solomon Systech
-SSD1681 / SSD1675A / SSD1680 / SSD1683 + UltraChip UC817x clones). One
-component, one decoder, one Web Component — parameterised by `panelKind`.
+Velxio emulates GxEPD2-driven ePaper panels across **three controller
+families** — Solomon Systech **SSD168x** (mono + B/W/Red), UltraChip
+**UC8159c** (5.65" 7-colour ACeP) and UltraChip **UC8179 / GD7965** (7.5"
+mono) — on AVR, RP2040 and ESP32 boards. One component, one Web Component,
+parameterised by `panelKind`; the decoder is selected from the panel's
+`controllerFamily`.
 
-> Phase 1 = mono only. Tri-colour (B/W/R), 7-colour ACeP, and the user-cited
-> 13.3" Spectra 6 are roadmap items — see "Phase 2 / out of scope" below.
+> Status: every gallery example renders correctly on the boards it fits on
+> (B/W, B/W/Red, and 7-colour ACeP). See "Decoder internals" and the sections
+> after it for the rotation / paging / tri-colour / BUSY details, and
+> "Roadmap" for what's still deferred.
 
 ## Supported panels
 
@@ -20,12 +25,20 @@ component, one decoder, one Web Component — parameterised by `panelKind`.
 | `epaper-7in5-bw`   | 7.5"  | 800×480 | B/W   | UC8179 / GD7965   | ❌       | ⚠️ tight | ✅ |
 | `epaper-5in65-7c`  | 5.65" | 600×448 | **ACeP 7-colour** | **UC8159c** | ❌ flash | ⚠️ tight | ✅ |
 
-The 7-colour `epaper-5in65-7c` panel uses a **different controller family**
-(UltraChip UC8159c). The decoder lives at
-`frontend/src/simulation/displays/UC8159cDecoder.ts` and the matching
-backend slave is `Uc8159cEpaperSlave` in `esp32_spi_slaves.py`. The hook
-(`EPaperPart.ts`) picks the decoder via `cfg.controllerFamily` so the same
-component code drives all panels.
+Three of those panels use a **non-SSD168x controller** and have their own
+decoder; `EPaperPart.ts` (browser) and `esp32_worker.py` (ESP32) both pick
+the decoder from `cfg.controllerFamily`:
+
+| `controllerFamily` | Panels | Browser decoder | ESP32 worker slave |
+|---|---|---|---|
+| `ssd168x` | 1.54 / 2.13 / 2.9 / 4.2" (B/W + B/W/R) | `SSD168xDecoder.ts` | `Ssd168xEpaperSlave` |
+| `uc8159c` | 5.65" ACeP 7-colour | `UC8159cDecoder.ts` | `Uc8159cEpaperSlave` |
+| `uc8179`  | 7.5" 800×480 mono     | `Uc8179Decoder.ts`  | `Uc8179EpaperSlave`  |
+
+> The 7.5" panel was originally mislabeled `controllerFamily: 'ssd168x'`
+> and rendered **blank** — GxEPD2_750_T7 is a UC8179, whose 0x10/0x13 DTM
+> stream the SSD168x decoder ignores. Setting it to `'uc8179'` + adding the
+> decoder fixed it.
 
 "AVR ⚠️ tight" means the GxEPD2 paged build fits but Adafruit_GFX font
 selection matters; "❌" means the binary blows past 32 KB at any sane
@@ -72,11 +85,114 @@ For all three paths:
 - **Auto-RAM-window** auto-increment honours
   `0x11 DATA_ENTRY_MODE` (default 0x03 = X+, Y+, X-first).
 
+## Decoder internals (SSD168x)
+
+The SSD168x decoder is implemented **three times and they must stay
+byte-for-byte identical** — change one, change all three:
+
+- `frontend/src/simulation/displays/SSD168xDecoder.ts` (TypeScript, AVR/RP2040)
+- `backend/app/services/esp32_spi_slaves.py::Ssd168xEpaperSlave` (Python, ESP32 worker)
+- `test/test_epaper/ssd168x_decoder.py` (the Python golden reference / spec)
+
+`test_ssd168x_protocol.py` + `ssd168x-decoder.test.ts` replay the same byte
+streams through them and assert identical framebuffers.
+
+### Native-window compose, then rotate
+
+GxEPD2 pre-rotates in software (Adafruit_GFX) and writes the controller's
+**native** RAM. For a panel used in landscape via `setRotation(1)` the native
+RAM is the **transpose** of the display (e.g. a 296×128 panel's controller RAM
+is 128×296). The decoder therefore:
+
+1. Sizes RAM to the **longer side both ways** so a transposed layout isn't
+   truncated.
+2. Composes in the **native active window** (the bytes the firmware actually
+   wrote, set via `0x44`/`0x45`), then rotates to the display orientation —
+   identity when native == display, the inverse of `setRotation(1)` when
+   native == transpose. Orientation is detected by **byte width** (`nw_bytes
+   == ceil(W/8)` vs `ceil(H/8)`), because a non-multiple-of-8 native width
+   (the 2.13" panel is 122 px → padded to 128) breaks a naive pixel compare.
+
+> Limitation: the stream looks identical for rotation 0 vs 2 and 1 vs 3, so the
+> decoder can only disambiguate 0/1 (which every shipped example uses).
+
+### Paged drivers → window union
+
+GxEPD2 with `page height < panel` (`firstPage()`/`nextPage()`) writes the frame
+in horizontal strips, **setting a partial RAM window per page**. Compose must
+use the **union** of every window since the last flush (the `_win_*_set` flags
+reset on `0x20`), or only the last strip renders — the all-white-paged-panel
+bug (1.54" Uno, 4.2" Pico, 7.5" ESP32).
+
+### RAM Y-counter wraps at the window
+
+The RAM address counter **wraps at the active-window boundary** like real
+hardware. `GxEPD2_3C` (tri-colour) writes the `0x24` plane then the `0x26`
+plane **without re-seeking the counter** between them, relying on this wrap; a
+decoder that runs Y past the window end drops every `0x26` byte and the red
+layer goes white.
+
+### B/W vs B/W/Red (`is_bwr`)
+
+- **Tri-colour** (`palette: 'bwr'`): `0x26` is the additive **red** plane
+  (red wins on compose, red RAM inits to 0x00 "no red").
+- **B/W**: `0x26` is a *second mono plane* (some controllers, e.g. GDEY029T94,
+  mirror the image there) — red RAM inits to 0xFF and a pixel is white only if
+  **both** planes say white.
+
+The browser passes `isBwr = cfg.palette === 'bwr'`; the worker derives it from
+`panel_kind` containing `'bwr'`.
+
+## UltraChip decoders (UC8159c / UC8179)
+
+The UltraChip family is a different protocol from SSD168x: big register-setup
+commands during init, then a linear **DTM** image stream and a `0x12` refresh
+(the flush opcode, vs SSD168x's `0x20`).
+
+| | **UC8159c** (5.65" ACeP) | **UC8179** (7.5" mono) |
+|---|---|---|
+| Pixels | 2 px/byte, 3-bit palette (7 colours) | 8 px/byte, 1 bpp (`0xFF` = white) |
+| Image command | `0x10` DTM1 (linear, no window) | `0x13` DTM2 "current" (`0x10` = ignored "previous") |
+| Window | none — flat native raster | `0x90` partial window (9 bytes, pixel coords MSB-first), framed by `0x91`/`0x92` |
+| Rotation | none (writes native raster for any rotation) | none — data lands at absolute pixel coords in the window, so compose == RAM |
+| Refresh / flush | `0x12` | `0x12` |
+
+Both produce a `Frame` the existing `paintFrame()` renders (the UC8179 reuses
+the SSD168x 0=black / 1=white palette; the UC8159c uses `ACEP_PALETTE_RGB`).
+
+## BUSY polarity is per controller family
+
+GxEPD2 busy-waits **inside `_PowerOn()`/`_InitDisplay()`, before any frame is
+sent**, so the worker seeds the BUSY pin to the panel's *idle* level at
+registration (`esp32_worker.py`, the `_init_sensors` path):
+
+| Family | Idle level | Busy level |
+|---|:---:|:---:|
+| SSD168x | **LOW** | HIGH |
+| UltraChip (uc8159c, uc8179) | **HIGH** | LOW |
+
+Get this wrong and GxEPD2's first busy-wait never satisfies → a **10 s "Busy
+Timeout!"** on every refresh (the original 7.5" symptom). The ePaper panels
+register through the `_init_sensors` path, **not** the runtime `sensor_attach`
+twin (whose BUSY was hardcoded and whose `epaper_update` emit was the old
+double-`data` shape — both left as dead-but-fixed code).
+
+## WS plumbing (ESP32 path)
+
+The worker emits `epaper_update` events to the frontend **flat** — fields at
+the top level, NOT nested under `'data'` — because the backend's
+`qemu_callback` (`simulation.py`) re-wraps the post-`type` payload under
+`'data'`. A nested `'data'` here double-wraps, the frontend reads
+`msg.data.data.component_id` (undefined), `EPaperPart` bails on
+`id !== componentId`, and the panel **never renders** (the long-standing
+"ESP32 ePaper is blank" bug). Every other worker event is flat for the same
+reason.
+
 ## Library compatibility matrix
 
 | Library | AVR | RP2040 | ESP32 | Notes |
 |---|:---:|:---:|:---:|---|
-| **GxEPD2** (Jean-Marc Zingg) | ✅ ≤ 2.13" only | ✅ | ✅ | The de-facto Arduino library; tested against. |
+| **GxEPD2** (Jean-Marc Zingg) | ✅ (panel must fit flash) | ✅ | ✅ | The de-facto Arduino library; every example is GxEPD2 (BW / 3C / 7C). |
 | **Adafruit_EPD** | ❌ RAM | ✅ | ✅ | Should work — the SSD168x command set is identical. |
 | **ESPHome `waveshare_epaper`** | n/a | n/a | ✅ | Generates the same SPI traffic as Adafruit_EPD; tested on real hardware. |
 
@@ -94,13 +210,33 @@ that lists them in `libraries: [...]`.
    the backend SSD168x slave (`epaper_update` events arriving over the
    WebSocket), not the in-browser decoder. Same UX from the user's POV.
 
-## Phase 2 / out of scope (deliberately deferred)
+## Debugging gotchas
+
+- **ESP32 ePaper render is SLOW.** It's a per-byte SPI stream; the 7.5"
+  800×480 pushes ~96 KB/refresh and takes a while. `display.init(..., true,
+  ...)` also does an early **clear-to-white refresh first**, so the *first*
+  flush is blank — reading the canvas/log too early looks like "it renders
+  white". Wait for the image flush (the panel actually changing, or the
+  sketch's `Serial.println("frame done")`).
+- **Restart the backend between ESP32 sims.** The lcgamboa QEMU keeps
+  singleton SPI state; a second Run in the same backend can corrupt it. For a
+  clean measurement: restart backend → reload page → Run once.
+- **`controllerFamily` must match the GxEPD2 driver class.** A UC8179 /
+  UC8159c panel decoded as `ssd168x` (or vice-versa) renders blank — the
+  command sets don't overlap.
+- **Tests** (must stay green): `cd frontend && npx vitest run
+  src/__tests__/ssd168x-decoder.test.ts` (15) and `pytest test/test_epaper`
+  (23). Tri-colour cases construct the decoder with `palette: 'bwr'` /
+  `is_bwr=True`.
+
+## Roadmap (deferred)
 
 | Feature | Why not yet |
 |---|---|
 | ~~Tri-colour SSD168x (B/W/R)~~ | **✅ shipped** — `epaper-2in13-bwr`, `epaper-2in9-bwr` panel kinds. The decoder's red RAM plane (`0x26 WRITE_RED_VRAM`) was always there; we just enabled it for the SSD1680 3-colour panels. |
 | ~~UC8159c 5.65" 7-colour ACeP~~ | **✅ shipped** — `epaper-5in65-7c` panel kind. New decoder family, same hook + Web Component. |
-| Other UC81xx panels (UC8176 4.2" alt, UC8179 7.5" full driver) | The SSD168x driver covers these panels' GxEPD2 path today (those Arduino driver classes emit SSD168x-compatible traffic for B/W). Only matters if someone uses a panel whose GxEPD2 class strictly emits UC81xx commands. |
+| ~~UC8179 7.5" full driver~~ | **✅ shipped** — `epaper-7in5-bw` now uses the dedicated `Uc8179Decoder` / `Uc8179EpaperSlave` (controllerFamily `uc8179`) instead of being mis-decoded as SSD168x. |
+| Other UC81xx panels (UC8176 4.2" alt) | The SSD168x driver covers the 4.2" GxEPD2_420 path today (it emits SSD168x-compatible traffic). Only matters if someone picks a panel whose GxEPD2 class strictly emits UC81xx commands a current decoder doesn't model. |
 | **E Ink Spectra 6 13.3" 1200×1600** (Seeed [6569](https://www.seeedstudio.com/13-3inch-Six-Color-eInk-ePaper-Display-with-1200x1600-Pixels-p-6569.html)) | Reverse-engineered command set; ship after Phase 1 proves the scaffold and we can capture real SPI traces from a Seeed EE02. |
 | IT8951 Carta panels | Different protocol entirely (SPI packet stream). |
 | LUT (`0x32`) waveform validation | Accept silently; never validate. Real panels sometimes send vendor-specific LUTs that aren't worth fingerprinting. |
@@ -111,18 +247,21 @@ that lists them in `libraries: [...]`.
 
 | File | Purpose |
 |---|---|
-| `frontend/src/simulation/displays/SSD168xDecoder.ts` | TS port of the reference Python decoder |
-| `frontend/src/simulation/displays/EPaperPanels.ts`   | Per-panel geometry + controller assignments |
+| `frontend/src/simulation/displays/SSD168xDecoder.ts` | SSD168x browser decoder (TS port of the golden spec) |
+| `frontend/src/simulation/displays/UC8159cDecoder.ts` | UC8159c (5.65" ACeP 7-colour) browser decoder |
+| `frontend/src/simulation/displays/Uc8179Decoder.ts` | UC8179 (7.5" mono) browser decoder |
+| `frontend/src/simulation/displays/EPaperPanels.ts`   | Per-panel geometry + `controllerFamily` assignments |
 | `frontend/src/components/velxio-components/EPaperElement.ts` | `<velxio-epaper>` Web Component |
 | `frontend/src/components/velxio-components/EPaper.tsx` | Thin React wrapper |
-| `frontend/src/simulation/parts/EPaperPart.ts` | `attachEvents` factory — branches AVR / RP2040 / ESP32 |
-| `frontend/src/data/examples-displays-epaper.ts` | 5 gallery examples |
-| `frontend/public/components-metadata.json` | 5 picker entries (category: `displays`) |
-| `backend/app/services/esp32_spi_slaves.py` | `Ssd168xEpaperSlave` for the ESP32 path |
-| `test/test_epaper/ssd168x_decoder.py` | Reference Python decoder (the spec) |
-| `test/test_epaper/test_ssd168x_protocol.py` | 11 pure-Python protocol tests |
+| `frontend/src/simulation/parts/EPaperPart.ts` | `attachEvents` factory — branches AVR / RP2040 / ESP32 + picks the decoder by `controllerFamily` |
+| `frontend/src/data/examples-displays-epaper.ts` | gallery examples |
+| `frontend/public/components-metadata.json` | picker entries (category: `displays`) |
+| `backend/app/services/esp32_spi_slaves.py` | `Ssd168xEpaperSlave` / `Uc8159cEpaperSlave` / `Uc8179EpaperSlave` for the ESP32 path |
+| `backend/app/services/esp32_worker.py` | dispatches the slave by `controller_family`; seeds the BUSY idle level; emits `epaper_update` |
+| `test/test_epaper/ssd168x_decoder.py` | Golden Python SSD168x decoder (the spec) |
+| `test/test_epaper/test_ssd168x_protocol.py` | pure-Python protocol tests |
 | `frontend/src/__tests__/ssd168x-decoder.test.ts` | Vitest port of the same tests |
-| `test/test_epaper/sketches/` | 5 canonical "hello world" sketches |
+| `test/test_epaper/sketches/` | canonical "hello world" sketches |
 
 ## See also