@pixerate/editor 0.193.0 → 0.195.0

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

@@ -23,6 +23,10 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  *   adds a free-hand stretch; a double-click, a click on the first corner or Enter (`key`)
  *   closes it, Backspace removes the last corner and Escape cancels. It stays `active` between
  *   clicks, so feed it pointer moves without a button too.
+ * - Magnetic lasso: a click sets the first anchor, then the outline follows the edges from the
+ *   last anchor to the pointer (snapped to the strongest edge within the width) and places
+ *   anchors as it goes (frequency); a click adds one, and closing and the keys are as the
+ *   polygonal lasso's. The first click reads the pixels (async).
  * - 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,
@@ -39,12 +43,15 @@ export declare class SelectionGesture {
     private polygon;
     private pressedAt;
     private freehand;
+    private magnetic;
     /** A click this close to the first corner (natural pixels) closes a polygonal lasso. */
     closeRadius: number;
     /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
     error: string | null;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
+    /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
+    get magneticAnchors(): ImagePoint[];
     /** The outline of the shape being drawn, or `null`. */
     get draftPath(): ImagePoint[] | null;
     /** Pointer down. Resolves once a wand click has been applied. */
@@ -60,6 +67,11 @@ export declare class SelectionGesture {
      * removes the last corner. Returns true when the key was used (the host prevents its default).
      */
     key(key: string): boolean;
+    /** Corridor half-width for a live-wire between two points. */
+    private corridor;
+    private magneticClick;
+    /** Updates the live path to `point`, fixing anchors along it every `frequency` px (with `place`). */
+    private followEdges;
     /** Abandons a drag (or a polygonal lasso) without changing the selection. */
     cancel(): void;
 }

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

@@ -23,6 +23,10 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  *   adds a free-hand stretch; a double-click, a click on the first corner or Enter (`key`)
  *   closes it, Backspace removes the last corner and Escape cancels. It stays `active` between
  *   clicks, so feed it pointer moves without a button too.
+ * - Magnetic lasso: a click sets the first anchor, then the outline follows the edges from the
+ *   last anchor to the pointer (snapped to the strongest edge within the width) and places
+ *   anchors as it goes (frequency); a click adds one, and closing and the keys are as the
+ *   polygonal lasso's. The first click reads the pixels (async).
  * - 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,
@@ -39,12 +43,15 @@ export declare class SelectionGesture {
     private polygon;
     private pressedAt;
     private freehand;
+    private magnetic;
     /** A click this close to the first corner (natural pixels) closes a polygonal lasso. */
     closeRadius: number;
     /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
     error: string | null;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
+    /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
+    get magneticAnchors(): ImagePoint[];
     /** The outline of the shape being drawn, or `null`. */
     get draftPath(): ImagePoint[] | null;
     /** Pointer down. Resolves once a wand click has been applied. */
@@ -60,6 +67,11 @@ export declare class SelectionGesture {
      * removes the last corner. Returns true when the key was used (the host prevents its default).
      */
     key(key: string): boolean;
+    /** Corridor half-width for a live-wire between two points. */
+    private corridor;
+    private magneticClick;
+    /** Updates the live path to `point`, fixing anchors along it every `frequency` px (with `place`). */
+    private followEdges;
     /** Abandons a drag (or a polygonal lasso) without changing the selection. */
     cancel(): void;
 }

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

@@ -12,3 +12,4 @@ export * from './stroke.cjs';
 export * from './channels.cjs';
 export * from './mask-files.cjs';
 export * from './path.cjs';
+export * from './magnetic.cjs';

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

@@ -12,3 +12,4 @@ export * from './stroke.js';
 export * from './channels.js';
 export * from './mask-files.js';
 export * from './path.js';
+export * from './magnetic.js';

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

@@ -0,0 +1,60 @@
+/**
+ * Magnetic Lasso: an outline that follows the edges of the image (live-wire, Mortensen & Barrett,
+ * "Intelligent Scissors", 1995). Each step between neighbouring pixels costs less where it runs
+ * along a strong edge (gradient magnitude), on a Laplacian zero-crossing and in the edge's
+ * direction; the outline between two points is the cheapest path, found with Dijkstra in a corridor
+ * around them. The direction term ignores which side of the edge is darker, so the path holds to an
+ * edge whichever way round it is traced.
+ */
+import type { ImagePoint } from '../types.cjs';
+import type { PixelBuffer } from './mask.cjs';
+export interface MagneticEdgeOptions {
+    /** Detection width in px: a point snaps to the strongest edge this close to it (default 10). */
+    width?: number;
+    /** 0..1: edges with less contrast than this are ignored (default 0.1, Photoshop's 10 %). */
+    contrast?: number;
+}
+/**
+ * The edge features of an image, computed lazily in 64 px blocks as the outline reaches them, so a
+ * click on a large image costs one luminance pass, not a full-image edge map.
+ */
+export declare class EdgeMap {
+    readonly width: number;
+    readonly height: number;
+    readonly contrast: number;
+    private readonly luma;
+    private readonly blocks;
+    constructor(pixels: PixelBuffer, options?: Pick<MagneticEdgeOptions, 'contrast'>);
+    /** Edge strength at (x, y) in whole pixels, 0..1 (0 outside the image or below the contrast). */
+    strength(x: number, y: number): number;
+    private block;
+    private computeBlock;
+    /** Features of the pixel at (x, y), which must be inside the image. */
+    features(x: number, y: number): {
+        strength: number;
+        dirX: number;
+        dirY: number;
+        zero: number;
+    };
+}
+/**
+ * `point` moved onto the strongest edge within `width` px (the nearest of equal ones); unchanged
+ * when there is no edge above the contrast that close. Returns a pixel centre.
+ */
+export declare function snapToEdge(map: EdgeMap, point: ImagePoint, width?: number): ImagePoint;
+/**
+ * The cheapest path along the edges from `from` to `to` (pixel centres, both included), searched
+ * in a corridor around the straight line between them: `band` px either side (default the larger
+ * of 16 px and a quarter of the distance). Points inside the image.
+ */
+export declare function liveWire(map: EdgeMap, from: ImagePoint, to: ImagePoint, band?: number): ImagePoint[];
+/** `points` with runs along one straight line reduced to their ends (exact for 8-connected paths). */
+export declare function simplifyPixelPath(points: readonly ImagePoint[]): ImagePoint[];
+/**
+ * The Magnetic Lasso for a given outline (the agent path): each point snaps to the strongest edge
+ * within `width` px, and consecutive points are joined by the live-wire path between them (the
+ * last back to the first). Points should run along the edge in order, a few dozen px apart.
+ */
+export declare function snapPolygonToEdges(pixels: PixelBuffer | EdgeMap, points: readonly ImagePoint[], options?: MagneticEdgeOptions): ImagePoint[];
+/** Path length in px between auto-placed anchors for a Frequency of 0..100 (Photoshop's default 57). */
+export declare function magneticAnchorSpacing(frequency?: number): number;

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

@@ -0,0 +1,60 @@
+/**
+ * Magnetic Lasso: an outline that follows the edges of the image (live-wire, Mortensen & Barrett,
+ * "Intelligent Scissors", 1995). Each step between neighbouring pixels costs less where it runs
+ * along a strong edge (gradient magnitude), on a Laplacian zero-crossing and in the edge's
+ * direction; the outline between two points is the cheapest path, found with Dijkstra in a corridor
+ * around them. The direction term ignores which side of the edge is darker, so the path holds to an
+ * edge whichever way round it is traced.
+ */
+import type { ImagePoint } from '../types.js';
+import type { PixelBuffer } from './mask.js';
+export interface MagneticEdgeOptions {
+    /** Detection width in px: a point snaps to the strongest edge this close to it (default 10). */
+    width?: number;
+    /** 0..1: edges with less contrast than this are ignored (default 0.1, Photoshop's 10 %). */
+    contrast?: number;
+}
+/**
+ * The edge features of an image, computed lazily in 64 px blocks as the outline reaches them, so a
+ * click on a large image costs one luminance pass, not a full-image edge map.
+ */
+export declare class EdgeMap {
+    readonly width: number;
+    readonly height: number;
+    readonly contrast: number;
+    private readonly luma;
+    private readonly blocks;
+    constructor(pixels: PixelBuffer, options?: Pick<MagneticEdgeOptions, 'contrast'>);
+    /** Edge strength at (x, y) in whole pixels, 0..1 (0 outside the image or below the contrast). */
+    strength(x: number, y: number): number;
+    private block;
+    private computeBlock;
+    /** Features of the pixel at (x, y), which must be inside the image. */
+    features(x: number, y: number): {
+        strength: number;
+        dirX: number;
+        dirY: number;
+        zero: number;
+    };
+}
+/**
+ * `point` moved onto the strongest edge within `width` px (the nearest of equal ones); unchanged
+ * when there is no edge above the contrast that close. Returns a pixel centre.
+ */
+export declare function snapToEdge(map: EdgeMap, point: ImagePoint, width?: number): ImagePoint;
+/**
+ * The cheapest path along the edges from `from` to `to` (pixel centres, both included), searched
+ * in a corridor around the straight line between them: `band` px either side (default the larger
+ * of 16 px and a quarter of the distance). Points inside the image.
+ */
+export declare function liveWire(map: EdgeMap, from: ImagePoint, to: ImagePoint, band?: number): ImagePoint[];
+/** `points` with runs along one straight line reduced to their ends (exact for 8-connected paths). */
+export declare function simplifyPixelPath(points: readonly ImagePoint[]): ImagePoint[];
+/**
+ * The Magnetic Lasso for a given outline (the agent path): each point snaps to the strongest edge
+ * within `width` px, and consecutive points are joined by the live-wire path between them (the
+ * last back to the first). Points should run along the edge in order, a few dozen px apart.
+ */
+export declare function snapPolygonToEdges(pixels: PixelBuffer | EdgeMap, points: readonly ImagePoint[], options?: MagneticEdgeOptions): ImagePoint[];
+/** Path length in px between auto-placed anchors for a Frequency of 0..100 (Photoshop's default 57). */
+export declare function magneticAnchorSpacing(frequency?: number): number;

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' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -31,6 +31,12 @@ export interface SelectionToolOptions {
     localized?: number;
     /** Color Range: select everything except the sampled colours. */
     rangeInvert?: boolean;
+    /** Magnetic Lasso: snap to the strongest edge within this many px (1..256, default 10). */
+    magneticWidth?: number;
+    /** Magnetic Lasso: ignore edges with less contrast than this, in % (1..100, default 10). */
+    magneticContrast?: number;
+    /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
+    magneticFrequency?: number;
     /** 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' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -31,6 +31,12 @@ export interface SelectionToolOptions {
     localized?: number;
     /** Color Range: select everything except the sampled colours. */
     rangeInvert?: boolean;
+    /** Magnetic Lasso: snap to the strongest edge within this many px (1..256, default 10). */
+    magneticWidth?: number;
+    /** Magnetic Lasso: ignore edges with less contrast than this, in % (1..100, default 10). */
+    magneticContrast?: number;
+    /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
+    magneticFrequency?: number;
     /** 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/tool-groups.d.cts

@@ -0,0 +1,35 @@
+/**
+ * The image editor's tools as a toolbar shows them: grouped like Photoshop's (a slot per group, the
+ * rest of the group in a flyout), with labels and shortcuts, the canvas mode each tool draws in and
+ * the layer panel (`layerPanels`) holding its options. Hosts build their toolbar from these instead
+ * of listing tools themselves, so new tools show up without host changes.
+ */
+import type { ImageEditorTool } from './types.cjs';
+export interface ImageToolGroup {
+    id: string;
+    label: string;
+    tools: readonly ImageEditorTool[];
+}
+/**
+ * Every tool a toolbar offers, in toolbar order. The `text` and `watermark` annotations are left
+ * out: they are added through the API (`addAnnotation`), not drawn.
+ */
+export declare const IMAGE_TOOL_GROUPS: readonly ImageToolGroup[];
+/** The group a tool is in (the first group for a tool no group holds). */
+export declare function imageToolGroup(tool: ImageEditorTool): ImageToolGroup;
+export declare function imageToolLabel(tool: ImageEditorTool): string;
+/** Photoshop's shortcuts, as the paint tools' keys handle them (`Shift+B` and so on). */
+export declare const IMAGE_TOOL_SHORTCUTS: Partial<Record<ImageEditorTool, string>>;
+/** The tool a shortcut picks (the first tool listed for a shared key), or null. */
+export declare function imageToolForShortcut(key: string, shift?: boolean): ImageEditorTool | null;
+/** How a canvas handles pointer gestures for a tool (the Svelte and React canvases' `mode`). */
+export type ImageToolCanvasMode = 'transform' | 'crop' | 'select' | 'paint' | 'annotate';
+/**
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type and the
+ * annotations draw in `annotate`.
+ */
+export declare function imageToolCanvasMode(tool: ImageEditorTool): ImageToolCanvasMode;
+/** The `layerPanels` panel holding a tool's options, or null when it has none. */
+export declare function imageToolPanel(tool: ImageEditorTool): string | null;
+/** The first tool whose options are in a panel (in toolbar order), or null. */
+export declare function imagePanelTool(panel: string): ImageEditorTool | null;

package/dist/image-editor/tool-groups.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The image editor's tools as a toolbar shows them: grouped like Photoshop's (a slot per group, the
+ * rest of the group in a flyout), with labels and shortcuts, the canvas mode each tool draws in and
+ * the layer panel (`layerPanels`) holding its options. Hosts build their toolbar from these instead
+ * of listing tools themselves, so new tools show up without host changes.
+ */
+import type { ImageEditorTool } from './types.js';
+export interface ImageToolGroup {
+    id: string;
+    label: string;
+    tools: readonly ImageEditorTool[];
+}
+/**
+ * Every tool a toolbar offers, in toolbar order. The `text` and `watermark` annotations are left
+ * out: they are added through the API (`addAnnotation`), not drawn.
+ */
+export declare const IMAGE_TOOL_GROUPS: readonly ImageToolGroup[];
+/** The group a tool is in (the first group for a tool no group holds). */
+export declare function imageToolGroup(tool: ImageEditorTool): ImageToolGroup;
+export declare function imageToolLabel(tool: ImageEditorTool): string;
+/** Photoshop's shortcuts, as the paint tools' keys handle them (`Shift+B` and so on). */
+export declare const IMAGE_TOOL_SHORTCUTS: Partial<Record<ImageEditorTool, string>>;
+/** The tool a shortcut picks (the first tool listed for a shared key), or null. */
+export declare function imageToolForShortcut(key: string, shift?: boolean): ImageEditorTool | null;
+/** How a canvas handles pointer gestures for a tool (the Svelte and React canvases' `mode`). */
+export type ImageToolCanvasMode = 'transform' | 'crop' | 'select' | 'paint' | 'annotate';
+/**
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type and the
+ * annotations draw in `annotate`.
+ */
+export declare function imageToolCanvasMode(tool: ImageEditorTool): ImageToolCanvasMode;
+/** The `layerPanels` panel holding a tool's options, or null when it has none. */
+export declare function imageToolPanel(tool: ImageEditorTool): string | null;
+/** The first tool whose options are in a panel (in toolbar order), or null. */
+export declare function imagePanelTool(panel: string): ImageEditorTool | null;

package/package.json

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

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

@@ -252,7 +252,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `select_rect` | Rectangular marquee: `x`, `y`, `width`, `height` (natural px), `mode` (replace, add, subtract, intersect), `feather` px, `antiAlias`. Returns the summary. |
 | `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. |
-| `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`. Trace a subject's contour, not its box. 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. |
 | `load_selection_from_image` | Load a mask image (`image` data URL or URL; white = selected) by `channel` (luminance, alpha, red, green, blue), with `threshold`, `invert`, `mode`. For AI or saved mattes; then `refine_selection`. 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` along the contour (20–60 points), then `refine_selection` |
+| 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` |
+| 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` |
 | A colour spread across the image (all the reds, a dress) | `select_color_range` with `samples` (several picks) or a hue `preset`; `localized` to keep one area |
 | Tones (shadows, highlights, a luminosity mask) | `select_color_range` with `preset` `shadows` / `midtones` / `highlights` |
@@ -155,6 +156,10 @@ 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.
+- **Magnetic outline jumps to the wrong edge:** `snapToEdges` follows the strongest edge near
+  each point, which can be a shadow or a texture. Put points within `width` of the edge you
+  want, add points where it turns or runs past another edge, raise `contrast` on a busy
+  background, and drop `snapToEdges` where the edge is too faint.
 - **Over-feathering hard objects:** a 10 px feather on a product looks like a glow. Keep hard
   edges at 0–2 px and refine soft ones instead.
 - **Halo:** the old background shows as a light or dark fringe. `contract` 1–2 px or
@@ -183,7 +188,7 @@ 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_polygon`: the lasso, along a contour
+- `select_polygon`: the lasso, along a contour; with `snapToEdges`, the Magnetic Lasso
 - `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