@pixerate/editor 0.197.0 → 0.199.0

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

@@ -30,6 +30,8 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  * - Quick Selection: drag (or click) a brush stroke; on `end` it grows into the region painted on,
  *   out to its edges (async: await {@link settled}). With the New mode and a selection already
  *   there, strokes add, as in Photoshop; Alt subtracts.
+ * - Object Selection: drag a box around an object, or click on it; on `end` the object is
+ *   selected (async: await {@link settled}).
  * - Single row / column: a click selects a 1 px line across the image.
  *
  * Shift adds, Alt subtracts, both intersect (overriding the options bar mode). While dragging,
@@ -54,7 +56,7 @@ export declare class SelectionGesture {
     private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
-    /** Resolves once a Quick Selection stroke has been applied. */
+    /** Resolves once a Quick Selection stroke or an Object Selection has been applied. */
     get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];

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

@@ -30,6 +30,8 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  * - Quick Selection: drag (or click) a brush stroke; on `end` it grows into the region painted on,
  *   out to its edges (async: await {@link settled}). With the New mode and a selection already
  *   there, strokes add, as in Photoshop; Alt subtracts.
+ * - Object Selection: drag a box around an object, or click on it; on `end` the object is
+ *   selected (async: await {@link settled}).
  * - Single row / column: a click selects a 1 px line across the image.
  *
  * Shift adds, Alt subtracts, both intersect (overriding the options bar mode). While dragging,
@@ -54,7 +56,7 @@ export declare class SelectionGesture {
     private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
-    /** Resolves once a Quick Selection stroke has been applied. */
+    /** Resolves once a Quick Selection stroke or an Object Selection has been applied. */
     get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];

package/dist/image-editor/selection/segment/grabcut.d.cts

@@ -0,0 +1,63 @@
+/**
+ * Object Selection: GrabCut (Rother, Kolmogorov & Blake, 2004) from a box drawn around an object
+ * or a click on it. Two colour models, mixtures of five Gaussians each, are fitted to what is
+ * currently inside and outside the object; a graph cut relabels every pixel by them and by the
+ * edges between neighbours; the two steps repeat until the labels settle. It runs on the reduced
+ * copy of the image and is scaled back up with an anti-aliased edge, as Quick Selection is.
+ */
+import type { CropBox, ImagePoint } from '../../types.cjs';
+import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+import { type Rect, type WorkImage } from './work.cjs';
+/** A mixture of {@link K} full-covariance Gaussians over RGB. */
+export declare class ColorGmm {
+    private readonly logWeight;
+    private readonly mean;
+    /** Inverse covariances, row-major 3 × 3. */
+    private readonly inv;
+    /** ln(weight) − ½ ln((2π)³ |Σ|) per component; −∞ for an empty one. */
+    private readonly logNorm;
+    /** Fits the components to the pixels `ids` of `rgb`, each in component `comp[id]`. */
+    fit(rgb: Float32Array, ids: ArrayLike<number>, comp: Uint8Array): void;
+    /** ln p(colour | component k), up to the shared constant. */
+    private componentLog;
+    /** −ln p(colour) under the mixture (large for colours the model hasn't seen). */
+    cost(r: number, g: number, b: number): number;
+    /** The component most likely to have produced the colour. */
+    nearest(r: number, g: number, b: number): number;
+}
+/** Pixels fixed to one side, and a starting guess, over a window of the work image. */
+export interface GrabCutSetup {
+    roi: Rect;
+    /** Per window pixel: 1 = starts inside the object. */
+    initial: Uint8Array;
+    /** Per window pixel: 1 = fixed outside. */
+    hardBg: Uint8Array;
+    /** Per window pixel: 1 = fixed inside. */
+    hardFg: Uint8Array | null;
+}
+/** GrabCut over the setup's window; returns 1 for the object per window pixel. */
+export declare function grabCutLabels(work: WorkImage, setup: GrabCutSetup, iterations: number): Uint8Array;
+/**
+ * Keeps the object's main parts: the pieces (4-connected) holding `seed` (window index), or
+ * without one, every piece at least a fifth the size of the largest.
+ */
+export declare function keepMainPieces(label: Uint8Array, rw: number, rh: number, seed: number | null): void;
+export interface ObjectSelectionOptions {
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+    /** Most rounds of fitting and cutting (default 5; it stops early once the labels settle). */
+    iterations?: number;
+}
+/** What to select: a box around the object, or a point on it (natural pixels). */
+export type ObjectTarget = {
+    rect: CropBox;
+} | {
+    point: ImagePoint;
+};
+/**
+ * Object Selection over `pixels`: the object in `target.rect` (everything outside the box is
+ * background), or the object under `target.point` (searched for in a window around it that grows
+ * while the object reaches its border). Returns a selection of the whole image, empty when
+ * nothing stands out.
+ */
+export declare function selectObjectIn(pixels: PixelBuffer, target: ObjectTarget, options?: ObjectSelectionOptions): SelectionMask;

package/dist/image-editor/selection/segment/grabcut.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Object Selection: GrabCut (Rother, Kolmogorov & Blake, 2004) from a box drawn around an object
+ * or a click on it. Two colour models, mixtures of five Gaussians each, are fitted to what is
+ * currently inside and outside the object; a graph cut relabels every pixel by them and by the
+ * edges between neighbours; the two steps repeat until the labels settle. It runs on the reduced
+ * copy of the image and is scaled back up with an anti-aliased edge, as Quick Selection is.
+ */
+import type { CropBox, ImagePoint } from '../../types.js';
+import { type PixelBuffer, type SelectionMask } from '../mask.js';
+import { type Rect, type WorkImage } from './work.js';
+/** A mixture of {@link K} full-covariance Gaussians over RGB. */
+export declare class ColorGmm {
+    private readonly logWeight;
+    private readonly mean;
+    /** Inverse covariances, row-major 3 × 3. */
+    private readonly inv;
+    /** ln(weight) − ½ ln((2π)³ |Σ|) per component; −∞ for an empty one. */
+    private readonly logNorm;
+    /** Fits the components to the pixels `ids` of `rgb`, each in component `comp[id]`. */
+    fit(rgb: Float32Array, ids: ArrayLike<number>, comp: Uint8Array): void;
+    /** ln p(colour | component k), up to the shared constant. */
+    private componentLog;
+    /** −ln p(colour) under the mixture (large for colours the model hasn't seen). */
+    cost(r: number, g: number, b: number): number;
+    /** The component most likely to have produced the colour. */
+    nearest(r: number, g: number, b: number): number;
+}
+/** Pixels fixed to one side, and a starting guess, over a window of the work image. */
+export interface GrabCutSetup {
+    roi: Rect;
+    /** Per window pixel: 1 = starts inside the object. */
+    initial: Uint8Array;
+    /** Per window pixel: 1 = fixed outside. */
+    hardBg: Uint8Array;
+    /** Per window pixel: 1 = fixed inside. */
+    hardFg: Uint8Array | null;
+}
+/** GrabCut over the setup's window; returns 1 for the object per window pixel. */
+export declare function grabCutLabels(work: WorkImage, setup: GrabCutSetup, iterations: number): Uint8Array;
+/**
+ * Keeps the object's main parts: the pieces (4-connected) holding `seed` (window index), or
+ * without one, every piece at least a fifth the size of the largest.
+ */
+export declare function keepMainPieces(label: Uint8Array, rw: number, rh: number, seed: number | null): void;
+export interface ObjectSelectionOptions {
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+    /** Most rounds of fitting and cutting (default 5; it stops early once the labels settle). */
+    iterations?: number;
+}
+/** What to select: a box around the object, or a point on it (natural pixels). */
+export type ObjectTarget = {
+    rect: CropBox;
+} | {
+    point: ImagePoint;
+};
+/**
+ * Object Selection over `pixels`: the object in `target.rect` (everything outside the box is
+ * background), or the object under `target.point` (searched for in a window around it that grows
+ * while the object reaches its border). Returns a selection of the whole image, empty when
+ * nothing stands out.
+ */
+export declare function selectObjectIn(pixels: PixelBuffer, target: ObjectTarget, options?: ObjectSelectionOptions): SelectionMask;

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

@@ -1,2 +1,5 @@
 export * from './maxflow.cjs';
+export * from './work.cjs';
 export * from './quick.cjs';
+export * from './grabcut.cjs';
+export * from './subject.cjs';

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

@@ -1,2 +1,5 @@
 export * from './maxflow.js';
+export * from './work.js';
 export * from './quick.js';
+export * from './grabcut.js';
+export * from './subject.js';

package/dist/image-editor/selection/segment/quick.d.cts

@@ -9,25 +9,6 @@
  */
 import type { ImagePoint } from '../../types.cjs';
 import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
-/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
-export interface WorkImage {
-    /** Natural size of the image it was made from. */
-    sourceWidth: number;
-    sourceHeight: number;
-    width: number;
-    height: number;
-    /** Reduced pixels per natural pixel (≤ 1). */
-    scale: number;
-    /** RGB, 3 values per pixel. */
-    rgb: Float32Array;
-}
-/** Long side of the work image (the issue's 512²). */
-export declare const WORK_SIZE = 512;
-/**
- * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
- * composited over white). Cached per pixel buffer.
- */
-export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
 export interface QuickSelectOptions {
     /** Brush diameter in natural pixels (default 30). */
     size?: number;

package/dist/image-editor/selection/segment/quick.d.ts

@@ -9,25 +9,6 @@
  */
 import type { ImagePoint } from '../../types.js';
 import { type PixelBuffer, type SelectionMask } from '../mask.js';
-/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
-export interface WorkImage {
-    /** Natural size of the image it was made from. */
-    sourceWidth: number;
-    sourceHeight: number;
-    width: number;
-    height: number;
-    /** Reduced pixels per natural pixel (≤ 1). */
-    scale: number;
-    /** RGB, 3 values per pixel. */
-    rgb: Float32Array;
-}
-/** Long side of the work image (the issue's 512²). */
-export declare const WORK_SIZE = 512;
-/**
- * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
- * composited over white). Cached per pixel buffer.
- */
-export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
 export interface QuickSelectOptions {
     /** Brush diameter in natural pixels (default 30). */
     size?: number;

package/dist/image-editor/selection/segment/subject.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Select Subject without a segmentation model: the most salient subject, found classically.
+ *
+ * 1. SLIC superpixels (Achanta et al., 2012) group the reduced image into a few hundred patches of
+ *    similar colour.
+ * 2. Each patch's saliency is how unlike the image's border it is (the border is mostly
+ *    background), times how much it contrasts with the patches around it (region contrast, Cheng
+ *    et al., 2015), times a mild preference for the centre.
+ * 3. Otsu's threshold splits the patches into a first guess at the subject.
+ * 4. GrabCut refines that guess along the image's edges, with the clearly-background border fixed.
+ *
+ * It cannot tell which object a description names: it selects what stands out.
+ */
+import type { PixelBuffer, SelectionMask } from '../mask.cjs';
+import { type WorkImage } from './work.cjs';
+export interface Superpixels {
+    /** Superpixel of each work pixel. */
+    label: Int32Array;
+    count: number;
+    /** Mean L*a*b* per superpixel, 3 values each. */
+    lab: Float64Array;
+    /** Mean position per superpixel, in work pixels, 2 values each. */
+    centre: Float64Array;
+    size: Int32Array;
+}
+/** SLIC superpixels of the work image: about `target` of them, `compactness` 10 (L*a*b* units). */
+export declare function slicSuperpixels(work: WorkImage, target?: number, compactness?: number, rounds?: number): Superpixels;
+/** Saliency 0..1 of each superpixel (see the module comment). */
+export declare function superpixelSaliency(sp: Superpixels, width: number, height: number): Float64Array;
+/** Otsu's threshold of `values` (0..1) weighted by `weights`. */
+export declare function otsuThreshold(values: ArrayLike<number>, weights: ArrayLike<number>): number;
+/** What {@link findSubject} found. */
+export interface FoundSubject {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/**
+ * The most salient subject of `pixels` as a selection of the whole image (empty, with a reason,
+ * when nothing stands out from the background).
+ */
+export declare function findSubject(pixels: PixelBuffer, options?: {
+    enhanceEdge?: boolean;
+}): FoundSubject;

package/dist/image-editor/selection/segment/subject.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Select Subject without a segmentation model: the most salient subject, found classically.
+ *
+ * 1. SLIC superpixels (Achanta et al., 2012) group the reduced image into a few hundred patches of
+ *    similar colour.
+ * 2. Each patch's saliency is how unlike the image's border it is (the border is mostly
+ *    background), times how much it contrasts with the patches around it (region contrast, Cheng
+ *    et al., 2015), times a mild preference for the centre.
+ * 3. Otsu's threshold splits the patches into a first guess at the subject.
+ * 4. GrabCut refines that guess along the image's edges, with the clearly-background border fixed.
+ *
+ * It cannot tell which object a description names: it selects what stands out.
+ */
+import type { PixelBuffer, SelectionMask } from '../mask.js';
+import { type WorkImage } from './work.js';
+export interface Superpixels {
+    /** Superpixel of each work pixel. */
+    label: Int32Array;
+    count: number;
+    /** Mean L*a*b* per superpixel, 3 values each. */
+    lab: Float64Array;
+    /** Mean position per superpixel, in work pixels, 2 values each. */
+    centre: Float64Array;
+    size: Int32Array;
+}
+/** SLIC superpixels of the work image: about `target` of them, `compactness` 10 (L*a*b* units). */
+export declare function slicSuperpixels(work: WorkImage, target?: number, compactness?: number, rounds?: number): Superpixels;
+/** Saliency 0..1 of each superpixel (see the module comment). */
+export declare function superpixelSaliency(sp: Superpixels, width: number, height: number): Float64Array;
+/** Otsu's threshold of `values` (0..1) weighted by `weights`. */
+export declare function otsuThreshold(values: ArrayLike<number>, weights: ArrayLike<number>): number;
+/** What {@link findSubject} found. */
+export interface FoundSubject {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/**
+ * The most salient subject of `pixels` as a selection of the whole image (empty, with a reason,
+ * when nothing stands out from the background).
+ */
+export declare function findSubject(pixels: PixelBuffer, options?: {
+    enhanceEdge?: boolean;
+}): FoundSubject;

package/dist/image-editor/selection/segment/work.d.cts

@@ -0,0 +1,54 @@
+/**
+ * The reduced copy of the image the graph segmentations (Quick Selection, Object Selection) work
+ * on, and scaling their result back up to the image with an anti-aliased edge.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
+export interface WorkImage {
+    /** Natural size of the image it was made from. */
+    sourceWidth: number;
+    sourceHeight: number;
+    width: number;
+    height: number;
+    /** Reduced pixels per natural pixel (≤ 1). */
+    scale: number;
+    /** RGB, 3 values per pixel. */
+    rgb: Float32Array;
+}
+/** Long side of the work image (the issue's 512²). */
+export declare const WORK_SIZE = 512;
+/**
+ * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
+ * composited over white). Cached per pixel buffer.
+ */
+export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
+/** Edge weight between neighbours: high for similar colours, low across an edge (GrabCut's γ, β). */
+export declare const GAMMA = 50;
+/**
+ * Capacities are whole multiples of 1 / UNITS: in floating point, residuals that should reach
+ * zero are left a hair above it and max-flow then pushes thousands of near-empty paths.
+ */
+export declare const UNITS = 64;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Capacities of the edges between neighbours in `roi` (to the right and below, indexed by the
+ * pixel in the window): high between similar colours, low across an edge, GrabCut's
+ * γ·exp(−β‖Δc‖²) with β from the window's mean squared difference, in whole {@link UNITS}.
+ */
+export declare function smoothnessWeights(work: WorkImage, roi: Rect): {
+    right: Float64Array;
+    down: Float64Array;
+};
+/** A 3 × 3 box blur of `src` (w × h), `passes` times. */
+export declare function boxBlur(src: Float32Array, w: number, h: number, passes: number): Float32Array;
+/**
+ * The region of the work-image `label` over `roi` at natural size: inside and outside as they
+ * are, and the pixels along the edge anti-aliased by where their colour lies between the region's
+ * colour and the surroundings' just either side.
+ */
+export declare function upscaleRegion(work: WorkImage, pixels: PixelBuffer, roi: Rect, label: Uint8Array, enhance: boolean): SelectionMask;

package/dist/image-editor/selection/segment/work.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The reduced copy of the image the graph segmentations (Quick Selection, Object Selection) work
+ * on, and scaling their result back up to the image with an anti-aliased edge.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.js';
+/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
+export interface WorkImage {
+    /** Natural size of the image it was made from. */
+    sourceWidth: number;
+    sourceHeight: number;
+    width: number;
+    height: number;
+    /** Reduced pixels per natural pixel (≤ 1). */
+    scale: number;
+    /** RGB, 3 values per pixel. */
+    rgb: Float32Array;
+}
+/** Long side of the work image (the issue's 512²). */
+export declare const WORK_SIZE = 512;
+/**
+ * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
+ * composited over white). Cached per pixel buffer.
+ */
+export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
+/** Edge weight between neighbours: high for similar colours, low across an edge (GrabCut's γ, β). */
+export declare const GAMMA = 50;
+/**
+ * Capacities are whole multiples of 1 / UNITS: in floating point, residuals that should reach
+ * zero are left a hair above it and max-flow then pushes thousands of near-empty paths.
+ */
+export declare const UNITS = 64;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Capacities of the edges between neighbours in `roi` (to the right and below, indexed by the
+ * pixel in the window): high between similar colours, low across an edge, GrabCut's
+ * γ·exp(−β‖Δc‖²) with β from the window's mean squared difference, in whole {@link UNITS}.
+ */
+export declare function smoothnessWeights(work: WorkImage, roi: Rect): {
+    right: Float64Array;
+    down: Float64Array;
+};
+/** A 3 × 3 box blur of `src` (w × h), `passes` times. */
+export declare function boxBlur(src: Float32Array, w: number, h: number, passes: number): Float32Array;
+/**
+ * The region of the work-image `label` over `roi` at natural size: inside and outside as they
+ * are, and the pixels along the edge anti-aliased by where their colour lies between the region's
+ * colour and the surroundings' just either side.
+ */
+export declare function upscaleRegion(work: WorkImage, pixels: PixelBuffer, roi: Rect, label: Uint8Array, enhance: boolean): SelectionMask;

package/dist/image-editor/selection/tool-options.d.cts

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.cjs';
 import type { ColorDistance, ColorRangePreset } from './wand.cjs';
 import type { RefineEdgeParams } from './refine.cjs';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'object' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -43,6 +43,10 @@ export interface SelectionToolOptions {
     quickSampleAll?: boolean;
     /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
     quickEnhance?: boolean;
+    /** Object Selection: read every layer (default true) or only the active pixel layer. */
+    objectSampleAll?: boolean;
+    /** Object Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    objectEnhance?: boolean;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

package/dist/image-editor/selection/tool-options.d.ts

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.js';
 import type { ColorDistance, ColorRangePreset } from './wand.js';
 import type { RefineEdgeParams } from './refine.js';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'object' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -43,6 +43,10 @@ export interface SelectionToolOptions {
     quickSampleAll?: boolean;
     /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
     quickEnhance?: boolean;
+    /** Object Selection: read every layer (default true) or only the active pixel layer. */
+    objectSampleAll?: boolean;
+    /** Object Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    objectEnhance?: boolean;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

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

@@ -23,8 +23,8 @@ export interface ImageSegmentationToolProviderOptions {
 /** The `select_subject` tool: Select › Subject through the controller's segmentation provider. */
 export declare function createImageSubjectSelectionTool(controller: ImageEditorController): AgentTool;
 /**
- * Agent tools that need the controller's segmentation provider (`select_subject`). The list is
- * empty while no provider is set, so a host can register this once and the tool appears when a
- * model is available.
+ * @deprecated `select_subject` is now one of the selection tools of `createImageEditorToolProvider`
+ * (it works without a model too), so this provider lists no tools; it stays so hosts that register
+ * it keep working. Remove it from your registry.
  */
 export declare function createImageSegmentationToolProvider(controller: ImageEditorController, options?: ImageSegmentationToolProviderOptions): AgentToolProvider;

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

@@ -23,8 +23,8 @@ export interface ImageSegmentationToolProviderOptions {
 /** The `select_subject` tool: Select › Subject through the controller's segmentation provider. */
 export declare function createImageSubjectSelectionTool(controller: ImageEditorController): AgentTool;
 /**
- * Agent tools that need the controller's segmentation provider (`select_subject`). The list is
- * empty while no provider is set, so a host can register this once and the tool appears when a
- * model is available.
+ * @deprecated `select_subject` is now one of the selection tools of `createImageEditorToolProvider`
+ * (it works without a model too), so this provider lists no tools; it stays so hosts that register
+ * it keep working. Remove it from your registry.
  */
 export declare function createImageSegmentationToolProvider(controller: ImageEditorController, options?: ImageSegmentationToolProviderOptions): AgentToolProvider;

package/package.json

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

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

@@ -221,7 +221,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. |
 | `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 (only when the host has a segmentation model): `target` describes what to select ("the dog", "the sky"); an AI model finds the matching objects and selects their outlines, combined by `mode`. `maxSegments` 1 for a single subject. Returns the selection and `found` (label, bounds per object); nothing found leaves the selection unchanged. |
+| `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. |
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
 | `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, `bitDepth` (8, 16 or 32), the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
@@ -253,6 +253,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `select_ellipse` | Elliptical marquee inscribed in `x`, `y`, `width`, `height`; same options. A feathered ellipse makes a vignette. Returns the summary. |
 | `select_line` | Single row or column marquee: `orientation` `row` (at y) or `column` (at x), `position` in natural px, `mode`. A 1 px line across the image. Returns the summary. |
 | `quick_select` | Quick Selection: `strokes` (brush paths of `{x, y}`), `size` (diameter, default 30), `mode`, `sampleAllLayers`, `enhanceEdge`. Each stroke grows out to its region's edges; with `replace` the first replaces and the rest add. Paint inside the area, then check and fix with `add` / `subtract` strokes. Returns the summary. |
+| `select_object` | Object Selection (GrabCut): `rect` (a box around the object) or `point` (on it), `mode`, `sampleAllLayers`, `enhanceEdge`. Outside the box is background. Make the box a little larger than the object. Returns the summary. |
 | `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`; `snapToEdges: {width, contrast}` makes it the Magnetic Lasso (points snap to edges, the outline follows them). Trace a subject's contour, not its box. Returns the summary (plus `outlinePoints` when snapped). |
 | `magic_wand` | Select similar colour from `x`, `y`: `tolerance` 0..255 (default 32), `contiguous` (default true), `distance` `rgb` or `perceptual`, `sampleMerged`, `sample` (`composite` or `active-layer`), `mode`, `feather`. For flat backdrops and solid colours. Returns the summary. |
 | `select_color_range` | Color Range, soft: `samples` (`[{color, x?, y?}]`) or a `preset` (reds … magentas, highlights, midtones, shadows, skinTones); `fuzziness` (samples 0..200, default 40; tone presets' falloff, default 20), `localized` px radius around positioned samples, `invert`, `sample`, `mode`, `feather`. Returns the summary. |

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

@@ -96,7 +96,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | Subject | Method |
 | --- | --- |
 | Geometric areas: a frame, a screen, a band | `select_rect` / `select_ellipse`, with `feather` for soft transitions |
-| A subject with a clear outline (product, person, animal) | `select_subject` if the host has a model; else `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
+| One object among others, where you can box it (a product on a table, a person in a group) | `select_object` with a `rect` a little larger than the object on every side; then `quick_select` add / subtract strokes for what it missed |
+| A subject with a clear outline (product, person, animal) | `select_subject` (with a host model, by description; without one it takes whatever stands out most, so check `method` and the result); else `select_object` around it, or `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
 | An area or subject that differs from its surroundings (a shirt, a sky, a car) | `quick_select` with strokes painted inside it, away from the edge (`size` a fraction of its width); `add` / `subtract` strokes where it fell short or leaked |
 | A low-contrast or busy outline the edges don't follow | `select_polygon` without `snapToEdges`, along the contour (20–60 points) |
 | Flat backdrop or solid colour (studio white, green screen, sky without clouds) | `magic_wand` on the backdrop (`tolerance` 20–40; `distance: "perceptual"` for gradients), then `invert_selection` |
@@ -157,6 +158,13 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
   30–60), check `percent`, and grow with `mode: "add"`.
 - **Box instead of outline:** `select_rect` around a subject masks its background too. Trace
   the contour.
+- **Select Subject without a model picks the wrong thing:** it selects what stands out most from
+  the image's border, which may be a bright sign rather than the person. When `method` is
+  `saliency`, check with `capture_view`; if it's wrong, use `select_object` with a box.
+- **Object Selection takes part of the background:** inside the box, anything that looks
+  unlike the background around the box counts as the object. Tighten the box, or `subtract` a
+  `quick_select` stroke on the extra. With `point`, it may stop at an inner edge of a
+  multicoloured object: use a box instead.
 - **Quick Selection spills over a weak edge:** a stroke grows into neighbouring areas of a
   similar colour. Paint smaller strokes further from the edge, then a `subtract` stroke on the
   spill. Strokes near an edge also pull in the other side.
@@ -194,6 +202,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `select_rect`, `select_ellipse`: marquees
 - `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_line`: a single row or column
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere
@@ -206,7 +215,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `fill_pixels`, `blur_stroke`: fill or soften the selection in Quick Mask mode
 - `magic_wand`: similar colour from a seed
 - `select_color_range`: colour samples, hue, tone and skin presets
-- `select_subject`: a subject by description (needs a host model)
+- `select_subject`: a subject by description with a host model; without one, the most salient subject
 - `load_selection_from_image`: AI or saved mattes
 - `load_selection_from_mask`: a layer mask back to a selection
 - `set_selection_display`: ants, Quick Mask tint or hidden