@pixerate/editor 0.213.0 → 0.214.0

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

@@ -0,0 +1,70 @@
+/**
+ * A measured report on a mask's edge (`inspect_mask_edge`), so an agent can check a selection or
+ * a mask without looking at it: halo (old background left just inside the edge), how much of the
+ * edge sits on the image's own edges, how jagged the outline is, how soft it is, holes and stray
+ * islands, and the worst places to look at. Read-only; works in the mask's bounds.
+ */
+import type { CropBox } from '../types.cjs';
+import type { PixelBuffer, SelectionMask } from './mask.cjs';
+export interface InspectMaskEdgeOptions {
+    /** Holes and islands smaller than this many pixels are left out (default 16). */
+    minArea?: number;
+}
+/** A hole or island: its area in pixels and bounds. */
+export interface MaskRegion {
+    area: number;
+    bounds: CropBox;
+}
+export interface MaskEdgeReport {
+    /** Pixels at least half covered. */
+    area: number;
+    bounds: CropBox;
+    /** Pixels along the edge (inside, at least half covered, beside one less than half). */
+    edgeLength: number;
+    /**
+     * 0–1: how close the colour just inside the edge is to the colour just outside it, relative to
+     * the colour further in (0: the edge ring looks like the subject; 1: it looks like the
+     * background). Measured only where the inside and outside differ.
+     */
+    haloScore: number;
+    /** 0–1: the share of the edge within 2 px of a strong image edge. */
+    edgeAlignment: number;
+    /** Turning of the outline beyond what closing it needs, in radians per 100 px of outline (0: smooth). */
+    jaggedness: number;
+    /** 0–1: the share of edge pixels that are partly covered (0 < α < 1). */
+    softFraction: number;
+    /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
+    holes: {
+        count: number;
+        totalArea: number;
+        largest: MaskRegion[];
+    };
+    /** Selected pieces apart from the largest one, largest first (at most 10 listed). */
+    islands: {
+        count: number;
+        totalArea: number;
+        largest: MaskRegion[];
+    };
+    /** Up to 5 places to look at first (for `capture_view`), worst first. */
+    worst: Array<{
+        bounds: CropBox;
+        reason: string;
+    }>;
+    /** Plain-language findings with a suggested fix, empty when the edge looks clean. */
+    issues: string[];
+}
+/** Report thresholds (also in the masking skill). */
+export declare const MASK_EDGE_THRESHOLDS: {
+    readonly halo: 0.35;
+    readonly alignment: 0.5;
+    readonly jaggedness: 15;
+    readonly soft: 0.9;
+};
+/**
+ * Inspects `mask`'s edge against `image` (RGBA, straight alpha, covering document pixels from
+ * `image.x`, `image.y`; outside it counts as transparent). Throws for an empty mask.
+ */
+export declare function inspectMaskEdge(mask: SelectionMask, image: PixelBuffer & {
+    x: number;
+    y: number;
+}, options?: InspectMaskEdgeOptions): MaskEdgeReport;

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

@@ -0,0 +1,70 @@
+/**
+ * A measured report on a mask's edge (`inspect_mask_edge`), so an agent can check a selection or
+ * a mask without looking at it: halo (old background left just inside the edge), how much of the
+ * edge sits on the image's own edges, how jagged the outline is, how soft it is, holes and stray
+ * islands, and the worst places to look at. Read-only; works in the mask's bounds.
+ */
+import type { CropBox } from '../types.js';
+import type { PixelBuffer, SelectionMask } from './mask.js';
+export interface InspectMaskEdgeOptions {
+    /** Holes and islands smaller than this many pixels are left out (default 16). */
+    minArea?: number;
+}
+/** A hole or island: its area in pixels and bounds. */
+export interface MaskRegion {
+    area: number;
+    bounds: CropBox;
+}
+export interface MaskEdgeReport {
+    /** Pixels at least half covered. */
+    area: number;
+    bounds: CropBox;
+    /** Pixels along the edge (inside, at least half covered, beside one less than half). */
+    edgeLength: number;
+    /**
+     * 0–1: how close the colour just inside the edge is to the colour just outside it, relative to
+     * the colour further in (0: the edge ring looks like the subject; 1: it looks like the
+     * background). Measured only where the inside and outside differ.
+     */
+    haloScore: number;
+    /** 0–1: the share of the edge within 2 px of a strong image edge. */
+    edgeAlignment: number;
+    /** Turning of the outline beyond what closing it needs, in radians per 100 px of outline (0: smooth). */
+    jaggedness: number;
+    /** 0–1: the share of edge pixels that are partly covered (0 < α < 1). */
+    softFraction: number;
+    /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
+    holes: {
+        count: number;
+        totalArea: number;
+        largest: MaskRegion[];
+    };
+    /** Selected pieces apart from the largest one, largest first (at most 10 listed). */
+    islands: {
+        count: number;
+        totalArea: number;
+        largest: MaskRegion[];
+    };
+    /** Up to 5 places to look at first (for `capture_view`), worst first. */
+    worst: Array<{
+        bounds: CropBox;
+        reason: string;
+    }>;
+    /** Plain-language findings with a suggested fix, empty when the edge looks clean. */
+    issues: string[];
+}
+/** Report thresholds (also in the masking skill). */
+export declare const MASK_EDGE_THRESHOLDS: {
+    readonly halo: 0.35;
+    readonly alignment: 0.5;
+    readonly jaggedness: 15;
+    readonly soft: 0.9;
+};
+/**
+ * Inspects `mask`'s edge against `image` (RGBA, straight alpha, covering document pixels from
+ * `image.x`, `image.y`; outside it counts as transparent). Throws for an empty mask.
+ */
+export declare function inspectMaskEdge(mask: SelectionMask, image: PixelBuffer & {
+    x: number;
+    y: number;
+}, options?: InspectMaskEdgeOptions): MaskEdgeReport;

package/package.json

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

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

@@ -210,6 +210,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `get_adjustments` | Read the current state: `values` by control id, `process` version (1 or 2), and `layers` bottom to top with id, kind, params, opacity, blend, enabled and mask. Call first, and to find layer ids. |
 | `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`). |
 | `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

@@ -44,10 +44,10 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    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.
-3. **Look at the edge.** Use `capture_view` with `region: "selection"` and `includeOverlays: true`,
-   or `set_selection_display` `quickMask`, to see soft edges as a tint.
-   **Check:** no holes in the subject, no islands in the background, and edges on the subject's
-   outline.
+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.
+   **Check:** `issues` is empty, or each one is intended (a deliberately soft edge or a second piece).
 4. **Clean it up.**
    - `modify_selection` `smooth` (2–4 px) removes wand speckle.
    - `grow_selection` (tolerance 10–30) picks up the shades a wand click missed;
@@ -89,7 +89,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    writes the selection, a channel or a layer mask as a greyscale PNG; a matte that comes
    back goes into a channel with `load_channel_from_image` (or straight to the selection with
    `load_selection_from_image`).
-7. **Verify.** `render_preview` at 1024 px or more, and `capture_view` on the edge at 2–8×.
+7. **Verify.** `inspect_mask_edge` again (`target: "layer-mask"` and `layerId` for a mask),
+   `render_preview` at 1024 px or more, and `capture_view` on `worst` regions at 2–8×.
    **Check:** no fringe of the old background colour, no stair-steps, no visible line where an
    adjustment ends. To judge a layer mask itself, `set_mask_view` `gray` (or `overlay`) and
    `capture_view` with `includeOverlays: true`; holes and stray grey show plainly there. Set it
@@ -220,8 +221,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere
 - `reselect`: undo a deselect
-- `save_selection`, `load_selection_from_channel`, `list_channels`: keep selections as alpha channels
-- `set_channel_properties`, `duplicate_channel`, `delete_channel`: manage channels
+- `save_selection`, `load_selection_from_channel`, `list_channels`, `set_channel_properties`, `duplicate_channel`, `delete_channel`: keep and manage selections as alpha channels
 - `export_mask_image`: a selection, channel or layer mask as a greyscale PNG
 - `load_channel_from_image`: a mask image into a new channel
 - `set_quick_mask`: paint the selection
@@ -240,8 +240,8 @@ 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
-- `capture_view`: inspect the edge at pixel level
-- `render_preview`: check the result
+- `inspect_mask_edge`: measured halo, alignment, jaggedness, softness, holes and islands of an edge
+- `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
 - `add_layer_mask`, `set_layer_mask_properties`, `apply_layer_mask`, `remove_layer_mask`: layer masks
 - `set_smart_filter_mask`: limit smart filters