@pixerate/editor 0.215.0 → 0.217.0

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

@@ -18,3 +18,5 @@ export * from './refine-edits.cjs';
 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

@@ -18,3 +18,5 @@ export * from './refine-edits.js';
 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/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/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.215.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. |
@@ -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.
@@ -64,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`,
@@ -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
@@ -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