web: repair dust with a brush that borrows a patch of the same photo

A sensor speck is not a filter: it is a small lie in one place, and every
slider in the panel is global, so there was no way to say "here, and only
here". The FX row now has a HEAL chip. Arming it turns the pointer into a
circle you can size S, M or L, and every click on a speck covers it with a
patch of skin borrowed from a few radii away — the repaired sites persist in
the recipe like any other edit, and UNDO takes them back one click at a time.

The spot is stored in the rendered photo's fractions, not in the preview's
pixels: x, y and a radius that is a fraction of the photo's WIDTH, so the
circle stays round on a tall or a square frame and the same recipe heals at
preview resolution and at export resolution without a second code path.
`readHeal` is the only door in, and it validates, clamps and drops the spots
with no radius before anything downstream sees them.

The source patch is searched for, not asked for. `findHealSource` walks eight
directions at three distances — 2.6r, 4.2r, 6.5r — and each candidate's mirror
through the spot as well, scores every one with a nine-tap comparison of the
neighbourhood, and hands back the first that actually resembles the ring around
the speck. When nothing fits — a brush wide enough to swallow the whole frame —
it returns null and the click is refused rather than smearing a wrong colour
over it. There is no colour-matching model here and no second draggable source
circle: Lightroom lets you place the donor, this finds one.

The pass runs last on the photo's own pixels. It is inserted after the grade,
the curve and the grain and before the frame, so the patch it pastes is copied
from pixels that have already been graded and grained — it matches by
construction, with no second copy of the pipeline to keep in step — and the
frame, the card and the watermarks are drawn over the result, so healing can
never erase the furniture of the render. The brush is a feathered circle at
0.55r, which is what keeps a repair from reading as a sticker.

SkSL indexes a uniform array by a constant only, so the shader is the block
unrolled HEAL_MAX = 16 times, the same trick the tone curve's mixer already
uses. Sixteen is the ceiling and the oldest spot falls out when the
seventeenth arrives. CLEAR drops the whole field — turning the chip off keeps
the repairs, which is the distinction between disarming the brush and undoing
the work.

Verified:
  heal-skia-lab.cjs (scratchpad, Node + the full CanvasKit build) — 15 PASS,
    0 FAIL: HEAL_SKSL compiles through RuntimeEffect.Make and
    makeShaderWithChildren; the uniform block is 132 floats in declaration
    order (16 spots + 16 sources + size, w/h/feather); a dust speck pinned on
    the canvas comes back as the borrowed patch while the rest of the frame is
    untouched, pixel for pixel; readHeal clamps, drops zero-radius spots and
    caps the list at 16; the search finds a valid donor and returns null for a
    brush that covers everything.
  heal-probe.cjs (scratchpad, the rebuilt app at http://localhost:8090) —
    29 PASS, 0 FAIL, no page errors: the cursor circle is 2 x 0.012 x width and
    centred on the pointer, L is visibly bigger, S and L are exclusive; one
    click is one spot; a speck at 151 reads 154 at its centre after the heal
    and the photo's other specks and empty skin are unchanged; the spot and its
    borrowed source are both drawn; the chip goes amber; CLEAR appears and
    restores everything; UNDO (the TopBar button) brings the dust back and REDO
    heals it again; three specks and one L-sized blob all go; the repairs
    survive a reload.
  Regressions against the rebuilt app, 0 fail: landing-test.cjs 172,
    pro-gate-test.cjs 27, award-column-probe.cjs 18, otp-code-probe.cjs 10,
    tone-curve-probe.cjs 42; backend npm test 180 passed, 0 failed.
  web tsc --noEmit clean.

ponytail: spots live in the rendered photo's coordinates, so re-cropping or
re-rotating after healing slides them — re-heal or CLEAR when that matters; a
coordinate space pinned to the sensor would need the crop and rotation to carry
the spots through. No live brush-size gesture and no colour-matching term: the
donor is chosen by resemblance alone, add a colour term if skin tones ever
mismatch. The list is capped at 16 with oldest-out rather than refusing the
seventeenth click.

docker/frontend/src/ui/ImageStage.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { useI18n } from '../i18n/I18nProvider';
-import { MIN_CROP_FRAC, type CropRect } from '../../shared/types';
-import { samplePixel } from '../engine/imageOps';
+import { MIN_CROP_FRAC, type CropRect, type HealSpot } from '../../shared/types';
+import { bitmapReader, samplePixel } from '../engine/imageOps';
+import { findHealSource } from '../../shared/utils/heal';
 import { measureMark } from '../engine/exportEngine';
 import { Histogram } from './Histogram';
 
@@ -104,6 +105,10 @@ export function ImageStage({
   marks = [],
   straightenRuler = null,
   curvePanel = null,
+  healing = false,
+  healSpots = [],
+  healR = 0.02,
+  onHealSpot,
   dims = null,
 }: {
   previewUrl: string | null;
@@ -155,6 +160,14 @@ export function ImageStage({
   // rather than in a column beside it. It is anchored, not draggable — the graph
   // is a fixed square and the photo moves under it.
   curvePanel?: ReactNode;
+  // FX's HEAL brush: the circle under the cursor is the size of the spot a
+  // click lays down, and the patch each spot borrows is searched for at the
+  // moment of the click (shared/utils/heal.ts) — off the render on the stage,
+  // which is the picture the repair is being judged against.
+  healing?: boolean;
+  healSpots?: HealSpot[];
+  healR?: number;
+  onHealSpot?: (spot: HealSpot) => void;
   // The photo's own pixel size, as the stage stands: the file's shape turned by
   // the quarter turn and cut by a committed crop, so the number in the row under
   // the photo is the resolution an export at the photo's own size renders.
@@ -192,6 +205,9 @@ export function ImageStage({
   // Where the eyedropper's own icon is drawing itself inside the photo: the
   // layer is the photo's box, so plain pixels are enough.
   const [pickPos, setPickPos] = useState<{ x: number; y: number } | null>(null);
+  // Where the heal brush's circle is drawing itself, same coordinates as the
+  // eyedropper's icon: plain pixels inside the photo's own box.
+  const [healPos, setHealPos] = useState<{ x: number; y: number } | null>(null);
   // The colour that was read is rarely a clear patch of photo, so the mixer's
   // card can be dragged off the point it hangs on. The offset is a fraction of
   // the photo — which is what the layer is — so a zoom keeps the card where it
@@ -249,7 +265,7 @@ export function ImageStage({
   }, []);
 
   useEffect(() => {
-    if (!cropEditing && !compare && !picking && !pickPanelAt && !wmCount && !showStraighten && !showCurve) {
+    if (!cropEditing && !compare && !picking && !pickPanelAt && !wmCount && !showStraighten && !showCurve && !healing) {
       setBox(null);
       return;
     }
@@ -270,7 +286,7 @@ export function ImageStage({
       ro?.disconnect();
       window.removeEventListener('resize', measure);
     };
-  }, [cropEditing, compare, picking, pickPanelAt, wmCount, showStraighten, showCurve, measure, previewUrl]);
+  }, [cropEditing, compare, picking, pickPanelAt, wmCount, showStraighten, showCurve, healing, measure, previewUrl]);
 
   const grabPanel = (e: React.PointerEvent<HTMLDivElement>) => {
     e.stopPropagation(); // the photo must not pan under the card
@@ -331,6 +347,35 @@ export function ImageStage({
     [previewUrl, onPickColor]
   );
 
+  // FX's HEAL brush. One click lays one spot down: the circle is where the
+  // click landed and the patch is whatever the search finds around it. The
+  // repair is drawn the moment the recipe carries the spot — the same live road
+  // every other knob takes, so the picture answers while the dust is still
+  // under the cursor.
+  const healAt = useCallback(
+    async (e: React.MouseEvent) => {
+      const img = imgRef.current;
+      if (!img || !previewUrl || !onHealSpot) return;
+      const rect = img.getBoundingClientRect();
+      if (!(rect.width > 0 && rect.height > 0)) return;
+      const fx = (e.clientX - rect.left) / rect.width;
+      const fy = (e.clientY - rect.top) / rect.height;
+      if (!(fx >= 0 && fx <= 1 && fy >= 0 && fy <= 1)) return;
+      // The same decode the eyedropper keeps, under the same rule: one bitmap
+      // per URL, and the search reads it a few hundred times rather than once.
+      if (!pickCache.current || pickCache.current.url !== previewUrl) {
+        const blob = await (await fetch(previewUrl)).blob();
+        pickCache.current?.bmp.close();
+        pickCache.current = { url: previewUrl, bmp: await createImageBitmap(blob) };
+      }
+      const src = findHealSource(bitmapReader(pickCache.current.bmp), fx, fy, healR);
+      // No candidate patch means no honest repair: the spot then borrows its own
+      // pixels, which is a way of doing nothing rather than a blind guess.
+      onHealSpot({ x: fx, y: fy, r: healR, sx: src ? src.sx : fx, sy: src ? src.sy : fy });
+    },
+    [previewUrl, onHealSpot, healR]
+  );
+
   // The img's box at scale 1 — the natural size fitted into the wrap, never
   // enlarged. Computed rather than measured so the transform cannot feed back
   // into it.
@@ -775,6 +820,64 @@ export function ImageStage({
               </span>
             </div>
           ) : null}
+          {/* FX's HEAL brush. The layer swallows the pointer the way the
+              eyedropper's does, so a click repairs instead of panning the
+              photo; the circle rides the cursor at the size a spot will be, and
+              every spot already laid down keeps its own circle on the picture —
+              the drawn circle and the borrowed patch, the pair the renderer
+              works with. */}
+          {healing && !cropEditing && box ? (
+            <div
+              className="heal-layer"
+              data-key="heal-layer"
+              style={{
+                left: box.left,
+                top: box.top,
+                width: box.width,
+                height: box.height,
+                transform:
+                  view.s === 1 ? undefined : `translate(${view.x}px, ${view.y}px) scale(${view.s})`,
+              }}
+              onPointerDown={(e) => e.stopPropagation()}
+              onPointerMove={(e) => {
+                const r = e.currentTarget.getBoundingClientRect();
+                setHealPos({ x: e.clientX - r.left, y: e.clientY - r.top });
+              }}
+              onPointerLeave={() => setHealPos(null)}
+              onClick={healAt}
+            >
+              {healSpots.map((s, i) => {
+                // r is a fraction of the photo's WIDTH, so the circle is round
+                // whatever the picture's shape is — the same measurement the
+                // shader makes against the render's own pixels.
+                const d = 2 * s.r * box.width;
+                const at = (x: number, y: number) => ({
+                  left: `${x * 100}%`,
+                  top: `${y * 100}%`,
+                  width: d,
+                  height: d,
+                });
+                return (
+                  <span className="heal-set" data-key="heal-set" data-i={i} key={i}>
+                    <span className="heal-source" data-key="heal-source" style={at(s.sx, s.sy)} />
+                    <span className="heal-spot" data-key="heal-spot" style={at(s.x, s.y)} />
+                  </span>
+                );
+              })}
+              {healPos ? (
+                <span
+                  className="heal-cursor"
+                  data-key="heal-cursor"
+                  style={{
+                    left: healPos.x,
+                    top: healPos.y,
+                    width: 2 * healR * box.width,
+                    height: 2 * healR * box.width,
+                  }}
+                />
+              ) : null}
+            </div>
+          ) : null}
           {/* The mixer's panel for the colour the eyedropper just read: it hangs
               on the photo at the point it was read from, and its swatch follows
               the three knobs under it. */}