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/engine/exportEngine.ts

@@ -34,6 +34,7 @@ import {
 } from '../../shared/utils/toneShader';
 import { CINEMA_SKSL, getCinemaUniforms, cinemaIsActive } from '../../shared/utils/cinemaShader';
 import { CURVE_SKSL, CURVE_LUT_SIZE, curveIsActive, curveLut } from '../../shared/utils/toneCurve';
+import { HEAL_SKSL, healUniforms, readHeal } from '../../shared/utils/heal';
 import {
   GRAIN_SKSL,
   HALATION_SKSL,
@@ -140,6 +141,7 @@ let cinemaEffect: any = null;
 let glowEffect: any = null;
 let halationEffect: any = null;
 let curveEffect: any = null;
+let healEffect: any = null;
 
 function effects() {
   if (!sharpenEffect) sharpenEffect = Skia.RuntimeEffect.Make(CLARITY_SKSL);
@@ -148,7 +150,8 @@ function effects() {
   if (!glowEffect) glowEffect = Skia.RuntimeEffect.Make(GLOW_SKSL);
   if (!halationEffect) halationEffect = Skia.RuntimeEffect.Make(HALATION_SKSL);
   if (!curveEffect) curveEffect = Skia.RuntimeEffect.Make(CURVE_SKSL);
-  return { sharpenEffect, toneEffect, cinemaEffect, glowEffect, halationEffect, curveEffect };
+  if (!healEffect) healEffect = Skia.RuntimeEffect.Make(HEAL_SKSL);
+  return { sharpenEffect, toneEffect, cinemaEffect, glowEffect, halationEffect, curveEffect, healEffect };
 }
 
 // CLARITY_SKSL uniforms are (a, px.x, px.y); px = one source pixel = 1 unit on
@@ -623,6 +626,39 @@ export async function renderPhoto(input: RenderInput): Promise<RenderResult | nu
       }
     }
 
+    // 6d. HEAL — the FX tab's dust brush (see heal.ts). It is the last thing
+    // that touches the photo's own pixels, and deliberately so: the borrowed
+    // patch is copied out of the pixels the pipeline has already built, so a
+    // repair matches the grade, the blur and the grain around it by
+    // construction instead of being a second render of the same look that has
+    // to agree. The card, the wall and the watermarks are drawn after it, so a
+    // healed spot still carries the frame's own edge.
+    const heal = readHeal(adjustments.heal);
+    if (heal.length) {
+      const { healEffect: effect } = effects();
+      flush(surface);
+      const snap = own(surface.makeImageSnapshot());
+      const child = snap
+        ? own(
+            snap.makeShaderOptions(
+              Skia.TileMode.Clamp, Skia.TileMode.Clamp, Skia.FilterMode.Linear, Skia.MipmapMode.None
+            )
+          )
+        : null;
+      const shader =
+        effect && child
+          ? own(effect.makeShaderWithChildren(healUniforms(heal, width, height), [child]))
+          : null;
+      if (shader) {
+        // Snapshot, clear, redraw — the pass reads the frame it is about to
+        // overwrite (the same shape convPass uses for CLARITY).
+        canvas.clear(Skia.Color('transparent'));
+        const healPaint = own(Skia.Paint());
+        healPaint.setShader(shader);
+        canvas.drawRect(Skia.XYWHRect(0, 0, width, height), healPaint);
+      }
+    }
+
     release(owned, skImage);
 
     // 7. Frame.

docker/frontend/src/engine/imageOps.ts

@@ -76,6 +76,32 @@ export function samplePixel(bitmap: ImageBitmap, fx: number, fy: number): { r: n
   return { r, g, b };
 }
 
+// A sampler over a whole decoded photo: fractions in, one pixel out. The heal
+// brush reads a few hundred points around a spot while it looks for a patch to
+// borrow, and per-sample that is a drawImage through `samplePixel` — which is
+// the right shape for one eyedropper click and the wrong one for a search, so
+// the pixels are read once and then indexed.
+export function bitmapReader(bitmap: ImageBitmap): (fx: number, fy: number) => { r: number; g: number; b: number } {
+  const w = bitmap.width;
+  const h = bitmap.height;
+  const canvas = document.createElement('canvas');
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext('2d', { willReadFrequently: true });
+  let data: Uint8ClampedArray | null = null;
+  if (ctx && w > 0 && h > 0) {
+    ctx.drawImage(bitmap, 0, 0);
+    data = ctx.getImageData(0, 0, w, h).data;
+  }
+  return (fx, fy) => {
+    if (!data) return { r: 0, g: 0, b: 0 };
+    const x = Math.min(w - 1, Math.max(0, Math.floor(fx * w)));
+    const y = Math.min(h - 1, Math.max(0, Math.floor(fy * h)));
+    const i = (y * w + x) * 4;
+    return { r: data[i], g: data[i + 1], b: data[i + 2] };
+  };
+}
+
 // Uploads are capped by the API (and by nginx in front of it), so a phone's
 // 12MP JPEG has to shrink before it goes up — the same downscale the preview
 // uses. The ORIGINAL bytes come back untouched (same reference) when the photo