@pixerate/editor 0.212.0 → 0.214.0

package/dist/image-editor/path-edit.d.cts

@@ -0,0 +1,97 @@
+/**
+ * Framework-free logic behind the path tools of the React and Svelte image editors (Photoshop's
+ * Path Selection, Direct Selection and Pen): hit-testing anchors, handles and segments, dragging
+ * them (one undo step per drag, the target updated live while dragging), converting, inserting and
+ * deleting anchors, drawing new subpaths with the Pen, and the overlay to draw. They edit what
+ * `controller.pathEditTarget()` names: the active path, the active shape layer or the active
+ * layer's vector mask. The components only translate DOM events and draw `overlay()`.
+ */
+import type { ImageEditorController } from './controller.cjs';
+import type { CropBox, ImagePoint } from './types.cjs';
+/** The path tools: whole components (`path-select`), anchors and handles (`direct-select`), and the Pen (`path-pen`). */
+export type PathEditTool = 'path-select' | 'direct-select' | 'path-pen';
+export declare const PATH_EDIT_TOOLS: readonly PathEditTool[];
+export declare function isPathEditTool(tool: string): tool is PathEditTool;
+/** One anchor of a target: component, subpath and anchor index. */
+export interface PathAnchorRef {
+    component: number;
+    subpath: number;
+    anchor: number;
+}
+/** What `RenderOptions.pathEdit` draws, in document pixels. */
+export interface PathEditOverlay {
+    /** The target's segments: 2 points for a line, 4 for a cubic. */
+    curves: ImagePoint[][];
+    /** Anchors shown; selected ones are drawn filled. */
+    anchors: Array<{
+        point: ImagePoint;
+        selected: boolean;
+    }>;
+    /** Direction handles of the selected anchors, with the anchor each belongs to. */
+    handles: Array<{
+        point: ImagePoint;
+        anchor: ImagePoint;
+    }>;
+    /** A marquee being dragged to select anchors. */
+    marquee: CropBox | null;
+    /** The Pen's next segment, from the last anchor to the pointer (2 or 4 points). */
+    preview: ImagePoint[] | null;
+}
+export interface PathEditModifiers {
+    shift?: boolean;
+    alt?: boolean;
+}
+/**
+ * The path tools' pointer and key handling. Call `setView` with the screen pixels per document
+ * pixel so hits are a fixed size on screen; `down` / `move` / `up` take document pixels.
+ */
+export declare class PathEditGesture {
+    private readonly controller;
+    /** Selected anchors, as `component:subpath:anchor` keys. */
+    private selected;
+    private target;
+    private drag;
+    /** The Pen's open subpath being drawn. */
+    private drawing;
+    private pointer;
+    private scale;
+    error: string | null;
+    constructor(controller: ImageEditorController);
+    /** Screen pixels per document pixel (the viewport projection's scale). */
+    setView(scale: number): void;
+    get active(): boolean;
+    /** The anchors selected now (on the current target). */
+    get selection(): PathAnchorRef[];
+    /** True while the Pen has an open subpath it adds to. */
+    get isDrawing(): boolean;
+    private get tolerance();
+    /** The target's components, or null (and the selection dropped) when the target changed or is gone. */
+    private components;
+    private anchorAt;
+    /** A handle of a selected anchor near `p`. */
+    private handleAt;
+    /** The segment near `p`: its first anchor (as `anchor`) and the parameter on it. */
+    private segmentAt;
+    /** The component under `p`: on its outline, or inside its fill. */
+    private componentAt;
+    private selectComponent;
+    private commit;
+    down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
+    private convert;
+    private penDown;
+    move(p: ImagePoint, mods?: PathEditModifiers): void;
+    /** The pointer moving with no button down (the Pen's preview of its next segment). */
+    hover(p: ImagePoint): void;
+    up(): void;
+    /** Ends the Pen's subpath (left open). */
+    finish(): void;
+    cancel(): void;
+    /**
+     * Keys: Delete / Backspace remove the selected anchors (one undo step), Enter and Escape end the
+     * Pen's subpath, Escape also deselects. Returns true when the key was handled.
+     */
+    key(k: string): boolean;
+    /** What to draw (`RenderOptions.pathEdit`) for `tool`, or null when there is no target. */
+    overlay(tool: PathEditTool): PathEditOverlay | null;
+}

package/dist/image-editor/path-edit.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Framework-free logic behind the path tools of the React and Svelte image editors (Photoshop's
+ * Path Selection, Direct Selection and Pen): hit-testing anchors, handles and segments, dragging
+ * them (one undo step per drag, the target updated live while dragging), converting, inserting and
+ * deleting anchors, drawing new subpaths with the Pen, and the overlay to draw. They edit what
+ * `controller.pathEditTarget()` names: the active path, the active shape layer or the active
+ * layer's vector mask. The components only translate DOM events and draw `overlay()`.
+ */
+import type { ImageEditorController } from './controller.js';
+import type { CropBox, ImagePoint } from './types.js';
+/** The path tools: whole components (`path-select`), anchors and handles (`direct-select`), and the Pen (`path-pen`). */
+export type PathEditTool = 'path-select' | 'direct-select' | 'path-pen';
+export declare const PATH_EDIT_TOOLS: readonly PathEditTool[];
+export declare function isPathEditTool(tool: string): tool is PathEditTool;
+/** One anchor of a target: component, subpath and anchor index. */
+export interface PathAnchorRef {
+    component: number;
+    subpath: number;
+    anchor: number;
+}
+/** What `RenderOptions.pathEdit` draws, in document pixels. */
+export interface PathEditOverlay {
+    /** The target's segments: 2 points for a line, 4 for a cubic. */
+    curves: ImagePoint[][];
+    /** Anchors shown; selected ones are drawn filled. */
+    anchors: Array<{
+        point: ImagePoint;
+        selected: boolean;
+    }>;
+    /** Direction handles of the selected anchors, with the anchor each belongs to. */
+    handles: Array<{
+        point: ImagePoint;
+        anchor: ImagePoint;
+    }>;
+    /** A marquee being dragged to select anchors. */
+    marquee: CropBox | null;
+    /** The Pen's next segment, from the last anchor to the pointer (2 or 4 points). */
+    preview: ImagePoint[] | null;
+}
+export interface PathEditModifiers {
+    shift?: boolean;
+    alt?: boolean;
+}
+/**
+ * The path tools' pointer and key handling. Call `setView` with the screen pixels per document
+ * pixel so hits are a fixed size on screen; `down` / `move` / `up` take document pixels.
+ */
+export declare class PathEditGesture {
+    private readonly controller;
+    /** Selected anchors, as `component:subpath:anchor` keys. */
+    private selected;
+    private target;
+    private drag;
+    /** The Pen's open subpath being drawn. */
+    private drawing;
+    private pointer;
+    private scale;
+    error: string | null;
+    constructor(controller: ImageEditorController);
+    /** Screen pixels per document pixel (the viewport projection's scale). */
+    setView(scale: number): void;
+    get active(): boolean;
+    /** The anchors selected now (on the current target). */
+    get selection(): PathAnchorRef[];
+    /** True while the Pen has an open subpath it adds to. */
+    get isDrawing(): boolean;
+    private get tolerance();
+    /** The target's components, or null (and the selection dropped) when the target changed or is gone. */
+    private components;
+    private anchorAt;
+    /** A handle of a selected anchor near `p`. */
+    private handleAt;
+    /** The segment near `p`: its first anchor (as `anchor`) and the parameter on it. */
+    private segmentAt;
+    /** The component under `p`: on its outline, or inside its fill. */
+    private componentAt;
+    private selectComponent;
+    private commit;
+    down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
+    private convert;
+    private penDown;
+    move(p: ImagePoint, mods?: PathEditModifiers): void;
+    /** The pointer moving with no button down (the Pen's preview of its next segment). */
+    hover(p: ImagePoint): void;
+    up(): void;
+    /** Ends the Pen's subpath (left open). */
+    finish(): void;
+    cancel(): void;
+    /**
+     * Keys: Delete / Backspace remove the selected anchors (one undo step), Enter and Escape end the
+     * Pen's subpath, Escape also deselects. Returns true when the key was handled.
+     */
+    key(k: string): boolean;
+    /** What to draw (`RenderOptions.pathEdit`) for `tool`, or null when there is no target. */
+    overlay(tool: PathEditTool): PathEditOverlay | null;
+}

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

@@ -39,3 +39,17 @@ export declare function serializePaths(paths: readonly DocumentPath[]): Serializ
  * Path; ids are made unique.
  */
 export declare function readPaths(stored: unknown, problems?: string[]): DocumentPath[];
+/**
+ * What the path tools edit: a document path, a shape layer's components or a layer's vector mask
+ * (see `ImageEditorController.pathEditTarget`).
+ */
+export type PathEditTarget = {
+    kind: 'path';
+    id: string;
+} | {
+    kind: 'shape';
+    layerId: string;
+} | {
+    kind: 'vector-mask';
+    layerId: string;
+};

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

@@ -39,3 +39,17 @@ export declare function serializePaths(paths: readonly DocumentPath[]): Serializ
  * Path; ids are made unique.
  */
 export declare function readPaths(stored: unknown, problems?: string[]): DocumentPath[];
+/**
+ * What the path tools edit: a document path, a shape layer's components or a layer's vector mask
+ * (see `ImageEditorController.pathEditTarget`).
+ */
+export type PathEditTarget = {
+    kind: 'path';
+    id: string;
+} | {
+    kind: 'shape';
+    layerId: string;
+} | {
+    kind: 'vector-mask';
+    layerId: string;
+};

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

@@ -1,3 +1,4 @@
+import type { PathEditOverlay } from './path-edit.cjs';
 import type { Annotation, CropBox, ImagePoint, ExportOptions, ImageEditorFit, ImageEditorState } from './types.cjs';
 import type { PixelTransform } from './color-management.cjs';
 import { type ImageHistogram } from './histogram.cjs';
@@ -80,6 +81,8 @@ export interface RenderOptions {
             }>;
         };
     } | null;
+    /** The path tools' target outline, anchors, handles, marquee and Pen preview in natural pixels (`PathEditGesture.overlay()`). */
+    pathEdit?: PathEditOverlay | null;
 }
 /**
  * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.

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

@@ -1,3 +1,4 @@
+import type { PathEditOverlay } from './path-edit.js';
 import type { Annotation, CropBox, ImagePoint, ExportOptions, ImageEditorFit, ImageEditorState } from './types.js';
 import type { PixelTransform } from './color-management.js';
 import { type ImageHistogram } from './histogram.js';
@@ -80,6 +81,8 @@ export interface RenderOptions {
             }>;
         };
     } | null;
+    /** The path tools' target outline, anchors, handles, marquee and Pen preview in natural pixels (`PathEditGesture.overlay()`). */
+    pathEdit?: PathEditOverlay | null;
 }
 /**
  * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.

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

@@ -17,3 +17,4 @@ export * from './segment/index.cjs';
 export * from './refine-edits.cjs';
 export * from './select-and-mask.cjs';
 export * from './worker.cjs';
+export * from './inspect.cjs';

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

@@ -17,3 +17,4 @@ export * from './segment/index.js';
 export * from './refine-edits.js';
 export * from './select-and-mask.js';
 export * from './worker.js';
+export * from './inspect.js';

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/dist/image-editor/tool-groups.d.cts

@@ -25,8 +25,8 @@ export declare function imageToolForShortcut(key: string, shift?: boolean): Imag
 /** 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`.
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type, the path tools
+ * 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. */

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

@@ -25,8 +25,8 @@ export declare function imageToolForShortcut(key: string, shift?: boolean): Imag
 /** 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`.
+ * The canvas mode a tool works in. Move picks and transforms layers; shapes, type, the path tools
+ * 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. */

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

@@ -280,7 +280,9 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
 /** Live shape layers (see `ShapeDrawGesture`). */
  | 'shape'
 /** Live type layers, edited on the canvas (see `TypeToolGesture`). */
- | 'type';
+ | 'type'
+/** The path tools (see `PathEditGesture`): Path Selection, Direct Selection and the Pen for paths. */
+ | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.cjs';
 import type { BitDepth } from '../raster/deep.cjs';

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

@@ -280,7 +280,9 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
 /** Live shape layers (see `ShapeDrawGesture`). */
  | 'shape'
 /** Live type layers, edited on the canvas (see `TypeToolGesture`). */
- | 'type';
+ | 'type'
+/** The path tools (see `PathEditGesture`): Path Selection, Direct Selection and the Pen for paths. */
+ | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.js';
 import type { BitDepth } from '../raster/deep.js';