@pixerate/editor 0.216.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) {
@@ -2987,10 +3113,10 @@ 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))
   };
 }
 
@@ -10381,6 +10507,65 @@ var ImageEditorController = class {
     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);
@@ -13146,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",
@@ -14200,6 +14444,7 @@ function createImageSelectionTools(controller) {
   return [
     getSelection,
     inspectEdge,
+    compareTool,
     selectAll,
     deselect,
     invert2,
@@ -22227,6 +22472,7 @@ export {
   colorRange,
   colorRangePreset,
   combineSelections,
+  compareSelectionMasks,
   compileAdjustmentLayer,
   componentPath,
   componentsCoverage,
@@ -22772,6 +23018,7 @@ export {
   selectObjectIn,
   selectSimilar,
   selectionArea,
+  selectionDiffPixels,
   selectionFromCoverage,
   selectionFromPixels,
   selectionFromRegion,

package/dist/image-editor/renderer.d.cts

@@ -176,6 +176,7 @@ export declare class ImageEditorRenderer {
     private applyPost;
     private publishHistogram;
     private quickMaskCache;
+    private diffCache;
     private outlineCache;
     private emptyMaskCache;
     /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
@@ -190,6 +191,7 @@ export declare class ImageEditorRenderer {
     /** A channel's tint (colour, opacity, masked or selected area), drawn in natural image space. */
     private drawMaskOverlay;
     /** Rubylith over the unselected area, drawn in natural image space. */
+    private drawSelectionDiff;
     private drawQuickMask;
     /**
      * Marching ants: a white line under a black dashed one, one screen pixel wide. `scale` is

package/dist/image-editor/renderer.d.ts

@@ -176,6 +176,7 @@ export declare class ImageEditorRenderer {
     private applyPost;
     private publishHistogram;
     private quickMaskCache;
+    private diffCache;
     private outlineCache;
     private emptyMaskCache;
     /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
@@ -190,6 +191,7 @@ export declare class ImageEditorRenderer {
     /** A channel's tint (colour, opacity, masked or selected area), drawn in natural image space. */
     private drawMaskOverlay;
     /** Rubylith over the unselected area, drawn in natural image space. */
+    private drawSelectionDiff;
     private drawQuickMask;
     /**
      * Marching ants: a white line under a black dashed one, one screen pixel wide. `scale` is

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

@@ -0,0 +1,59 @@
+/**
+ * What changed between two selections (`compare_selections`): the area added and removed, where,
+ * and how much they overlap (IoU), so an agent can check that a modify or refine step did what it
+ * meant to and a person can see it as a two-colour overlay.
+ */
+import type { CropBox } from '../types.cjs';
+import { type SelectionMask } from './mask.cjs';
+/** One piece of added or removed area. */
+export interface SelectionDiffRegion {
+    area: number;
+    bounds: CropBox;
+}
+export interface SelectionDiffSide {
+    /** Pixels at least half selected. */
+    area: number;
+    bounds: CropBox | null;
+}
+export interface SelectionDiff {
+    a: SelectionDiffSide;
+    b: SelectionDiffSide;
+    /** Selected in b but not in a: area, and the largest pieces (at most `maxRegions`). */
+    added: {
+        area: number;
+        count: number;
+        regions: SelectionDiffRegion[];
+    };
+    /** Selected in a but not in b. */
+    removed: {
+        area: number;
+        count: number;
+        regions: SelectionDiffRegion[];
+    };
+    /** Intersection over union, 0–1 (1 when both are empty). */
+    iou: number;
+    /** Σ |coverage b − coverage a| in pixels: also counts edges that only softened or hardened. */
+    coverageChange: number;
+    /** Every pixel's coverage is the same. */
+    identical: boolean;
+}
+export interface CompareSelectionsOptions {
+    /** Pieces smaller than this many pixels are counted in the area but not listed (default 4). */
+    minArea?: number;
+    /** At most this many pieces are listed per side (default 10). */
+    maxRegions?: number;
+}
+/**
+ * Compares selection `a` (before) with `b` (after) over a `width × height` canvas; `null` is
+ * nothing selected. Area, pieces and IoU are judged at half coverage. Also returns the added and
+ * removed masks for an overlay.
+ */
+export declare function compareSelectionMasks(a: SelectionMask | null, b: SelectionMask | null, width: number, height: number, options?: CompareSelectionsOptions): SelectionDiff & {
+    addedMask: SelectionMask;
+    removedMask: SelectionMask;
+};
+/**
+ * The diff overlay's RGBA: added area tinted green, removed area red, the rest transparent
+ * (`width × height`, the masks' size).
+ */
+export declare function selectionDiffPixels(added: SelectionMask, removed: SelectionMask): Uint8ClampedArray;

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

@@ -0,0 +1,59 @@
+/**
+ * What changed between two selections (`compare_selections`): the area added and removed, where,
+ * and how much they overlap (IoU), so an agent can check that a modify or refine step did what it
+ * meant to and a person can see it as a two-colour overlay.
+ */
+import type { CropBox } from '../types.js';
+import { type SelectionMask } from './mask.js';
+/** One piece of added or removed area. */
+export interface SelectionDiffRegion {
+    area: number;
+    bounds: CropBox;
+}
+export interface SelectionDiffSide {
+    /** Pixels at least half selected. */
+    area: number;
+    bounds: CropBox | null;
+}
+export interface SelectionDiff {
+    a: SelectionDiffSide;
+    b: SelectionDiffSide;
+    /** Selected in b but not in a: area, and the largest pieces (at most `maxRegions`). */
+    added: {
+        area: number;
+        count: number;
+        regions: SelectionDiffRegion[];
+    };
+    /** Selected in a but not in b. */
+    removed: {
+        area: number;
+        count: number;
+        regions: SelectionDiffRegion[];
+    };
+    /** Intersection over union, 0–1 (1 when both are empty). */
+    iou: number;
+    /** Σ |coverage b − coverage a| in pixels: also counts edges that only softened or hardened. */
+    coverageChange: number;
+    /** Every pixel's coverage is the same. */
+    identical: boolean;
+}
+export interface CompareSelectionsOptions {
+    /** Pieces smaller than this many pixels are counted in the area but not listed (default 4). */
+    minArea?: number;
+    /** At most this many pieces are listed per side (default 10). */
+    maxRegions?: number;
+}
+/**
+ * Compares selection `a` (before) with `b` (after) over a `width × height` canvas; `null` is
+ * nothing selected. Area, pieces and IoU are judged at half coverage. Also returns the added and
+ * removed masks for an overlay.
+ */
+export declare function compareSelectionMasks(a: SelectionMask | null, b: SelectionMask | null, width: number, height: number, options?: CompareSelectionsOptions): SelectionDiff & {
+    addedMask: SelectionMask;
+    removedMask: SelectionMask;
+};
+/**
+ * The diff overlay's RGBA: added area tinted green, removed area red, the rest transparent
+ * (`width × height`, the masks' size).
+ */
+export declare function selectionDiffPixels(added: SelectionMask, removed: SelectionMask): Uint8ClampedArray;

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

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

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

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

package/dist/image-editor/types.d.cts

@@ -319,6 +319,15 @@ export interface ImageEditorState {
      * growing as the brush moves). View state: not an edit, not in history, not saved.
      */
     selectionPreview?: SelectionMask | null;
+    /**
+     * `compare_selections`' overlay: the added area tinted green, the removed red. Shown while the
+     * selection is still `selection` (any change hides it). View state: not in history, not saved.
+     */
+    selectionDiff?: {
+        added: SelectionMask;
+        removed: SelectionMask;
+        selection: SelectionMask | null;
+    } | null;
     /** Quick Mask view: tint the unselected area instead of drawing marching ants (view state). */
     quickMask?: boolean;
     /** How the canvas shows the selection (view state; `quickMask` mirrors `'quickMask'`). */

package/dist/image-editor/types.d.ts

@@ -319,6 +319,15 @@ export interface ImageEditorState {
      * growing as the brush moves). View state: not an edit, not in history, not saved.
      */
     selectionPreview?: SelectionMask | null;
+    /**
+     * `compare_selections`' overlay: the added area tinted green, the removed red. Shown while the
+     * selection is still `selection` (any change hides it). View state: not in history, not saved.
+     */
+    selectionDiff?: {
+        added: SelectionMask;
+        removed: SelectionMask;
+        selection: SelectionMask | null;
+    } | null;
     /** Quick Mask view: tint the unselected area instead of drawing marching ants (view state). */
     quickMask?: boolean;
     /** How the canvas shows the selection (view state; `quickMask` mirrors `'quickMask'`). */

package/package.json

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

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

@@ -120,8 +120,7 @@ Keep outlines as paths (`make_work_path`, `add_path`) and edit their anchors: se
 
 ### Colour management
 
-The working space, Assign / Convert to Profile with intents, soft proofing with a gamut warning
-and colour conversions for print briefs: read [references/color-management.md](references/color-management.md).
+Working space, profiles, soft proofing and print conversions: read [references/color-management.md](references/color-management.md).
 ### Retouching
 
 Clone Stamp, Healing Brush, Spot Healing, Smudge, Dodge, Burn, Sponge, Blur, Sharpen and the
@@ -209,6 +208,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `list_controls` | Get every base control (id, label, section, min, max, step, default, `requiresProcess`), each layer kind's settable controls (plus `opacity`), the blend mode ids and the `layers.<layerId>.<controlId>` path format. Call once per session before writing. |
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
 | `inspect_mask_edge` | Measure an edge without looking: the selection (default) or a layer's `layer-mask` / `vector-mask` (`layerId`). Returns `haloScore`, `edgeAlignment`, `jaggedness`, `softFraction`, `holes`, `islands`, `worst` regions for `capture_view` and `issues` with fixes. Inspect, fix, inspect again (see `pixerate-image-selection-masking`). |
+| `compare_selections` | What changed between two selections: `a` (default the one before the last undo step) and `b` (default current), each `selection`, `history` (`steps`), `channel` or a layer's `layer-mask` / `vector-mask`. Returns `added` / `removed` (area, largest pieces with bounds), `iou` and `identical`; `show` tints the change on the canvas. Check every modify or refine step. |
 | `list_channels` | Read the alpha channels (saved selections): id, name, bounds, percent, overlay and visibility, and whether Quick Mask mode is on. |
 | `select_subject` | Select › Subject. With a host segmentation model, `target` describes what to select ("the dog", "the sky") and the model's outlines are selected (`maxSegments` 1 for one). Without one, the subject that stands out most is found classically; `target` can't choose it (`method: "saliency"`, `note`). Combined by `mode`. Returns the selection, `found` (label, bounds) and `method`; nothing found leaves the selection unchanged. |
 | `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `shape`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`; shapes a `shape` summary of component ops and kinds and paint types, and `annotation` when migrated from one), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |

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

@@ -65,8 +65,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
      can open the same edits in the workspace. With a host model, `refineMode: "object"`
      refines from the model's outline.
    - `shiftEdge` −10..−30 % tightens a refined edge that picked up background.
-   **Check:** `percent` changed by roughly what you intended (a few percent at most for a
-   cleanup).
+   **Check:** `compare_selections` after the step: `added` / `removed` are what you meant and
+   `iou` stays near 1 for a cleanup (it tints the change on the canvas).
 5. **Output.** Choose by goal:
    - A local adjustment: `add_adjustment_layer` while the selection is active (it is masked
      by it), or `apply_selection_as_mask` with `kind`. Filters (`apply_effect`,
@@ -239,7 +239,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `modify_selection`: expand, contract, feather, border, smooth
 - `refine_selection`: snap the edge to the image
 - `transform_selection`: move or scale the outline only
-- `inspect_mask_edge`: measured halo, alignment, jaggedness, softness, holes and islands of an edge
+- `inspect_mask_edge`, `compare_selections`: measure an edge (halo, alignment, jaggedness, holes, islands) and what a step changed (IoU)
 - `set_edge_decontamination`, `set_edge_despill`, `set_edge_ambient`, `get_edge_color`: live edge colour on a masked cutout
 - `capture_view`, `render_preview`: look at the edge at pixel level; check the result
 - `apply_selection_as_mask`: a masked adjustment layer in one step