cocoa: the live damage proof X11 and Wayland had and this backend did not

[tannevaled]

Why

Incremental present on macOS now draws only the changed rows, each run
wrapped as a bitmap of its own (#117). That makes the row arithmetic
load-bearing in a way it was not before: an off-by-one, or two bands that fail
to meet, leaves a stale line across a window that nothing later repairs,
because the framebuffer persists between frames.

The unit tests hold the arithmetic. Nothing held the pixels — TestLiveX11Damage
and TestLiveWaylandDamage exist, and there was no Cocoa counterpart.

What it does

A four-quadrant root is presented, one quadrant is changed, and only its
rectangle is presented. The window is then photographed through the window
server and the two captures are compared: the changed quadrant must have
changed, the other three must be untouched.

screencapture -l, not -cacheDisplayInRect: — that asks the view to draw
itself afresh, which is an AppKit-initiated draw, takes the whole-buffer
fallback, and would prove nothing about the banded path.

Two things said in the file rather than left to be discovered

Colours are compared between the two captures, never against the bytes that
were written. The window server colour-manages what it composites: a buffer
holding pure red photographs as (234,51,36) on this display, so absolute
colours would measure the display profile instead of the present path.

The proof's own limit, found by breaking the code on purpose. A band read
from the wrong source rows is caught. A band drawn at the wrong destination
is not: AppKit redraws the window for its own reasons between the change
and the photograph, that redraw takes the whole-buffer fallback, and it repairs
the evidence. TestBandDest and its seam case fail on that ablation, which is
where that guarantee actually lives. A live proof that heals itself is worth
saying out loud rather than trusting.

Housekeeping

Captures go through captureDir — outside any repository, somewhere durable —
which this package already had.

Gated behind darwin && integration + WINDOW_COCOA_INTEGRATION=1, like the
rest of the live suite, and it skips rather than fails if Screen Recording is
not granted.

🤖 Generated with Claude Code