# GPU headless render harness — framing + as-built

pmacs-gpu has 40 unit tests, but every one is helper/logic or
vertex-math — **none exercises the wgpu composition path**. Layout and
rendering regressions (hit-testing, dropdown clipping, minimap
projection, squiggles, selection/current-line backgrounds, status/
minibuffer composition) pass the suite silently. This is why every GPU
arc this session ended with "looks good in the GUI" — a human eyeball
was the only render gate. Audit F-014.

This arc adds the **first test that actually renders a frame** — headless
(no window), to an offscreen texture, read back to CPU for pixel
assertions.

## What the recon established

- `State` (`main.rs:321`) holds device, queue, surface, window, the
  renderers, and ~70 render-input fields. Device/queue creation is
  **separable** from window/surface (`request_device` takes no surface;
  `request_adapter` can pass `compatible_surface: None`).
- `render()` (`main.rs:3526`) renders to the surface's current texture
  view — its **only** target. Everything after the acquire uses `view` +
  `config.width/height`, so swapping in an offscreen view is localized.
- Render inputs are **plain settable fields**; `apply_attach_message` is
  the wire path, not a gate — a test can set `current_text`, spans,
  decorations, menu/minibuffer, etc. directly, no daemon.
- The one blocker: **`State` can't be built without a device + window**
  (`window`/`surface` are non-optional).

## The rule

**Q#GH1 — make the render core headless-constructible, least-invasively.**
`window: Option<Arc<Window>>` and `surface: Option<Surface>`; a
`State::new_headless(width, height)` that builds device/queue/renderers/
atlas/viewport/config with `compatible_surface: None` and no window;
promote the surface format to a `format` field on `State` (pick a fixed
renderable `Rgba8UnormSrgb` headless, shared by the offscreen texture and
all three pipelines + atlas — they must match). `request_redraw` and
`surface.configure` become `if let Some(...)`. *Not* the full
`Renderer`-sub-struct extraction the recon floated as the "clean" option
— that's hundreds of `self.device → self.renderer.device` edits; deferred
until a second consumer needs it.

**Q#GH2 — split `render()` into acquire + `render_to_view`.** Move the
body (`3543-3853`) into `render_to_view(&mut self, view: &TextureView)`;
`render()` keeps the surface acquire and calls it; a new
`render_offscreen() -> Vec<u8>` creates an `RENDER_ATTACHMENT | COPY_SRC`
texture, calls `render_to_view`, then `copy_texture_to_buffer` into a
`MAP_READ` buffer (256-byte `bytes_per_row` alignment), `map_async`, and
returns RGBA. The composition path is exercised **as-is** — the test
renders through the real `render_to_view`, not a reimplementation.

**Q#GH3 — start narrow (the audit's own guidance).** Smoke assertions,
not pixel-exact golden PNGs:
- an **empty** buffer renders the clear color (`BG`) everywhere — the
  baseline;
- with `current_text` set, **ink appears** — the frame differs from the
  empty baseline in the text region (glyphs rasterized);
- a colored decoration background paints **its** color where placed.

These catch the real regression class ("nothing renders" / "text stopped
drawing" / "a layer broke") without brittle exact-pixel goldens.

## Categorical bets

- **Exercise the real path, don't mock it.** The value is in rendering
  through the actual `render_to_view` + real renderers; a reimplemented
  mini-pipeline would test itself, not the code.
- **`Rgba8UnormSrgb` headless is representative enough.** The surface
  picks an srgb format anyway; a fixed one keeps readback deterministic.

## CI gating (decided: lavapipe now)

Headless wgpu needs an adapter and CI runners have no GPU, so the CI job
installs the Vulkan software rasterizer **lavapipe** (`mesa-vulkan-
drivers`) and points wgpu at its ICD. A dedicated **GPU Render
(headless)** job then runs `cargo test -p pmacs-gpu` — which *also*
closes a gap the recon surfaced: the workspace default member is only the
root `pmacs` package, so pmacs-gpu's tests weren't being executed in CI
at all (the clippy job builds them but never runs them). This job runs
them, render tests included.

The test still **skips gracefully** when `request_adapter` returns `None`
(log + early return) so it doesn't fail on a dev box without a working
adapter — but with lavapipe present in CI it runs for real and gates
every PR.

## Validation implication

Making `surface`/`window` optional touches `render()` and `resize()` —
the live windowed path. The headless test passing does **not** prove the
windowed frontend still renders; **that needs a human eyeball** after
this lands (attach the GUI, confirm it still draws/resizes).

## As-built

Landed as framed, via the least-invasive refactor (not the `Renderer`
extraction):

- `State.window`/`State.surface` are now `Option`; a shared
  `State::assemble(window, surface, device, queue, config, initial_text)`
  builds the window-agnostic half, called by both the windowed `new` and
  a `#[cfg(test)] new_headless(w, h, text)` that passes
  `compatible_surface: None` and returns `None` when no adapter exists.
  The stored `format` field turned out redundant with `config.format`, so
  it was dropped — `config.format` is the single source the pipelines,
  atlas, and offscreen texture share.
- `render()` split into a surface-acquire wrapper + `render_to_view(&
  TextureView)`; a `#[cfg(test)] render_offscreen()` renders through the
  same `render_to_view` into a `RENDER_ATTACHMENT | COPY_SRC` texture and
  reads it back (256-byte row alignment, `PollType::wait_indefinitely`).
  `request_redraw` became an `Option`-guarded helper across its 15 call
  sites.
- Two smoke tests through the **real** composition path: a full frame is
  non-uniform (something composited), and setting text changes the frame
  vs an empty buffer. Both pass locally on this box's AMD Vulkan adapter.
- CI: a **GPU Render (headless)** job installs `mesa-vulkan-drivers`
  (lavapipe) and runs `cargo test -p pmacs-gpu` — also the first time
  pmacs-gpu's tests run in CI at all. `PMACS_REQUIRE_GPU=1` there turns a
  missing adapter into a hard failure, so a broken lavapipe setup can't
  masquerade as a silently-skipped green.

Divergence from framing: the fixed-format `format` field was dropped as
redundant (above). No other divergence.

## Deferred (named)

- Golden-PNG comparison + a case gallery (dropdown clipped above a short
  window, minimap projection, squiggle under a glyph, resize reflow).
- The `Renderer`-sub-struct extraction, if a second headless consumer
  appears.