From e2fb62bd7b50578760cf899d5b1453f15d24fe8a Mon Sep 17 00:00:00 2001
From: P S Kesavan <pskeshu@gmail.com>
Date: Fri, 4 Sep 2026 07:42:15 +0530
Subject: [PATCH 1/2] feat(devices): read-only dump of a device's Micro-Manager
 properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`GET /api/devices/properties?device=<label>`, or no device for the list.

Gently models four properties on the Coherent Scientific Remote — the per-line
`PowerSetpoint (%)` — because those are the four it writes. The adapter exposes
many more, and among them are the ones that answer whether a laser is actually
emitting: enable state, interlock, faults, power readback. None of that is
reachable today, so #106 has been argued from what the code commands rather
than from what the hardware reports.

That gap matters most when nobody can look at the instrument. The operator is
working on this microscope remotely: a camera can only report photons that
reach it, which needs the specimen in focus, and the light-sheet view is
exactly the surface that cannot be judged out of focus. The controller can
report its own state regardless of any of that.

Each property comes back with its value, its allowed values where the adapter
declares them, and a `read_only` flag. The allowed set turns an opaque string
into a state machine you can reason about, and read-only marks a readback
rather than a setting — which is precisely the distinction #106 turns on.

No `require_control`: it commands nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 gently/hardware/dispim/client.py       | 10 +++++
 gently/hardware/dispim/device_layer.py | 62 ++++++++++++++++++++++++++
 gently/ui/web/routes/data.py           | 17 +++++++
 3 files changed, 89 insertions(+)

diff --git a/gently/hardware/dispim/client.py b/gently/hardware/dispim/client.py
index e1597004..940bc172 100644
--- a/gently/hardware/dispim/client.py
+++ b/gently/hardware/dispim/client.py
@@ -819,6 +819,16 @@ async def get_laser_power(self, wavelength: int) -> dict:
         except Exception as e:
             return {"success": False, "error": str(e)}
 
+    async def get_properties(self, device: str | None = None) -> dict:
+        """Every property of one Micro-Manager device, or the device list.
+
+        Read-only. Asks the hardware what it reports about itself rather than
+        what this codebase models — the difference that matters when no one can
+        look at the instrument.
+        """
+        suffix = f"?device={device}" if device else ""
+        return await self._api_get(f"/api/properties{suffix}")
+
     async def get_beam(self) -> dict:
         """Read whether the beam is armed, per side, from the hardware.
 
diff --git a/gently/hardware/dispim/device_layer.py b/gently/hardware/dispim/device_layer.py
index c428ee44..94db4c5f 100644
--- a/gently/hardware/dispim/device_layer.py
+++ b/gently/hardware/dispim/device_layer.py
@@ -2443,6 +2443,67 @@ def _read_beam(self) -> dict:
                 out[side] = None
         return out
 
+    async def handle_get_properties(self, request):
+        """GET /api/properties?device=<label> — every property of one device.
+
+        Read-only, and the read is the point: it asks the hardware what it says
+        about itself, rather than what this codebase happens to model. Gently
+        knows four properties on the Coherent Scientific Remote — the per-line
+        `PowerSetpoint (%)` — because those are the ones it writes. The adapter
+        exposes many more, and among them are the ones that answer whether a
+        laser is actually emitting: enable state, interlock, faults, power
+        readback.
+
+        That matters when nobody can look at the instrument. A camera can only
+        report photons that reach it, which needs the specimen in focus; the
+        controller can report its own state regardless.
+
+        With no `device`, lists the loaded device labels.
+        """
+        try:
+            label = request.query.get("device")
+            core = None
+            for dev in self.devices.values():
+                core = getattr(dev, "core", None)
+                if core is not None:
+                    break
+            if core is None:
+                return web.json_response(
+                    {"success": False, "error": "no core available"}, status=503
+                )
+
+            if not label:
+                return web.json_response(
+                    {"success": True, "devices": sorted(core.getLoadedDevices())}
+                )
+
+            if label not in set(core.getLoadedDevices()):
+                return web.json_response(
+                    {"success": False, "error": f"unknown device {label!r}"}, status=404
+                )
+
+            props = {}
+            for name in core.getDevicePropertyNames(label):
+                try:
+                    entry: dict[str, Any] = {"value": core.getProperty(label, name)}
+                    # Allowed values turn an opaque string into a state machine
+                    # you can reason about; read-only marks what is a readback
+                    # rather than a setting, which is exactly the distinction
+                    # being chased here.
+                    allowed = list(core.getAllowedPropertyValues(label, name))
+                    if allowed:
+                        entry["allowed"] = allowed
+                    if core.isPropertyReadOnly(label, name):
+                        entry["read_only"] = True
+                    props[name] = entry
+                except Exception as exc:
+                    props[name] = {"error": str(exc)}
+
+            return web.json_response({"success": True, "device": label, "properties": props})
+        except Exception as exc:
+            logger.exception("[properties] read failed")
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
     async def handle_get_beam(self, request):
         """GET /api/scanner/beam — is the beam armed, per side, from hardware."""
         try:
@@ -3833,6 +3894,7 @@ async def on_start(self):
         self._app.router.add_post("/api/spim/fdrive/nudge", self.handle_nudge_fdrive)
         self._app.router.add_post("/api/light_source/power", self.handle_set_light_source_power)
         self._app.router.add_get("/api/light_source/power", self.handle_get_light_source_power)
+        self._app.router.add_get("/api/properties", self.handle_get_properties)
         self._app.router.add_get("/api/scanner/beam", self.handle_get_beam)
         self._app.router.add_post("/api/scanner/beam", self.handle_set_beam)
         self._app.router.add_post("/api/laser/config", self.handle_set_laser_config)
diff --git a/gently/ui/web/routes/data.py b/gently/ui/web/routes/data.py
index b9bebfb1..f0ed9a0b 100644
--- a/gently/ui/web/routes/data.py
+++ b/gently/ui/web/routes/data.py
@@ -820,6 +820,23 @@ async def laser_off():
             logger.exception("Laser off command failed")
             raise HTTPException(status_code=502, detail=f"laser off failed: {exc}") from exc
 
+    @router.get("/api/devices/properties")
+    async def device_properties(device: str | None = None):
+        """Every Micro-Manager property of one device, or the device list.
+
+        Read-only diagnostic. No `require_control`: it commands nothing, and it
+        is most needed exactly when someone is trying to work out what the
+        hardware is doing without being able to look at it.
+        """
+        client = _resolve_client()
+        if client is None or not client.is_connected:
+            raise HTTPException(status_code=503, detail="Microscope not connected")
+        try:
+            return await client.get_properties(device)
+        except Exception as exc:
+            logger.exception("Device property read failed")
+            raise HTTPException(status_code=502, detail=f"property read failed: {exc}") from exc
+
     @router.get("/api/devices/beam")
     async def beam_get():
         """Is the beam armed, per side? Read from hardware. Read-only route."""

From 4ed9c2f8219cbc7a42a76913134f908b1100dbf4 Mon Sep 17 00:00:00 2001
From: P S Kesavan <pskeshu@gmail.com>
Date: Fri, 4 Sep 2026 07:50:03 +0530
Subject: [PATCH 2/2] feat(ui): the display range becomes a histogram panel
 under the frame
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things were wrong with the control this replaces, and the operator named
both: the contrast adjustment sat on top of the image, and the image is the
main thing anyone interacts with.

## Nothing sits on the pixels

The controls moved out of the frame into a panel attached beneath it. An
overlay hides data, and this one also swallowed clicks in the bottom strip of
the image — a cost I had already had to write off as a `ponytail:` note, which
was the tell that it was in the wrong place.

`ImageView.attach(id, { controlsHost })` takes an external host. The zoom badge
stays over the frame, because it reports the view rather than controlling it.

## The artefact is the status

Modelled on ImageJ/Fiji's Brightness/Contrast, which every microscopist already
knows. Its insight is that the histogram and the mapping belong in one picture:
the transfer line is drawn across the data it applies to, so where black and
white fall relative to where the signal actually sits is a single glance. B&C
carries no numeric status readout, and neither does this — the operator's own
suggestion, and it is right.

Counts are on a log axis. A microscopy histogram is dominated by background,
and on a linear axis the part that matters is a flat line along zero.

Auto takes the 0.1st and 99.9th percentiles, not min and max: a handful of hot
pixels must not define white.

The histogram is computed client-side by drawing the frame to an offscreen
canvas and binning it — no new endpoint, no new traffic. Throttled to 400ms,
because the frame rate is far above what an eye needs from a histogram and each
pass is a full readback of the decoded image.

## What it is honest about

It is a histogram of the frame AS DISPLAYED: 8-bit, already percentile-stretched
per frame by the device layer before JPEG encoding. Not raw camera counts. The
panel says so, and the label carries the explanation.

That is not a limitation to hide, it is the argument for #149. Anything the
server-side stretch clipped is already gone, and this panel is what will make
that visible — nuclei jammed against the top of the range are now something an
operator can see rather than something I inferred from reading the encoder.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 gently/ui/web/static/css/operate.css        | 180 ++++++--------
 gently/ui/web/static/js/operate.js          |   4 +-
 gently/ui/web/static/js/panels/imageview.js | 249 +++++++++++++++-----
 gently/ui/web/templates/index.html          |   4 +
 4 files changed, 267 insertions(+), 170 deletions(-)

diff --git a/gently/ui/web/static/css/operate.css b/gently/ui/web/static/css/operate.css
index 8881d948..ee9192aa 100644
--- a/gently/ui/web/static/css/operate.css
+++ b/gently/ui/web/static/css/operate.css
@@ -871,114 +871,6 @@
    a containing block for it. */
 .op-cam { position: relative; }
 
-/* Contrast/brightness strip — fades in on hover or keyboard focus. The
-   video-player idiom: discoverable, nothing to open or close, and gone while
-   you are just watching the frame. */
-.iv-bar {
-    position: absolute;
-    left: 6px;
-    right: 6px;
-    bottom: 6px;
-    display: flex;
-    align-items: center;
-    gap: 10px;
-    padding: 4px 8px;
-    border-radius: 5px;
-    background: rgba(0, 0, 0, 0.55);
-    opacity: 0;
-    transition: opacity 0.15s ease;
-    pointer-events: none;
-}
-
-.op-cam:hover .iv-bar,
-.iv-bar:focus-within {
-    opacity: 1;
-    pointer-events: auto;
-}
-
-@media (prefers-reduced-motion: reduce) {
-    .iv-bar { transition: none; }
-}
-
-/* Display window: one track, a black point and a white point. The lit span
-   between them is the range being mapped to the full output. */
-.iv-lbl {
-    flex: 0 0 auto;
-    font-size: 0.62rem;
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: rgba(255, 255, 255, 0.65);
-}
-
-.iv-win {
-    position: relative;
-    flex: 1 1 auto;
-    min-width: 70px;
-    height: 18px;
-    touch-action: none;      /* the handles own the gesture */
-    cursor: ew-resize;
-}
-
-.iv-win-track {
-    position: absolute;
-    inset: 7px 0 auto 0;
-    height: 4px;
-    border-radius: 2px;
-    /* black-to-white, because that is literally the axis being windowed */
-    background: linear-gradient(90deg, #000, #fff);
-    outline: 1px solid rgba(255, 255, 255, 0.25);
-}
-
-.iv-win-span {
-    position: absolute;
-    top: 6px;
-    height: 6px;
-    border-radius: 3px;
-    background: rgba(96, 165, 250, 0.55);
-    pointer-events: none;
-}
-
-.iv-win-h {
-    position: absolute;
-    top: 2px;
-    width: 10px;
-    height: 14px;
-    margin-left: -5px;
-    border-radius: 2px;
-    background: #fff;
-    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.7);
-    cursor: ew-resize;
-}
-
-.iv-win-h:focus-visible {
-    outline: 2px solid var(--accent, #3b82f6);
-    outline-offset: 1px;
-}
-
-/* Numbers only once the window is not full — a permanent "0–100" is a label
-   reporting that nothing has been changed. */
-.iv-read {
-    flex: 0 0 auto;
-    min-width: 42px;
-    font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
-    font-size: 0.64rem;
-    color: #fff;
-    text-align: right;
-}
-
-.iv-reset {
-    flex: 0 0 auto;
-    font-size: 0.64rem;
-    padding: 1px 6px;
-    border: 1px solid rgba(255, 255, 255, 0.4);
-    border-radius: 3px;
-    background: transparent;
-    color: #fff;
-    cursor: pointer;
-}
-
-/* The zoom badge shares the corner with the strip; lift it clear on hover. */
-.op-cam:hover .iv-badge { bottom: 34px; }
 
 /* ── Marking panel ────────────────────────────────────────────────────────
    Two counts side by side, because they are two different facts and showing
@@ -1053,3 +945,75 @@
     grid-column: 1 / -1;
     margin: 0;
 }
+
+/* ── Display panel ────────────────────────────────────────────────────────
+   A histogram with the transfer line drawn across it, after ImageJ/Fiji's
+   Brightness/Contrast. It sits UNDER the frame, never over it: the image is
+   the instrument, and an overlay both hides data and swallows clicks meant
+   for markers. The picture is the readout, so there is no numeric status. */
+.op-block-display .lp-head {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+}
+
+/* Says what the histogram is of, because it is not raw camera counts. */
+.iv-src {
+    font-size: 0.62rem;
+    color: var(--op-ink-dim);
+    cursor: help;
+}
+
+.iv-hist {
+    position: relative;
+    height: 60px;
+    margin-bottom: 10px;
+    border-radius: 3px;
+    /* Black-to-white behind the bars: the axis being windowed, made literal. */
+    background: linear-gradient(90deg, #0b0f14, #2b3441);
+    outline: 1px solid var(--op-rule);
+    touch-action: none;
+    cursor: ew-resize;
+}
+
+.iv-hist-c {
+    display: block;
+    width: 100%;
+    height: 100%;
+}
+
+.iv-h {
+    position: absolute;
+    top: -3px;
+    bottom: -6px;
+    width: 2px;
+    margin-left: -1px;
+    background: #60a5fa;
+    cursor: ew-resize;
+}
+
+/* A grip at the foot, so the handle is grabbable without hiding the data. */
+.iv-h::after {
+    content: '';
+    position: absolute;
+    left: -4px;
+    bottom: -1px;
+    width: 10px;
+    height: 8px;
+    border-radius: 2px;
+    background: #60a5fa;
+}
+
+.iv-h-lo::after { border-bottom-left-radius: 0; }
+.iv-h-hi::after { border-bottom-right-radius: 0; }
+
+.iv-h:focus-visible {
+    outline: 2px solid var(--accent, #3b82f6);
+    outline-offset: 2px;
+}
+
+.iv-acts {
+    display: flex;
+    gap: 6px;
+    justify-content: flex-end;
+}
diff --git a/gently/ui/web/static/js/operate.js b/gently/ui/web/static/js/operate.js
index eec59985..a468f93c 100644
--- a/gently/ui/web/static/js/operate.js
+++ b/gently/ui/web/static/js/operate.js
@@ -1295,8 +1295,8 @@ const OperateManager = (function () {
     // magnification.
     function attachImageViews() {
         if (typeof ImageView === 'undefined') return;
-        ImageView.attach('op-cam-bottom');
-        ImageView.attach('op-cam-spim');
+        ImageView.attach('op-cam-bottom', { controlsHost: 'op-display-bottom' });
+        ImageView.attach('op-cam-spim', { controlsHost: 'op-display-spim' });
     }
 
     let _lightMounted = false;
diff --git a/gently/ui/web/static/js/panels/imageview.js b/gently/ui/web/static/js/panels/imageview.js
index 84a0b840..2f703fd6 100644
--- a/gently/ui/web/static/js/panels/imageview.js
+++ b/gently/ui/web/static/js/panels/imageview.js
@@ -42,7 +42,7 @@ const ImageView = (() => {
 
     const views = new Map();   // containerId -> {z, tx, ty, fit, badge}
 
-    function attach(containerId) {
+    function attach(containerId, opts) {
         if (views.has(containerId)) return;
         const box = document.getElementById(containerId);
         if (!box) return;
@@ -50,7 +50,8 @@ const ImageView = (() => {
         if (!fit) return;
 
         const v = { z: 1, tx: 0, ty: 0, fit, box, badge: null, drag: null,
-                    lo: 0, hi: 1, bar: null, filterId: `iv-win-${containerId}` };
+                    lo: 0, hi: 1, panel: null, hist: null,
+                    filterId: `iv-win-${containerId}` };
         views.set(containerId, v);
 
         // Zoom about the cursor, so the thing under the pointer stays under it.
@@ -127,95 +128,224 @@ const ImageView = (() => {
         // uses (PANELS.md rule 6 — nothing to open or close).
         box.addEventListener('dblclick', e => { e.preventDefault(); reset(containerId); });
 
-        buildBar(v, containerId);
+        // Controls go in a host OUTSIDE the frame. Nothing sits on the pixels:
+        // the image is the instrument, and an overlay both hides data and eats
+        // clicks meant for markers.
+        const host = opts && opts.controlsHost && document.getElementById(opts.controlsHost);
+        if (host) buildPanel(v, containerId, host);
         apply(v);
     }
 
     /**
-     * The display window: a black point and a white point on one track.
+     * The display panel: a histogram with the transfer line drawn across it.
      *
-     * This replaced two abstract "contrast" and "brightness" sliders. Those are
-     * not how anyone reading a microscope image thinks — a microscopist sets a
-     * display range, the way ImageJ's Brightness/Contrast or Micro-Manager's
-     * histogram does, and asking them to reach that through two multiplicative
-     * knobs is arithmetic homework.
+     * Modelled on ImageJ/Fiji's Brightness/Contrast, which is the tool every
+     * microscopist already knows. Its insight is that the histogram and the
+     * mapping belong in one picture: you see where the data actually sits, and
+     * you see the line that decides what black and white mean, together. That
+     * is why B&C needs no numeric status readout — the artefact is the status.
+     *
+     * Two abstract "contrast" and "brightness" sliders were the opposite of
+     * this: they asked the operator to guess where the data was and then reach
+     * it through multiplication.
      *
      * It also cannot be done with CSS. `brightness()` and `contrast()` are both
      * multiplicative about their own origin, so composing them gives
-     * `out = in·b·c + k` where k is pinned by c — there is no free intercept,
-     * and an arbitrary window needs one. An SVG feComponentTransfer with
-     * type="linear" has slope AND intercept, so it maps the window exactly:
+     * `out = in·b·c + k` with k pinned by c — no free intercept, and a window
+     * needs one. An SVG feComponentTransfer with type="linear" has slope AND
+     * intercept, so it maps the window exactly:
      *
      *     out = (in - lo) / (hi - lo)   →   slope = 1/(hi-lo), intercept = -lo·slope
      *
      * `color-interpolation-filters="sRGB"` matters: the SVG default is
-     * linearRGB, which would silently apply a gamma the operator did not ask
-     * for and make the readout a lie.
+     * linearRGB, which would apply a gamma the operator did not ask for.
+     *
+     * The histogram is of the frame as displayed, which is 8-bit and already
+     * percentile-stretched by the device layer before JPEG encoding. It is not
+     * raw camera counts, and it is labelled as such — the honest fix for that
+     * is #149, and this panel is what will make the case visible.
      */
-    function buildBar(v, containerId) {
+    function buildPanel(v, containerId, host) {
         ensureFilter(v);
 
-        const bar = document.createElement('div');
-        bar.className = 'iv-bar';
-        bar.innerHTML = `
-          <span class="iv-lbl">display</span>
-          <div class="iv-win" data-win tabindex="0" role="group"
-               aria-label="Display range: black point and white point">
-            <div class="iv-win-track"></div>
-            <div class="iv-win-span" data-span></div>
-            <div class="iv-win-h iv-win-lo" data-h="lo" role="slider" tabindex="0"
-                 aria-label="Black point" aria-valuemin="0" aria-valuemax="100"></div>
-            <div class="iv-win-h iv-win-hi" data-h="hi" role="slider" tabindex="0"
-                 aria-label="White point" aria-valuemin="0" aria-valuemax="100"></div>
-          </div>
-          <span class="iv-read" data-read></span>
-          <button type="button" class="iv-reset" title="Reset zoom and display range">reset</button>`;
-
-        ['pointerdown', 'pointerup', 'click', 'dblclick', 'wheel'].forEach(ev =>
-            bar.addEventListener(ev, e => e.stopPropagation()));
-
-        const win = bar.querySelector('[data-win]');
+        host.innerHTML = `
+          <div class="lp">
+            <div class="lp-head">
+              <span class="lp-title">Display</span>
+              <span class="iv-src" title="Histogram of the displayed 8-bit frame, which the device layer has already percentile-stretched. Not raw camera counts (#149).">as displayed</span>
+            </div>
+            <div class="iv-hist" data-hist>
+              <canvas class="iv-hist-c" data-hist-c width="512" height="96"></canvas>
+              <div class="iv-h iv-h-lo" data-h="lo" role="slider" tabindex="0"
+                   aria-label="Black point" aria-valuemin="0" aria-valuemax="100"></div>
+              <div class="iv-h iv-h-hi" data-h="hi" role="slider" tabindex="0"
+                   aria-label="White point" aria-valuemin="0" aria-valuemax="100"></div>
+            </div>
+            <div class="iv-acts">
+              <button type="button" class="lp-btn" data-auto>Auto</button>
+              <button type="button" class="lp-btn" data-reset>Reset</button>
+            </div>
+          </div>`;
+
+        const hist = host.querySelector('[data-hist]');
         let dragging = null;
-
         const fromX = clientX => {
-            const r = win.getBoundingClientRect();
+            const r = hist.getBoundingClientRect();
             return Math.min(1, Math.max(0, (clientX - r.left) / Math.max(1, r.width)));
         };
 
-        win.addEventListener('pointerdown', e => {
+        hist.addEventListener('pointerdown', e => {
             const h = e.target.closest('[data-h]');
-            // Grab the nearer handle when the track itself is pressed, so the
-            // operator does not have to hit an 8 px target.
             const at = fromX(e.clientX);
+            // Grab the nearer handle when the histogram itself is pressed, so
+            // the operator does not have to hit an 8 px target.
             dragging = h ? h.dataset.h
                 : (Math.abs(at - v.lo) <= Math.abs(at - v.hi) ? 'lo' : 'hi');
             moveHandle(v, dragging, at);
-            win.setPointerCapture(e.pointerId);
+            hist.setPointerCapture(e.pointerId);
         });
-        win.addEventListener('pointermove', e => {
-            if (!dragging) return;
-            moveHandle(v, dragging, fromX(e.clientX));
+        hist.addEventListener('pointermove', e => {
+            if (dragging) moveHandle(v, dragging, fromX(e.clientX));
         });
-        win.addEventListener('pointerup', e => {
+        hist.addEventListener('pointerup', e => {
             dragging = null;
-            try { win.releasePointerCapture(e.pointerId); } catch (_) { /* fine */ }
+            try { hist.releasePointerCapture(e.pointerId); } catch (_) { /* fine */ }
         });
-
-        // Keyboard: the window is a real control, not a mouse-only flourish.
-        win.addEventListener('keydown', e => {
+        hist.addEventListener('keydown', e => {
             const step = e.shiftKey ? 0.10 : 0.02;
             const which = (document.activeElement && document.activeElement.dataset.h) || 'hi';
             if (e.key === 'ArrowLeft') { moveHandle(v, which, v[which] - step); e.preventDefault(); }
             else if (e.key === 'ArrowRight') { moveHandle(v, which, v[which] + step); e.preventDefault(); }
         });
 
-        bar.querySelector('.iv-reset').addEventListener('click', () => {
+        host.querySelector('[data-auto]').addEventListener('click', () => autoWindow(v));
+        host.querySelector('[data-reset]').addEventListener('click', () => {
             v.lo = 0; v.hi = 1;
             reset(containerId);
         });
 
-        v.bar = bar;
-        v.box.appendChild(bar);
+        v.panel = host;
+        // Frames stream, so recompute on arrival but not on every one.
+        const img = v.fit.querySelector('.op-cam-img');
+        if (img) img.addEventListener('load', () => scheduleHistogram(v));
+        scheduleHistogram(v);
+    }
+
+    /* ── histogram ───────────────────────────────────────────────────────── */
+
+    // RIG-NOTE: 400ms between recomputes. The frame rate is higher than any eye
+    // needs from a histogram, and each pass is a full readback of the decoded
+    // image. Lower it if the histogram feels laggy while hunting focus.
+    const HIST_MS = 400;
+    let histTimer = null;
+    let histPending = null;
+
+    function scheduleHistogram(v) {
+        histPending = v;
+        if (histTimer) return;
+        histTimer = setTimeout(() => {
+            histTimer = null;
+            const target = histPending;
+            histPending = null;
+            if (target) computeHistogram(target);
+        }, HIST_MS);
+    }
+
+    function computeHistogram(v) {
+        const img = v.fit.querySelector('.op-cam-img');
+        if (!img || !img.naturalWidth) { v.hist = null; drawHistogram(v); return; }
+        try {
+            // Downsampled: a histogram does not need every pixel, and reading
+            // back a full frame every 400ms would be the expensive part.
+            const W = 256, H = Math.max(1, Math.round(256 * img.naturalHeight / img.naturalWidth));
+            const c = histCanvas(W, H);
+            const ctx = c.getContext('2d', { willReadFrequently: true });
+            ctx.drawImage(img, 0, 0, W, H);
+            const d = ctx.getImageData(0, 0, W, H).data;
+            const bins = new Uint32Array(256);
+            for (let i = 0; i < d.length; i += 4) {
+                // Rec. 601 luma. The frames are greyscale, so any channel would
+                // do, but this stays right if a colour overlay ever arrives.
+                bins[(d[i] * 77 + d[i + 1] * 150 + d[i + 2] * 29) >> 8]++;
+            }
+            v.hist = bins;
+        } catch (_) {
+            v.hist = null;      // tainted or not yet decodable
+        }
+        drawHistogram(v);
+    }
+
+    let _histCanvas = null;
+    function histCanvas(w, h) {
+        if (!_histCanvas) _histCanvas = document.createElement('canvas');
+        if (_histCanvas.width !== w || _histCanvas.height !== h) {
+            _histCanvas.width = w; _histCanvas.height = h;
+        }
+        return _histCanvas;
+    }
+
+    function drawHistogram(v) {
+        if (!v.panel) return;
+        const c = v.panel.querySelector('[data-hist-c]');
+        if (!c) return;
+        const ctx = c.getContext('2d');
+        const W = c.width, H = c.height;
+        ctx.clearRect(0, 0, W, H);
+
+        if (v.hist) {
+            // Log counts: a microscopy histogram is dominated by background, and
+            // on a linear axis the signal that matters is a flat line at zero.
+            let max = 0;
+            for (let i = 0; i < 256; i++) max = Math.max(max, v.hist[i]);
+            const norm = Math.log1p(max) || 1;
+            ctx.fillStyle = 'rgba(255,255,255,0.55)';
+            for (let i = 0; i < 256; i++) {
+                const h = (Math.log1p(v.hist[i]) / norm) * (H - 2);
+                if (h > 0) ctx.fillRect((i / 256) * W, H - h, Math.ceil(W / 256), h);
+            }
+        } else {
+            ctx.fillStyle = 'rgba(255,255,255,0.25)';
+            ctx.font = '11px system-ui, sans-serif';
+            ctx.fillText('no frame', 6, H / 2);
+        }
+
+        // The transfer line: what black and white currently mean, drawn over the
+        // data it applies to. This is the readout — ImageJ's B&C insight.
+        ctx.strokeStyle = 'rgba(96,165,250,0.95)';
+        ctx.lineWidth = 1.5;
+        ctx.beginPath();
+        ctx.moveTo(0, H - 1);
+        ctx.lineTo(v.lo * W, H - 1);
+        ctx.lineTo(v.hi * W, 1);
+        ctx.lineTo(W, 1);
+        ctx.stroke();
+    }
+
+    /**
+     * Auto: put the window around the data actually present.
+     *
+     * The 0.1st and 99.9th percentiles of the displayed histogram, not min/max
+     * — a handful of hot pixels should not define white.
+     */
+    function autoWindow(v) {
+        if (!v.hist) return;
+        let total = 0;
+        for (let i = 0; i < 256; i++) total += v.hist[i];
+        if (!total) return;
+        const lowCut = total * 0.001, highCut = total * 0.999;
+        let acc = 0, lo = 0, hi = 255;
+        for (let i = 0; i < 256; i++) {
+            acc += v.hist[i];
+            if (acc >= lowCut) { lo = i; break; }
+        }
+        acc = 0;
+        for (let i = 0; i < 256; i++) {
+            acc += v.hist[i];
+            if (acc >= highCut) { hi = i; break; }
+        }
+        v.lo = lo / 255;
+        v.hi = Math.max(v.lo + MIN_SPAN, hi / 255);
+        apply(v);
     }
 
     // Handles cannot cross, and cannot meet: hi === lo is an infinite slope.
@@ -274,16 +404,14 @@ const ImageView = (() => {
             });
         }
 
-        if (!v.bar) return;
-        const lo = v.bar.querySelector('[data-h="lo"]');
-        const hi = v.bar.querySelector('[data-h="hi"]');
-        const span = v.bar.querySelector('[data-span]');
-        const read = v.bar.querySelector('[data-read]');
+        if (!v.panel) return;
+        // The handles are the only numeric readout there is, and the transfer
+        // line over the histogram is the rest — ImageJ's B&C carries no status
+        // text either, because the picture already says it.
+        const lo = v.panel.querySelector('[data-h="lo"]');
+        const hi = v.panel.querySelector('[data-h="hi"]');
         if (lo) { lo.style.left = `${v.lo * 100}%`; lo.setAttribute('aria-valuenow', Math.round(v.lo * 100)); }
         if (hi) { hi.style.left = `${v.hi * 100}%`; hi.setAttribute('aria-valuenow', Math.round(v.hi * 100)); }
-        if (span) { span.style.left = `${v.lo * 100}%`; span.style.right = `${(1 - v.hi) * 100}%`; }
-        // Presence-driven: the numbers appear only once the window is not full.
-        if (read) read.textContent = wide ? '' : `${Math.round(v.lo * 100)}–${Math.round(v.hi * 100)}`;
     }
 
     const clamp = z => Math.min(MAX_Z, Math.max(MIN_Z, z));
@@ -295,6 +423,7 @@ const ImageView = (() => {
         // On the <img>, not the fit box: the marker canvas is a sibling inside
         // it and must NOT be filtered, or green markers dim with the frame.
         applyWindow(v);
+        drawHistogram(v);
         v.box.style.cursor = v.z > 1 ? 'grab' : '';
         badge(v);
     }
diff --git a/gently/ui/web/templates/index.html b/gently/ui/web/templates/index.html
index 455d9b2c..96cf0693 100644
--- a/gently/ui/web/templates/index.html
+++ b/gently/ui/web/templates/index.html
@@ -579,6 +579,9 @@ <h2 class="devices-title"><span class="devices-title-script">Device</span> <em c
                     <div class="op-bar">
                       <span class="op-cap" id="op-mark-hint">Click to mark · click a marker to remove · click a registered embryo to centre on it</span>
                     </div>
+                    <!-- Display range, attached under the frame it applies to.
+                         Nothing sits on the pixels. -->
+                    <div class="op-block op-block-display" id="op-display-bottom"></div>
                     <!-- Marking sits under the frame it acts on, not off in the
                          instrument rail. Shared panel; the module owns its
                          markup (docs/architecture/PANELS.md). -->
@@ -642,6 +645,7 @@ <h2 class="devices-title"><span class="devices-title-script">Device</span> <em c
                     <!-- Seats itself while a routine is producing images and retires
                          when they stop. No open or close control on purpose: an
                          operator watching the scope should not have to ask for it. -->
+                    <div class="op-block op-block-display" id="op-display-spim"></div>
                     <figure class="op-preview" id="op-preview" hidden>
                       <img class="op-preview-img" id="op-preview-img" alt="Focus sweep preview">
                       <figcaption class="op-preview-cap">