@pixerate/editor 0.215.0 → 0.216.0

package/dist/image-editor/index.js

@@ -2609,27 +2609,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 +2786,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;
@@ -2990,6 +2994,135 @@ function regions(a, W, H, b, minArea) {
   };
 }
 
+// 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
+  };
+}
+
 // src/image-editor/selection/path.ts
 function selectionToSubpaths(mask, options = {}) {
   const b = mask.bounds;
@@ -9730,6 +9863,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 +9898,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 +10350,37 @@ 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 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 +13093,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;
@@ -13145,7 +13321,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 +13359,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 +13516,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 +13547,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 +13586,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 +13620,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 +13642,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 = {
@@ -14063,7 +14247,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 +14278,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) };
     }
   };
 }
@@ -22070,6 +22254,7 @@ export {
   createAdjustmentLayer,
   createBlenderScratch,
   createCanvasTextShaper,
+  createGradientSampler,
   createImageCaptureSurface,
   createImageColorTools,
   createImageEditTools,
@@ -22597,6 +22782,7 @@ export {
   selectionToCoverage,
   selectionToPixels,
   selectionToSubpaths,
+  selectionUncertainty,
   selectionValueAt,
   serializeChannels,
   serializeColorMode,

package/dist/image-editor/selection/index.d.cts

@@ -18,3 +18,4 @@ export * from './refine-edits.cjs';
 export * from './select-and-mask.cjs';
 export * from './worker.cjs';
 export * from './inspect.cjs';
+export * from './uncertainty.cjs';

package/dist/image-editor/selection/index.d.ts

@@ -18,3 +18,4 @@ export * from './refine-edits.js';
 export * from './select-and-mask.js';
 export * from './worker.js';
 export * from './inspect.js';
+export * from './uncertainty.js';

package/dist/image-editor/selection/inspect.d.cts

@@ -68,3 +68,12 @@ export declare function inspectMaskEdge(mask: SelectionMask, image: PixelBuffer
     x: number;
     y: number;
 }, options?: InspectMaskEdgeOptions): MaskEdgeReport;
+/**
+ * A cached sampler of the image's edge strength at document pixels: the Sobel magnitude of
+ * alpha-weighted R, G and B, the largest of the three, as a fraction of a full 0–255 step.
+ * Reads clamp at the image's edges. `W` is the canvas width (for the cache key).
+ */
+export declare function createGradientSampler(image: PixelBuffer & {
+    x: number;
+    y: number;
+}, W: number): (x: number, y: number) => number;

package/dist/image-editor/selection/inspect.d.ts

@@ -68,3 +68,12 @@ export declare function inspectMaskEdge(mask: SelectionMask, image: PixelBuffer
     x: number;
     y: number;
 }, options?: InspectMaskEdgeOptions): MaskEdgeReport;
+/**
+ * A cached sampler of the image's edge strength at document pixels: the Sobel magnitude of
+ * alpha-weighted R, G and B, the largest of the three, as a fraction of a full 0–255 step.
+ * Reads clamp at the image's edges. `W` is the canvas width (for the cache key).
+ */
+export declare function createGradientSampler(image: PixelBuffer & {
+    x: number;
+    y: number;
+}, W: number): (x: number, y: number) => number;

package/dist/image-editor/selection/uncertainty.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Where a selection is unsure of itself (a trimap's unknown band): the stretches of its edge that
+ * run where the image shows no edge, widened into a band. The smart selection tools report these
+ * as `uncertainRegions`, so an agent looks at and refines only them (`refine_selection` `regions`).
+ */
+import type { CropBox } from '../types.cjs';
+import { type PixelBuffer, type SelectionMask } from './mask.cjs';
+export interface UncertainRegion {
+    bounds: CropBox;
+    /** Pixels in the unknown band. */
+    area: number;
+    /** 0–1: how strongly the image backs the edge here (low = unsure). */
+    confidence: number;
+}
+export interface SelectionUncertainty {
+    /** The unknown band over the canvas (255 = unsure). */
+    unknown: SelectionMask;
+    /** The least confident regions first (at most `maxRegions`). */
+    regions: UncertainRegion[];
+    /** How many regions there are in all. */
+    count: number;
+    /** 0–1 over the whole edge. */
+    confidence: number;
+}
+export interface SelectionUncertaintyOptions {
+    /** Half-width of the unknown band in px (default 1/200 of the shorter side, at least 2). */
+    band?: number;
+    /** Regions smaller than this many pixels are left out (default 16). */
+    minArea?: number;
+    /** At most this many regions are listed (default 20). */
+    maxRegions?: number;
+}
+/**
+ * The unknown band of `mask` against `image` (RGBA, straight alpha, at `image.x`, `image.y` in
+ * document pixels). An empty selection has no band.
+ */
+export declare function selectionUncertainty(mask: SelectionMask, image: PixelBuffer & {
+    x: number;
+    y: number;
+}, options?: SelectionUncertaintyOptions): SelectionUncertainty;

package/dist/image-editor/selection/uncertainty.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Where a selection is unsure of itself (a trimap's unknown band): the stretches of its edge that
+ * run where the image shows no edge, widened into a band. The smart selection tools report these
+ * as `uncertainRegions`, so an agent looks at and refines only them (`refine_selection` `regions`).
+ */
+import type { CropBox } from '../types.js';
+import { type PixelBuffer, type SelectionMask } from './mask.js';
+export interface UncertainRegion {
+    bounds: CropBox;
+    /** Pixels in the unknown band. */
+    area: number;
+    /** 0–1: how strongly the image backs the edge here (low = unsure). */
+    confidence: number;
+}
+export interface SelectionUncertainty {
+    /** The unknown band over the canvas (255 = unsure). */
+    unknown: SelectionMask;
+    /** The least confident regions first (at most `maxRegions`). */
+    regions: UncertainRegion[];
+    /** How many regions there are in all. */
+    count: number;
+    /** 0–1 over the whole edge. */
+    confidence: number;
+}
+export interface SelectionUncertaintyOptions {
+    /** Half-width of the unknown band in px (default 1/200 of the shorter side, at least 2). */
+    band?: number;
+    /** Regions smaller than this many pixels are left out (default 16). */
+    minArea?: number;
+    /** At most this many regions are listed (default 20). */
+    maxRegions?: number;
+}
+/**
+ * The unknown band of `mask` against `image` (RGBA, straight alpha, at `image.x`, `image.y` in
+ * document pixels). An empty selection has no band.
+ */
+export declare function selectionUncertainty(mask: SelectionMask, image: PixelBuffer & {
+    x: number;
+    y: number;
+}, options?: SelectionUncertaintyOptions): SelectionUncertainty;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.215.0",
+  "version": "0.216.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-image-editor/SKILL.md

@@ -258,7 +258,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `grow_selection` | Select › Grow: add connected pixels within `tolerance` (default 32) of a selected colour; follows colour, not distance. `sample`, `sampleMerged`. Fails when nothing is selected. Returns the summary. |
 | `select_similar` | Select › Similar: add every pixel in the image within `tolerance` of a selected colour, connected or not. Fails when nothing is selected. Returns the summary. |
 | `reselect` | Bring back the last selection `deselect` cleared (one undo step). Fails when there is none. Returns the summary. |
-| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer`, `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), or `new-document` / `new-document-with-mask` (host must open documents; returns `documentId`), with `decontaminate` 0..100 for new layers and documents. `edits` (`quick-select`, `brush`, `lasso`, `object` add/subtract; `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
+| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer`, `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), or `new-document` / `new-document-with-mask` (host must open documents; returns `documentId`), with `decontaminate` 0..100 for new layers and documents. `edits` (`quick-select`, `brush`, `lasso`, `object` add/subtract; `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model; `regions` (rects, e.g. `uncertainRegions` bounds) limits it to those. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
 | `update_adjustment_layer` | Change a layer's `enabled` (false hides it without deleting), `blend`, `opacity` (0..1) or `name` in one undo step. Returns the layer. Its parameters change with `set_adjustments`. Toggle `enabled` to compare a layer's effect before and after. |
 | `move_adjustment_layer` | Move a layer to index `to` (0 = bottom, applied first; past the top means top). Order matters: a curves layer above a hue/saturation layer works on its output. Fails when the layer is already there. Returns the ids bottom to top. |
 | `remove_adjustment_layer` | Delete a layer and its mask. Prefer hiding it with `update_adjustment_layer` when the user may want it back. Returns the remaining ids. |

package/skills/pixerate-image-selection-masking/SKILL.md

@@ -43,7 +43,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 2. **Build it in steps** with `mode`: start with `replace`, `add` what was missed, `subtract`
    what leaked, and `intersect` to limit it to a region (for example `select_rect` around the
    subject).
-   **Check:** `bounds` hug the subject. A bounds as large as the image means a leak.
+   **Check:** `bounds` hug the subject. A bounds as large as the image means a leak. Smart tools
+   return `uncertainRegions` (edge with no image edge under it): look there, refine with `regions`.
 3. **Measure the edge, then look.** `inspect_mask_edge` scores it: `haloScore` ≥ 0.35 is old
    background inside the edge, `edgeAlignment` < 0.5 is off the image's edges, `jaggedness` ≥ 15
    zigzags; it counts `holes` and `islands`, `issues` names fixes, `worst` gives `capture_view` rects.
@@ -210,13 +211,12 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 
 - `get_selection`: empty, bounds, area and percent after every step
 - `select_all`, `deselect`, `invert_selection`: whole-image selections
-- `select_rect`, `select_ellipse`: marquees
+- `select_rect`, `select_ellipse`, `select_line`: marquees, and a single row or column
 - `select_polygon`: the lasso, along a contour; with `snapToEdges`, the Magnetic Lasso
 - `quick_select`: brush strokes that grow out to the region's edges
 - `select_object`: the object in a box or under a point
 - `select_focus_area`: what is in focus
 - `select_sky`: the sky
-- `select_line`: a single row or column
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere
 - `reselect`: undo a deselect