@pixerate/editor 0.215.0 → 0.217.0

package/dist/image-editor/index.js

@@ -1070,6 +1070,105 @@ function startMarchingAnts(tick, stepMs = MARCHING_ANTS_STEP_MS) {
   return () => clearInterval(id);
 }
 
+// src/image-editor/selection/diff.ts
+function compareSelectionMasks(a, b, width, height, options = {}) {
+  const minArea = Math.max(1, options.minArea ?? 4);
+  const maxRegions = Math.max(1, options.maxRegions ?? 10);
+  const n = width * height;
+  const ad = a?.data;
+  const bd = b?.data;
+  const added = new Uint8Array(n);
+  const removed = new Uint8Array(n);
+  let areaA = 0;
+  let areaB = 0;
+  let inter = 0;
+  let change = 0;
+  let addedArea = 0;
+  let removedArea = 0;
+  for (let i = 0; i < n; i++) {
+    const va = ad ? ad[i] : 0;
+    const vb = bd ? bd[i] : 0;
+    if (va !== vb) change += Math.abs(vb - va);
+    const ia = va >= 128;
+    const ib = vb >= 128;
+    if (ia) areaA++;
+    if (ib) areaB++;
+    if (ia && ib) inter++;
+    else if (ib) {
+      added[i] = 255;
+      addedArea++;
+    } else if (ia) {
+      removed[i] = 255;
+      removedArea++;
+    }
+  }
+  const union = areaA + areaB - inter;
+  const addedMask = createSelectionMask(width, height, added);
+  const removedMask = createSelectionMask(width, height, removed);
+  return {
+    a: { area: areaA, bounds: a?.bounds ?? null },
+    b: { area: areaB, bounds: b?.bounds ?? null },
+    added: { area: addedArea, ...pieces(added, width, height, addedMask.bounds, minArea, maxRegions) },
+    removed: { area: removedArea, ...pieces(removed, width, height, removedMask.bounds, minArea, maxRegions) },
+    iou: union ? Math.round(inter / union * 1e4) / 1e4 : 1,
+    coverageChange: Math.round(change / 255),
+    identical: change === 0,
+    addedMask,
+    removedMask
+  };
+}
+function pieces(bits, W, H, bounds, minArea, maxRegions) {
+  if (!bounds) return { count: 0, regions: [] };
+  const { x: x0, y: y0, width: w, height: h } = bounds;
+  const seen = new Uint8Array(w * h);
+  const stack = new Int32Array(w * h);
+  const found = [];
+  for (let start = 0; start < w * h; start++) {
+    if (seen[start] || !bits[(y0 + Math.floor(start / w)) * W + x0 + start % w]) continue;
+    let area = 0;
+    let bx0 = w;
+    let by0 = h;
+    let bx1 = -1;
+    let by1 = -1;
+    let top = 0;
+    stack[top++] = start;
+    seen[start] = 1;
+    while (top) {
+      const k = stack[--top];
+      const i = k % w;
+      const j = (k - i) / w;
+      area++;
+      if (i < bx0) bx0 = i;
+      if (i > bx1) bx1 = i;
+      if (j < by0) by0 = j;
+      if (j > by1) by1 = j;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+          const ni = i + dx;
+          const nj = j + dy;
+          if (ni < 0 || nj < 0 || ni >= w || nj >= h) continue;
+          const nk = nj * w + ni;
+          if (seen[nk] || !bits[(y0 + nj) * W + x0 + ni]) continue;
+          seen[nk] = 1;
+          stack[top++] = nk;
+        }
+      }
+    }
+    if (area >= minArea) found.push({ area, bounds: { x: x0 + bx0, y: y0 + by0, width: bx1 - bx0 + 1, height: by1 - by0 + 1 } });
+  }
+  found.sort((p, q) => q.area - p.area);
+  return { count: found.length, regions: found.slice(0, maxRegions) };
+}
+function selectionDiffPixels(added, removed) {
+  const n = added.width * added.height;
+  const out = new Uint8ClampedArray(n * 4);
+  for (let i = 0; i < n; i++) {
+    if (added.data[i]) out.set([34, 197, 94, 140], i * 4);
+    else if (removed.data[i]) out.set([239, 68, 68, 140], i * 4);
+  }
+  return out;
+}
+
 // src/image-editor/layers/render.ts
 function isQuarterTurn(rotate) {
   return normalizeAngle(rotate) % 90 === 0;
@@ -1515,6 +1614,19 @@ var ImageEditorRenderer = class {
       }
       ctx.restore();
     }
+    const diff = state.selectionDiff;
+    if (diff && diff.selection === (state.selection ?? null)) {
+      ctx.save();
+      try {
+        applyImageProjectionToContext(ctx, projection);
+        ctx.beginPath();
+        ctx.rect(region.x, region.y, region.width, region.height);
+        ctx.clip();
+        this.drawSelectionDiff(ctx, diff);
+      } catch {
+      }
+      ctx.restore();
+    }
     if (options.brushCursor) {
       const b = options.brushCursor;
       ctx.save();
@@ -1970,6 +2082,7 @@ var ImageEditorRenderer = class {
     this.onPreviewHistogram?.(histogram);
   }
   quickMaskCache = /* @__PURE__ */ new WeakMap();
+  diffCache = /* @__PURE__ */ new WeakMap();
   outlineCache = /* @__PURE__ */ new WeakMap();
   emptyMaskCache = null;
   /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
@@ -2023,6 +2136,19 @@ var ImageEditorRenderer = class {
     ctx.drawImage(cached.canvas, 0, 0, mask.width, mask.height);
   }
   /** Rubylith over the unselected area, drawn in natural image space. */
+  drawSelectionDiff(ctx, diff) {
+    let canvas = this.diffCache.get(diff);
+    if (!canvas) {
+      canvas = this.createCanvas(diff.added.width, diff.added.height);
+      const mctx = canvas.getContext("2d");
+      if (!mctx || typeof mctx.createImageData !== "function") return;
+      const img = mctx.createImageData(diff.added.width, diff.added.height);
+      img.data.set(selectionDiffPixels(diff.added, diff.removed));
+      mctx.putImageData(img, 0, 0);
+      this.diffCache.set(diff, canvas);
+    }
+    ctx.drawImage(canvas, 0, 0, diff.added.width, diff.added.height);
+  }
   drawQuickMask(ctx, selection) {
     let canvas = this.quickMaskCache.get(selection);
     if (!canvas) {
@@ -2609,27 +2735,7 @@ function inspectMaskEdge(mask, image, options = {}) {
     if (img[i + 3] < 128) return null;
     return [img[i], img[i + 1], img[i + 2]];
   };
-  const premul = (x, y, c) => {
-    const ix = Math.min(image.width - 1, Math.max(0, x - image.x));
-    const iy = Math.min(image.height - 1, Math.max(0, y - image.y));
-    const i = (iy * image.width + ix) * 4;
-    return img[i + c] * img[i + 3] / 255;
-  };
-  const gradCache = /* @__PURE__ */ new Map();
-  const gradient = (x, y) => {
-    const k = y * W + x;
-    const hit = gradCache.get(k);
-    if (hit !== void 0) return hit;
-    let best = 0;
-    for (let c = 0; c < 3; c++) {
-      const p = (dx, dy) => premul(x + dx, y + dy, c);
-      const gx = p(1, -1) + 2 * p(1, 0) + p(1, 1) - p(-1, -1) - 2 * p(-1, 0) - p(-1, 1);
-      const gy = p(-1, 1) + 2 * p(0, 1) + p(1, 1) - p(-1, -1) - 2 * p(0, -1) - p(1, -1);
-      best = Math.max(best, Math.hypot(gx, gy) / 1020);
-    }
-    gradCache.set(k, best);
-    return best;
-  };
+  const gradient = createGradientSampler(image, W);
   const B = Math.min(256, Math.max(24, Math.round(Math.max(W, H) / 12)));
   const BW = Math.ceil(W / B);
   const blocks = /* @__PURE__ */ new Map();
@@ -2806,6 +2912,30 @@ function inspectMaskEdge(mask, image, options = {}) {
     issues
   };
 }
+function createGradientSampler(image, W) {
+  const img = image.data;
+  const premul = (x, y, c) => {
+    const ix = Math.min(image.width - 1, Math.max(0, x - image.x));
+    const iy = Math.min(image.height - 1, Math.max(0, y - image.y));
+    const i = (iy * image.width + ix) * 4;
+    return img[i + c] * img[i + 3] / 255;
+  };
+  const cache = /* @__PURE__ */ new Map();
+  return (x, y) => {
+    const k = y * W + x;
+    const hit = cache.get(k);
+    if (hit !== void 0) return hit;
+    let best = 0;
+    for (let c = 0; c < 3; c++) {
+      const p = (dx, dy) => premul(x + dx, y + dy, c);
+      const gx = p(1, -1) + 2 * p(1, 0) + p(1, 1) - p(-1, -1) - 2 * p(-1, 0) - p(-1, 1);
+      const gy = p(-1, 1) + 2 * p(0, 1) + p(1, 1) - p(-1, -1) - 2 * p(0, -1) - p(1, -1);
+      best = Math.max(best, Math.hypot(gx, gy) / 1020);
+    }
+    cache.set(k, best);
+    return best;
+  };
+}
 function traceLoops(a, W, H, rx0, ry0, rx1, ry1) {
   const w = rx1 - rx0;
   const h = ry1 - ry0;
@@ -2983,10 +3113,139 @@ function regions(a, W, H, b, minArea) {
     const kept = list.filter((r) => r.area >= minArea).sort((p, q) => q.area - p.area);
     return { count: kept.length, totalArea: kept.reduce((s, r) => s + r.area, 0), largest: kept.slice(0, 10).map((r) => ({ area: r.area, bounds: box(r) })) };
   };
-  const pieces = found.filter((r) => r.fg).sort((p, q) => q.area - p.area);
+  const pieces2 = found.filter((r) => r.fg).sort((p, q) => q.area - p.area);
   return {
     holes: summarize(found.filter((r) => !r.fg && !r.outer)),
-    islands: summarize(pieces.slice(1))
+    islands: summarize(pieces2.slice(1))
+  };
+}
+
+// src/image-editor/selection/uncertainty.ts
+var BACKED = 0.2;
+function selectionUncertainty(mask, image, options = {}) {
+  const W = mask.width;
+  const H = mask.height;
+  const empty = () => ({ unknown: createSelectionMask(W, H), regions: [], count: 0, confidence: 1 });
+  const b = mask.bounds;
+  if (!b) return empty();
+  const band = Math.max(1, Math.round(options.band ?? Math.max(2, Math.min(W, H) / 200)));
+  const minArea = Math.max(1, options.minArea ?? 16);
+  const maxRegions = Math.max(1, options.maxRegions ?? 20);
+  const a = mask.data;
+  const gradient = createGradientSampler(image, W);
+  const x0 = Math.max(0, b.x - band - 1);
+  const y0 = Math.max(0, b.y - band - 1);
+  const x1 = Math.min(W, b.x + b.width + band + 1);
+  const y1 = Math.min(H, b.y + b.height + band + 1);
+  const w = x1 - x0;
+  const h = y1 - y0;
+  const evidence = new Float32Array(w * h).fill(NaN);
+  const seeds = new Uint8Array(w * h);
+  let sum = 0;
+  let n = 0;
+  const on = (x, y) => a[y * W + x] >= 128;
+  for (let y = y0; y < y1; y++) {
+    for (let x = x0; x < x1; x++) {
+      const v = on(x, y);
+      const differs = (nx, ny) => nx >= 0 && ny >= 0 && nx < W && ny < H && on(nx, ny) !== v;
+      if (!(differs(x - 1, y) || differs(x + 1, y) || differs(x, y - 1) || differs(x, y + 1))) continue;
+      let g = 0;
+      for (let dy = -2; dy <= 2; dy++) {
+        for (let dx = -2; dx <= 2; dx++) {
+          const nx = x + dx;
+          const ny = y + dy;
+          if (nx >= 0 && ny >= 0 && nx < W && ny < H) g = Math.max(g, gradient(nx, ny));
+        }
+      }
+      const e = Math.min(1, g / BACKED);
+      const k = (y - y0) * w + (x - x0);
+      evidence[k] = e;
+      sum += e;
+      n++;
+      if (e < 0.5) seeds[k] = 1;
+    }
+  }
+  if (!n) return empty();
+  const rows = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    let last = -Infinity;
+    for (let x = 0; x < w; x++) {
+      if (seeds[y * w + x]) last = x;
+      if (x - last <= band) rows[y * w + x] = 1;
+    }
+    last = Infinity;
+    for (let x = w - 1; x >= 0; x--) {
+      if (seeds[y * w + x]) last = x;
+      if (last - x <= band) rows[y * w + x] = 1;
+    }
+  }
+  const grown = new Uint8Array(w * h);
+  for (let x = 0; x < w; x++) {
+    let last = -Infinity;
+    for (let y = 0; y < h; y++) {
+      if (rows[y * w + x]) last = y;
+      if (y - last <= band) grown[y * w + x] = 1;
+    }
+    last = Infinity;
+    for (let y = h - 1; y >= 0; y--) {
+      if (rows[y * w + x]) last = y;
+      if (last - y <= band) grown[y * w + x] = 1;
+    }
+  }
+  const label = new Int32Array(w * h);
+  const stack = new Int32Array(w * h);
+  const found = [];
+  for (let start = 0; start < w * h; start++) {
+    if (!grown[start] || label[start]) continue;
+    const r = { area: 0, e: 0, en: 0, bx0: w, by0: h, bx1: -1, by1: -1 };
+    const id = found.length + 1;
+    let top = 0;
+    stack[top++] = start;
+    label[start] = id;
+    while (top) {
+      const k = stack[--top];
+      const i = k % w;
+      const j = (k - i) / w;
+      r.area++;
+      if (!Number.isNaN(evidence[k])) {
+        r.e += evidence[k];
+        r.en++;
+      }
+      if (i < r.bx0) r.bx0 = i;
+      if (i > r.bx1) r.bx1 = i;
+      if (j < r.by0) r.by0 = j;
+      if (j > r.by1) r.by1 = j;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+          const ni = i + dx;
+          const nj = j + dy;
+          if (ni < 0 || nj < 0 || ni >= w || nj >= h) continue;
+          const nk = nj * w + ni;
+          if (!grown[nk] || label[nk]) continue;
+          label[nk] = id;
+          stack[top++] = nk;
+        }
+      }
+    }
+    found.push(r);
+  }
+  const unknownData = new Uint8Array(W * H);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const id = label[y * w + x];
+      if (id && found[id - 1].area >= minArea) unknownData[(y + y0) * W + x + x0] = 255;
+    }
+  }
+  const kept = found.filter((r) => r.area >= minArea).map((r) => ({
+    bounds: { x: x0 + r.bx0, y: y0 + r.by0, width: r.bx1 - r.bx0 + 1, height: r.by1 - r.by0 + 1 },
+    area: r.area,
+    confidence: Math.round((r.en ? r.e / r.en : 0) * 1e3) / 1e3
+  })).sort((p, q) => p.confidence - q.confidence || q.area - p.area);
+  return {
+    unknown: createSelectionMask(W, H, unknownData),
+    regions: kept.slice(0, maxRegions),
+    count: kept.length,
+    confidence: Math.round(sum / n * 1e3) / 1e3
   };
 }
 
@@ -9730,6 +9989,7 @@ var ImageEditorController = class {
    */
   async refineSelectionTo(params, output = "selection", options = {}) {
     const edits = options.edits ?? [];
+    const regions2 = this.checkRegions(options.regions);
     const refineMode = options.refineMode ?? "color";
     if (!this.state.selection?.bounds && !edits.length) throw new Error("Nothing is selected; select first, or pass edits that paint a selection.");
     if (refineMode === "object" && !this.segmentation) {
@@ -9764,7 +10024,14 @@ var ImageEditorController = class {
       if (!clipped?.bounds) throw new Error("The segmentation model found no object in the selection; use refineMode color.");
       sel = clipped;
     }
-    const refined = refineSelection(pixels, sel, params, edited.refineBrush);
+    let refined = refineSelection(pixels, sel, params, edited.refineBrush);
+    if (regions2) {
+      const data = Uint8Array.from(sel.data);
+      for (const r of regions2) {
+        for (let y = r.y; y < r.y + r.height; y++) data.set(refined.data.subarray(y * width + r.x, y * width + r.x + r.width), y * width + r.x);
+      }
+      refined = createSelectionMask(width, height, data);
+    }
     if (!refined.bounds) throw new Error("Refining left nothing selected; use a smaller shiftEdge or contrast.");
     if (toDocument) {
       const document2 = this.documentFromSelection({ layerId, withMask: output === "new-document-with-mask", selection: refined, decontaminate: amount * 100, radius: params.radius });
@@ -10209,6 +10476,96 @@ var ImageEditorController = class {
     const report = inspectMaskEdge(mask, image, options);
     return { target, ...layer ? { layerId: layer.id } : {}, ...report };
   }
+  /** Whole-pixel rectangles inside the canvas, or a useful error; undefined stays undefined. */
+  checkRegions(regions2) {
+    if (regions2 === void 0) return void 0;
+    const { width, height } = this.naturalSize;
+    if (!Array.isArray(regions2) || !regions2.length) throw new Error("regions must be a non-empty list of { x, y, width, height } (e.g. the uncertainRegions bounds); leave it out to refine everywhere.");
+    return regions2.map((r, i) => {
+      const x = Math.max(0, Math.floor(r?.x));
+      const y = Math.max(0, Math.floor(r?.y));
+      const x1 = Math.min(width, Math.ceil(r?.x + r?.width));
+      const y1 = Math.min(height, Math.ceil(r?.y + r?.height));
+      if (![x, y, x1, y1].every(Number.isFinite) || x1 <= x || y1 <= y) throw new Error(`regions[${i}] must overlap the image (0..${width} \xD7 0..${height}), got ${JSON.stringify(r)}.`);
+      return { x, y, width: x1 - x, height: y1 - y };
+    });
+  }
+  /**
+   * Where the selection is unsure of itself: the stretches of its edge with no image edge under
+   * them, widened into a band (a trimap's unknown), as a mask and regions with bounds and
+   * confidence, least confident first. Measured against the composite. Read-only; an empty
+   * selection has none.
+   */
+  selectionUncertainty(options = {}) {
+    const { width, height } = this.naturalSize;
+    const sel = this.getSelection();
+    if (!sel?.bounds) return selectionUncertainty(createSelectionMask(width, height), { x: 0, y: 0, width: 0, height: 0, data: new Uint8ClampedArray(0) }, options);
+    const b = sel.bounds;
+    const m = Math.max(8, Math.ceil(options.band ?? Math.max(2, Math.min(width, height) / 200)) + 4);
+    const x = Math.max(0, b.x - m);
+    const y = Math.max(0, b.y - m);
+    const region = { x, y, width: Math.min(width, b.x + b.width + m) - x, height: Math.min(height, b.y + b.height + m) - y };
+    return selectionUncertainty(sel, { ...this.compositePixels(region), x, y }, options);
+  }
+  /**
+   * A selection to compare (`compareSelections`): the current one, the one `steps` undo steps
+   * ago, a saved channel, or a layer's painted or vector mask. `null` is nothing selected.
+   */
+  selectionFrom(source) {
+    const { width, height } = this.naturalSize;
+    switch (source?.kind) {
+      case "selection":
+        return this.getSelection();
+      case "history": {
+        const steps = source.steps ?? 1;
+        const depth = this.undoStack.length;
+        if (!Number.isInteger(steps) || steps < 1) throw new LayerOperationError(`steps must be a whole number of undo steps back, at least 1; got ${String(source.steps)}.`);
+        if (steps > depth) throw new LayerOperationError(`There ${depth === 1 ? "is 1 undo step" : `are ${depth} undo steps`}; steps must be 1..${depth || 1}${depth ? "" : " once something has been done"}.`);
+        return this.undoStack[depth - steps].selection ?? null;
+      }
+      case "channel":
+        return this.requireChannel(source.channelId).mask;
+      case "layer-mask": {
+        const layer = this.getLayer(source.layerId);
+        if (!layer) throw new LayerOperationError(`There is no layer "${source.layerId}" (see list_layers).`);
+        const mask = this.layerMaskCoverage(layer.id);
+        if (!mask) throw new LayerOperationError(`Layer "${layer.name || layer.id}" has no painted mask; add one with add_layer_mask, or compare its vector-mask.`);
+        return mask;
+      }
+      case "vector-mask": {
+        const layer = this.getLayer(source.layerId);
+        if (!layer) throw new LayerOperationError(`There is no layer "${source.layerId}" (see list_layers).`);
+        const { vm } = this.requireVectorMask(layer.id);
+        const mask = pathToSelection(vm.components, width, height, { fillRule: vm.fillRule });
+        return vm.inverted ? invertSelection(mask) : mask;
+      }
+      default:
+        throw new LayerOperationError(`Unknown selection source ${JSON.stringify(source)}. Use selection, history, channel, layer-mask or vector-mask.`);
+    }
+  }
+  /**
+   * What changed from selection `a` (default: before the last undo step) to `b` (default: the
+   * current selection): added and removed area with their largest pieces, IoU and the coverage
+   * change. With `show` (default true) the canvas tints added area green and removed red until the
+   * selection next changes (view state, no undo step). Read-only otherwise.
+   */
+  compareSelections(a = { kind: "history", steps: 1 }, b = { kind: "selection" }, options = {}) {
+    const { width, height } = this.naturalSize;
+    const ma = this.selectionFrom(a);
+    const mb = this.selectionFrom(b);
+    const { addedMask, removedMask, ...diff } = compareSelectionMasks(ma, mb, width, height, options);
+    if (options.show !== false) {
+      this.state.selectionDiff = diff.identical ? null : { added: addedMask, removed: removedMask, selection: this.state.selection ?? null };
+      this.notify();
+    }
+    return diff;
+  }
+  /** Hides the `compareSelections` overlay. */
+  clearSelectionDiff() {
+    if (!this.state.selectionDiff) return;
+    this.state.selectionDiff = null;
+    this.notify();
+  }
   /** A layer's painted mask over the canvas as a selection mask; null without one (or for a depth mask). */
   layerMaskCoverage(layerId) {
     const layer = this.getLayer(layerId);
@@ -12921,6 +13278,10 @@ function rectOf(args) {
   if (rect2.width <= 0 || rect2.height <= 0) throw new Error("width and height must be greater than 0.");
   return rect2;
 }
+function uncertainty(controller) {
+  const u = controller.selectionUncertainty();
+  return { uncertainRegions: u.regions, uncertainCount: u.count, edgeConfidence: u.confidence };
+}
 function summary(controller) {
   const sel = controller.getSelection();
   const { width, height } = controller.getState().imageDimensions;
@@ -12970,6 +13331,65 @@ function createImageSelectionTools(controller) {
       return controller.inspectMaskEdge(t, { layerId, minArea });
     }
   };
+  const sourceSchema = (which, dflt) => ({
+    type: "object",
+    properties: {
+      source: { type: "string", enum: ["selection", "history", "channel", "layer-mask", "vector-mask"], description: "selection: the current one; history: as it was steps undo steps ago; channel: a saved selection (channelId, see list_channels); layer-mask / vector-mask: a layer's mask (layerId)." },
+      steps: { type: "integer", minimum: 1, description: "history only: how many undo steps back (default 1, before the last edit)." },
+      channelId: { type: "string", description: "channel only: the channel id from list_channels." },
+      layerId: { type: "string", description: "layer-mask and vector-mask only: the layer id from list_layers." }
+    },
+    required: ["source"],
+    additionalProperties: false,
+    description: `${which} (default ${dflt}).`
+  });
+  const toSource = (v, fallback) => {
+    if (v === void 0) return fallback;
+    const o = v;
+    const extra = (keys) => {
+      const bad = Object.keys(o).filter((k) => k !== "source" && !keys.includes(k));
+      if (bad.length) throw new Error(`${bad.join(", ")} ${bad.length === 1 ? "does" : "do"} not apply to source ${o.source}.`);
+    };
+    switch (o.source) {
+      case "selection":
+        extra([]);
+        return { kind: "selection" };
+      case "history":
+        extra(["steps"]);
+        return { kind: "history", steps: o.steps ?? 1 };
+      case "channel":
+        extra(["channelId"]);
+        if (!o.channelId) throw new Error("source channel needs channelId (see list_channels).");
+        return { kind: "channel", channelId: o.channelId };
+      case "layer-mask":
+      case "vector-mask":
+        extra(["layerId"]);
+        if (!o.layerId) throw new Error(`source ${o.source} needs layerId (see list_layers).`);
+        return { kind: o.source, layerId: o.layerId };
+      default:
+        throw new Error(`Unknown source "${String(o.source)}". Use selection, history, channel, layer-mask or vector-mask.`);
+    }
+  };
+  const compareTool = {
+    name: "compare_selections",
+    title: "Compare two selections",
+    description: "Shows what changed between two selections, to check that a modify, refine or select step did what you meant. a (default: the selection before the last undo step) and b (default: the current selection) can each be the current selection, a history step, a saved channel or a layer's mask. Returns a and b (area, bounds), added and removed (area in pixels, count and the 10 largest pieces with bounds, ready for capture_view), iou 0-1, coverageChange (pixels of coverage changed, counting edges that only softened) and identical. With show (default true) the canvas tints added area green and removed red until the selection next changes (view only, no undo step).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        a: sourceSchema("The selection before", "history, 1 step back"),
+        b: sourceSchema("The selection after", "the current selection"),
+        minArea: { type: "number", minimum: 1, maximum: 1e6, description: "Pieces smaller than this many pixels are counted but not listed (default 4)." },
+        show: { type: "boolean", description: "Tint the change on the canvas (default true)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Compare two selections", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: ({ a, b, minArea, show }) => controller.compareSelections(toSource(a, { kind: "history", steps: 1 }), toSource(b, { kind: "selection" }), {
+      ...minArea !== void 0 ? { minArea } : {},
+      show: show !== false
+    })
+  };
   const selectRegion = {
     name: "select_region",
     title: "Select a region",
@@ -13145,7 +13565,14 @@ function createImageSelectionTools(controller) {
             additionalProperties: false
           }
         },
-        refineMode: { type: "string", enum: ["color", "object"], description: "color (default): refine from the image colours; object: from a host segmentation model's outline of the object (needs a model)." }
+        refineMode: { type: "string", enum: ["color", "object"], description: "color (default): refine from the image colours; object: from a host segmentation model's outline of the object (needs a model)." },
+        regions: {
+          type: "array",
+          minItems: 1,
+          maxItems: 50,
+          items: rectSchemaStrict,
+          description: "Refine only inside these rectangles (natural image pixels), e.g. the uncertainRegions bounds a smart selection returned; the rest of the selection stays as it is. Default: everywhere."
+        }
       },
       additionalProperties: false
     },
@@ -13176,7 +13603,8 @@ function createImageSelectionTools(controller) {
           layerId: typeof params.layerId === "string" ? params.layerId : void 0,
           decontaminate: num2(params.decontaminate, 0),
           edits,
-          refineMode: params.refineMode === "object" ? "object" : "color"
+          refineMode: params.refineMode === "object" ? "object" : "color",
+          ...params.regions !== void 0 ? { regions: params.regions } : {}
         }
       );
       return { ...summary(controller), ...result };
@@ -13332,7 +13760,7 @@ function createImageSelectionTools(controller) {
   const quickSelectTool = {
     name: "quick_select",
     title: "Quick Selection",
-    description: "Quick Selection: paints brush strokes (paths in natural image pixels) that each grow into the region they are painted on, out to its edges (a graph cut on colour and edges), combined with the selection by mode. With replace (default) the first stroke replaces the selection and later ones add, as the brush does; use mode subtract to take an area back out. Best for a subject or area that differs from its surroundings: paint inside it, away from the edge, then check with get_selection and capture_view and add or subtract strokes where it leaked or fell short. All strokes are one undoable step. Returns the selection.",
+    description: "Quick Selection: paints brush strokes (paths in natural image pixels) that each grow into the region they are painted on, out to its edges (a graph cut on colour and edges), combined with the selection by mode. With replace (default) the first stroke replaces the selection and later ones add, as the brush does; use mode subtract to take an area back out. Best for a subject or area that differs from its surroundings: paint inside it, away from the edge, then check with get_selection and capture_view and add or subtract strokes where it leaked or fell short. All strokes are one undoable step. Returns the selection. Also returns uncertainRegions (bounds, area, confidence 0-1; up to 20, least confident first), uncertainCount and edgeConfidence: where the edge has no image edge under it. Look at those with capture_view and fix only them (refine_selection with regions).",
     inputSchema: {
       type: "object",
       properties: {
@@ -13363,13 +13791,13 @@ function createImageSelectionTools(controller) {
         enhanceEdge: args.enhanceEdge,
         signal: context?.signal
       });
-      return summary(controller);
+      return { ...summary(controller), ...uncertainty(controller) };
     }
   };
   const selectObjectTool = {
     name: "select_object",
     title: "Object Selection",
-    description: 'Object Selection: selects the object inside rect (a box drawn loosely around it, natural image pixels; what lies outside the box is treated as background) or the object under point. With a host segmentation model it asks the model (falling back if nothing it returns fits); otherwise it finds the object from the colours of object and background and the edges between them (GrabCut). Combined with the selection by mode. A box is more reliable than a point: make it a little larger than the object on every side. Check with get_selection and capture_view, then fix with quick_select strokes or select_object with mode add / subtract. One undoable step. Returns the selection and method ("model" or "grabcut").',
+    description: 'Object Selection: selects the object inside rect (a box drawn loosely around it, natural image pixels; what lies outside the box is treated as background) or the object under point. With a host segmentation model it asks the model (falling back if nothing it returns fits); otherwise it finds the object from the colours of object and background and the edges between them (GrabCut). Combined with the selection by mode. A box is more reliable than a point: make it a little larger than the object on every side. Check with get_selection and capture_view, then fix with quick_select strokes or select_object with mode add / subtract. One undoable step. Returns the selection and method ("model" or "grabcut"). Also returns uncertainRegions (bounds, area, confidence 0-1; up to 20, least confident first), uncertainCount and edgeConfidence: where the edge has no image edge under it. Look at those with capture_view and fix only them (refine_selection with regions).',
     inputSchema: {
       type: "object",
       properties: {
@@ -13402,7 +13830,7 @@ function createImageSelectionTools(controller) {
         signal: context?.signal
       };
       const { method } = rect2 ? await controller.selectObject({ rect: { x: num2(rect2.x, NaN), y: num2(rect2.y, NaN), width: num2(rect2.width, NaN), height: num2(rect2.height, NaN) } }, options) : await controller.selectObject({ point: { x: num2(point.x, NaN), y: num2(point.y, NaN) } }, options);
-      return { ...summary(controller), method };
+      return { ...summary(controller), method, ...uncertainty(controller) };
     }
   };
   const selectFocusAreaTool = {
@@ -13436,7 +13864,7 @@ function createImageSelectionTools(controller) {
   const selectSkyTool = {
     name: "select_sky",
     title: "Select the sky",
-    description: 'Select \u203A Sky: selects the sky, combined with the selection by mode. With a host segmentation model it asks the model; otherwise it finds it classically (blue, or bright and grey when overcast, smooth, reaching down from the top of the image, including patches seen through branches or gaps) with the edge fitted to the skyline. Use it to replace or recolour a sky or to adjust the land without it (invert_selection). Raise threshold to take in haze or a sunset glow, lower it if bright buildings come in. One undoable step. Returns the selection, method ("model" or "classical"; threshold and softness apply to classical), and a note when no sky was found (the selection is then unchanged).',
+    description: 'Select \u203A Sky: selects the sky, combined with the selection by mode. With a host segmentation model it asks the model; otherwise it finds it classically (blue, or bright and grey when overcast, smooth, reaching down from the top of the image, including patches seen through branches or gaps) with the edge fitted to the skyline. Use it to replace or recolour a sky or to adjust the land without it (invert_selection). Raise threshold to take in haze or a sunset glow, lower it if bright buildings come in. One undoable step. Returns the selection, method ("model" or "classical"; threshold and softness apply to classical), and a note when no sky was found (the selection is then unchanged). Also returns uncertainRegions (bounds, area, confidence 0-1; up to 20, least confident first), uncertainCount and edgeConfidence: where the edge has no image edge under it. Look at those with capture_view and fix only them (refine_selection with regions).',
     inputSchema: {
       type: "object",
       properties: {
@@ -13458,7 +13886,7 @@ function createImageSelectionTools(controller) {
         useModel: args.useModel,
         signal: context?.signal
       });
-      return { ...summary(controller), method, ...note ? { note } : {} };
+      return { ...summary(controller), method, ...note ? { note } : {}, ...uncertainty(controller) };
     }
   };
   const magicWandTool = {
@@ -14016,6 +14444,7 @@ function createImageSelectionTools(controller) {
   return [
     getSelection,
     inspectEdge,
+    compareTool,
     selectAll,
     deselect,
     invert2,
@@ -14063,7 +14492,7 @@ function createImageSubjectSelectionTool(controller) {
   return {
     name: "select_subject",
     title: "Select a subject",
-    description: 'Select \u203A Subject: selects the main subject of the flattened image, combined with the selection by mode. With a segmentation model set by the host, target (a description such as "the dog" or "the house") chooses which objects; describe one object precisely to get only that one. Without a model, the subject that stands out most from the background is found classically (superpixel saliency and GrabCut): target cannot choose it, and method "saliency" and a note say so. Then check it with capture_view and fix it with quick_select or select_object. One undoable step. Returns the selection, the objects found (label, bounds), method ("model" or "saliency") and any note; none found leaves the selection unchanged.',
+    description: 'Select \u203A Subject: selects the main subject of the flattened image, combined with the selection by mode. With a segmentation model set by the host, target (a description such as "the dog" or "the house") chooses which objects; describe one object precisely to get only that one. Without a model, the subject that stands out most from the background is found classically (superpixel saliency and GrabCut): target cannot choose it, and method "saliency" and a note say so. Then check it with capture_view and fix it with quick_select or select_object. One undoable step. Returns the selection, the objects found (label, bounds), method ("model" or "saliency") and any note; none found leaves the selection unchanged. Also returns uncertainRegions (bounds, area, confidence 0-1; up to 20, least confident first), uncertainCount and edgeConfidence: where the edge has no image edge under it. Look at those with capture_view and fix only them (refine_selection with regions).',
     inputSchema: {
       type: "object",
       properties: {
@@ -14094,7 +14523,7 @@ function createImageSubjectSelectionTool(controller) {
         // Under playback the cursor traces what the model found, as a lasso, before it is selected.
         beforeApply: perform ? (outlines) => perform(planOutlineTrace(outlines)) : void 0
       });
-      return { ...summary(controller), found: segments, method, ...note ? { note } : {} };
+      return { ...summary(controller), found: segments, method, ...note ? { note } : {}, ...uncertainty(controller) };
     }
   };
 }
@@ -22043,6 +22472,7 @@ export {
   colorRange,
   colorRangePreset,
   combineSelections,
+  compareSelectionMasks,
   compileAdjustmentLayer,
   componentPath,
   componentsCoverage,
@@ -22070,6 +22500,7 @@ export {
   createAdjustmentLayer,
   createBlenderScratch,
   createCanvasTextShaper,
+  createGradientSampler,
   createImageCaptureSurface,
   createImageColorTools,
   createImageEditTools,
@@ -22587,6 +23018,7 @@ export {
   selectObjectIn,
   selectSimilar,
   selectionArea,
+  selectionDiffPixels,
   selectionFromCoverage,
   selectionFromPixels,
   selectionFromRegion,
@@ -22597,6 +23029,7 @@ export {
   selectionToCoverage,
   selectionToPixels,
   selectionToSubpaths,
+  selectionUncertainty,
   selectionValueAt,
   serializeChannels,
   serializeColorMode,