See what the highlights are doing: a live histogram (FR-DSP-7)

Exposure, blacks and whites were set by eye. Nothing said a highlight had
blown — the canvas shows white where a channel is at 250 and white where it is
at 255, and the difference is the whole question.

**Counted on the GPU, not on the readback.** There is a full frame sitting in
CPU memory on every canvas update right now — `AdjustPass::read_output`, the
bridge spike S1 removes — and walking it would have been thirty lines and no
shader. FR-DSP-7 states the mechanism and not just the feature: "these derive
from a GPU-side reduction into a small buffer. Per-frame CPU readback of image
data is prohibited." A histogram founded on the bridge would be correct today
and deleted by S1, and would meanwhile be the reason the bridge could not go.
What crosses the bus here is 4104 bytes whatever the image size.

The reduction tallies into workgroup memory first and merges once per
workgroup. A photograph is not noise: a clear sky puts tens of thousands of
adjacent pixels in one bin, and contending for that single global atomic
serialises the dispatch.

**On the settled frame only.** `render_now` already knows whether a gesture is
still moving — `draft` is the flag `redraw` derives from `was_coalesced` — so
the dispatch and its transfer happen once when the slider stops rather than on
each of the forty frames a drag emits. Nothing is lost: a histogram flickering
past under a finger is not a reading anyone takes. FR-DSP-7 requires exactly
this, that it not extend the FR-DSP-3 frame budget.

Luma is weighted in 8.8 fixed point — 54, 183, 19, summing to 256 exactly —
rather than in floats. Not thrift: it makes the shader's arithmetic
reproducible bit for bit, which is what lets the test below be an `assert_eq`
against a CPU count rather than a tolerance. ARCH §6.13's line about integer
state, applied where it happens to also be free.

**What the numbers were checked against.** A flat frame must put all 4096
pixels in one bin and one only. A 256-wide ramp must occupy every level with
exactly the same count, which is what catches an off-by-one in the
quantisation — a `floor` where a rounding was needed shifts the whole
photograph one bin left and looks like nothing at all. And a 101x37 frame of
seeded pseudo-random pixels — deliberately not a multiple of the 16x16
workgroup, so the edge tiles run off the image — is compared slot for slot
against a second, obvious CPU implementation. Exact equality, no tolerance.
The CPU version is a deliberate reimplementation rather than shared code: the
bugs worth catching here are ones shared code would commit identically on both
sides.

Above that, the presentation arithmetic is unit-tested headless, because it is
where a wrong answer is invisible. A histogram of the wrong shape looks exactly
as plausible as one of the right shape. So: 64 columns because it divides 256
and an uneven fold draws an even ramp as a comb; the peak excludes the end
columns, or a night scene scaled against its own black spike is a flat line
with no information in it; heights are clamped into the plot; and "0%" is kept
distinct from "<0.1%" and from "—", since an indicator reading "clipped" over
a figure reading "none" is a panel contradicting itself.

Clipping counts a *pixel* with any channel at an extreme, not a channel. Any,
because a blown red has no gradation left in it however much green and blue
still hold — and it is the saturated highlight, the sunset and the red jersey,
that clips first and recovers worst. Per pixel, because counting channels can
report 200% of a frame clipped, and a percentage above 100 is a readout nobody
trusts again.

Two affordances for it, which NFR-A11Y-3 asks for: a bar standing at the end
of the plot the tones are piling against, and a figure saying how much. Either
alone reads.

The panel sits directly under the capture metadata and above every control,
because it is what the controls are judged against. It is hand-built rather
than generated, and ARCH §4.3a is untroubled: a histogram is not an operation
— no parameters, changes nothing, answers a question rather than asking one —
and nothing in it reads a parameter out of a descriptor.

Three plot colours and a neutral luma trace join the palette. That is the
swatch's exception rather than a second one: a per-channel histogram has to
say which channel, and no achromatic treatment distinguishes red from blue, so
the hue is data exactly as the image beside it is. Held well back from full
strength for the reason the theme preamble gives.

The bounded, non-parking map wait moves out of `AdjustPass` into
`readback::await_mapping`, shared with the histogram's transfer. Thirty lines
of load-bearing reasoning about frozen interfaces and lost devices, and two
copies of it would have drifted.

The histogram describes the frame on the canvas, so it is in the output colour
space FR-DSP-7 asks for, and when zoomed it describes the visible region — a
photographer inspecting a highlight at 4x is asking about that highlight. A
device that cannot build the reduction loses the histogram and keeps the
photograph.

Still to do for FR-DSP-7: the pixel colour readout under the cursor.

324 tests pass, clippy and fmt clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

core/dr-gpu/src/adjust.rs

@@ -19,6 +19,7 @@ use std::collections::HashMap;
 use dr_pipeline::ComposedShader;
 use wgpu::util::DeviceExt;
 
+use crate::readback::await_mapping;
 use crate::{DemosaicedImage, GpuContext, GpuError};
 
 /// Leading floats the composer reserves before any operation's own uniforms:
@@ -31,18 +32,6 @@ use crate::{DemosaicedImage, GpuContext, GpuError};
 /// reads them.
 const RESERVED_FIELDS: usize = dr_pipeline::RESERVED_UNIFORM_FIELDS;
 
-/// How many non-blocking polls a readback gets before it is called failed.
-///
-/// A bound rather than a spin forever: if the device is lost the map callback
-/// never arrives, and an unbounded loop would hang the interface rather than
-/// surfacing the error. Set far above any plausible completion — the copy this
-/// waits on is milliseconds — so it is reached only when something is wrong.
-///
-/// Ungated along with `export_pixels`: an export reads pixels back in a
-/// shipping build, and the bound that stops a lost device hanging the app
-/// applies at least as much there as it does to the display bridge.
-const READBACK_POLL_LIMIT: u32 = 100_000;
-
 /// Runs composed operation chains against demosaiced images.
 pub struct AdjustPass {
     ctx: GpuContext,
@@ -399,38 +388,10 @@ impl AdjustPass {
             let _ = tx.send(r);
         });
 
-        // **Polled without blocking, then checked.**
-        //
-        // `Maintain::Wait` parks the calling thread until the GPU has finished,
-        // and this is called from the UI thread — so that park was a frozen
-        // interface for the duration of the copy (~7 ms at 4K, per the note
-        // above). `Poll` drives the same callbacks without sleeping, so the
-        // loop below stays interruptible and the mapping still completes.
-        //
-        // The bounded spin matters: a lost device would otherwise never
-        // deliver the callback and this would hang the app instead of
-        // reporting an error.
-        let mut mapped = None;
-        for _ in 0..READBACK_POLL_LIMIT {
-            // A poll error is a lost device, which is exactly the case the
-            // bounded spin exists to escape — returning here reports it
-            // immediately rather than spinning out the full limit first.
-            self.ctx
-                .device
-                .poll(wgpu::PollType::Poll)
-                .map_err(|e| GpuError::Readback(e.to_string()))?;
-            match rx.try_recv() {
-                Ok(r) => {
-                    mapped = Some(r);
-                    break;
-                }
-                Err(std::sync::mpsc::TryRecvError::Empty) => continue,
-                Err(e) => return Err(GpuError::Readback(e.to_string())),
-            }
-        }
-        mapped
-            .ok_or_else(|| GpuError::Readback("readback did not complete".into()))?
-            .map_err(|e| GpuError::Readback(e.to_string()))?;
+        // Polled rather than parked, and bounded rather than spun forever —
+        // see `readback::await_mapping`, which the histogram's own transfer
+        // shares for exactly the same reasons.
+        await_mapping(&self.ctx, &rx)?;
 
         let data = slice.get_mapped_range();
         let mut out = Vec::with_capacity((unpadded * h) as usize);