@pixerate/editor 0.219.2 → 0.221.0

package/dist/image-editor/layers/hybrid-mask.d.cts

@@ -0,0 +1,31 @@
+/**
+ * Hybrid vector masks: a vector mask whose segments each have an edge mode. Hard segments are
+ * the path's own anti-aliased edge; feather segments blur across the curve; matte segments solve
+ * a corridor between two rails (inside by `inner`, outside by `outer`) from the layer's pixels
+ * with the colour-guided filter, so hair and fur keep their detail while the rest stays sharp.
+ * Where modes meet, they blend over a few pixels so there is no seam. Rendered on demand from
+ * the path and the pixels, and cached with the layer like any vector mask.
+ */
+import type { ShapeComponent, VectorMask, VectorMaskEdge } from './model.cjs';
+export type VectorMaskEdgeMode = 'hard' | 'feather' | 'matte';
+/** Defaults for a segment switched to a soft mode. */
+export declare const VECTOR_MASK_EDGE_DEFAULTS: {
+    readonly radius: 4;
+    readonly inner: 4;
+    readonly outer: 8;
+};
+/** The segments of a vector mask's path as `{ component, subpath, segment }` triples. */
+export declare function vectorMaskSegments(components: readonly ShapeComponent[]): Array<{
+    component: number;
+    subpath: number;
+    segment: number;
+}>;
+/** Edges whose segment still exists in `components` (after the path was edited). */
+export declare function validVectorMaskEdges(edges: readonly VectorMaskEdge[] | undefined, components: readonly ShapeComponent[]): VectorMaskEdge[];
+/**
+ * The hybrid coverage (0..1, `width × height`) from the path's hard coverage `hard` (as
+ * `componentsCoverage` gives it, before the mask's own feather and density) and the soft
+ * `edges`. `guide` is the layer's RGBA over the canvas, for matte corridors; without one a matte
+ * segment is feathered instead. Returns `hard` itself when no edge is soft.
+ */
+export declare function hybridVectorMaskCoverage(vm: Pick<VectorMask, 'components' | 'edges'>, hard: Float32Array, width: number, height: number, guide: ArrayLike<number> | null): Float32Array;

package/dist/image-editor/layers/hybrid-mask.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hybrid vector masks: a vector mask whose segments each have an edge mode. Hard segments are
+ * the path's own anti-aliased edge; feather segments blur across the curve; matte segments solve
+ * a corridor between two rails (inside by `inner`, outside by `outer`) from the layer's pixels
+ * with the colour-guided filter, so hair and fur keep their detail while the rest stays sharp.
+ * Where modes meet, they blend over a few pixels so there is no seam. Rendered on demand from
+ * the path and the pixels, and cached with the layer like any vector mask.
+ */
+import type { ShapeComponent, VectorMask, VectorMaskEdge } from './model.js';
+export type VectorMaskEdgeMode = 'hard' | 'feather' | 'matte';
+/** Defaults for a segment switched to a soft mode. */
+export declare const VECTOR_MASK_EDGE_DEFAULTS: {
+    readonly radius: 4;
+    readonly inner: 4;
+    readonly outer: 8;
+};
+/** The segments of a vector mask's path as `{ component, subpath, segment }` triples. */
+export declare function vectorMaskSegments(components: readonly ShapeComponent[]): Array<{
+    component: number;
+    subpath: number;
+    segment: number;
+}>;
+/** Edges whose segment still exists in `components` (after the path was edited). */
+export declare function validVectorMaskEdges(edges: readonly VectorMaskEdge[] | undefined, components: readonly ShapeComponent[]): VectorMaskEdge[];
+/**
+ * The hybrid coverage (0..1, `width × height`) from the path's hard coverage `hard` (as
+ * `componentsCoverage` gives it, before the mask's own feather and density) and the soft
+ * `edges`. `guide` is the layer's RGBA over the canvas, for matte corridors; without one a matte
+ * segment is feathered instead. Returns `hard` itself when no edge is soft.
+ */
+export declare function hybridVectorMaskCoverage(vm: Pick<VectorMask, 'components' | 'edges'>, hard: Float32Array, width: number, height: number, guide: ArrayLike<number> | null): Float32Array;

package/dist/image-editor/layers/model.d.cts

@@ -51,6 +51,23 @@ export interface VectorMask {
     density?: number;
     /** Gaussian feather σ in px (default 0). */
     feather?: number;
+    /**
+     * Hybrid mask: soft edge modes per path segment (see `hybridVectorMaskCoverage`); segments not
+     * listed are hard. Indices follow the path's components, subpaths and segments.
+     */
+    edges?: VectorMaskEdge[];
+}
+/** One segment's edge mode in a hybrid vector mask. */
+export interface VectorMaskEdge {
+    component: number;
+    subpath: number;
+    /** Segment index in the subpath (from anchor `segment` to the next). */
+    segment: number;
+    /** `feather`: a Gaussian falloff of `radius` px across the curve; `matte`: a corridor from `inner` px inside to `outer` px outside, solved from the layer's colours. */
+    mode: 'hard' | 'feather' | 'matte';
+    radius?: number;
+    inner?: number;
+    outer?: number;
 }
 /** The base sliders of the old document-level adjustments, as a filter on one layer. */
 export interface DevelopSettings {

package/dist/image-editor/layers/model.d.ts

@@ -51,6 +51,23 @@ export interface VectorMask {
     density?: number;
     /** Gaussian feather σ in px (default 0). */
     feather?: number;
+    /**
+     * Hybrid mask: soft edge modes per path segment (see `hybridVectorMaskCoverage`); segments not
+     * listed are hard. Indices follow the path's components, subpaths and segments.
+     */
+    edges?: VectorMaskEdge[];
+}
+/** One segment's edge mode in a hybrid vector mask. */
+export interface VectorMaskEdge {
+    component: number;
+    subpath: number;
+    /** Segment index in the subpath (from anchor `segment` to the next). */
+    segment: number;
+    /** `feather`: a Gaussian falloff of `radius` px across the curve; `matte`: a corridor from `inner` px inside to `outer` px outside, solved from the layer's colours. */
+    mode: 'hard' | 'feather' | 'matte';
+    radius?: number;
+    inner?: number;
+    outer?: number;
 }
 /** The base sliders of the old document-level adjustments, as a filter on one layer. */
 export interface DevelopSettings {

package/dist/image-editor/layers/serialize.d.cts

@@ -57,6 +57,8 @@ export interface SerializedVectorMask {
     linked?: false;
     density?: number;
     feather?: number;
+    /** Hybrid mask: soft edge modes per segment. */
+    edges?: unknown[];
 }
 /** A layer's effects: the effect list as JSON plus the PSD block they came from (base64). */
 export interface SerializedLayerEffects {
@@ -240,6 +242,8 @@ export interface SerializedLayeredImageEditorState {
     /** Blur migrated from a v1 / v2 document with adjustment layers (runs after the layers). */
     legacyOutputBlur?: number;
     selection?: SerializedSelection;
+    /** The selection's recipe (live selections): the steps that made it, as JSON. */
+    selectionRecipe?: unknown[];
     /** Alpha channels (saved selections), run-length encoded. */
     channels?: SerializedAlphaChannel[];
     /** Document paths (the Paths panel). */

package/dist/image-editor/layers/serialize.d.ts

@@ -57,6 +57,8 @@ export interface SerializedVectorMask {
     linked?: false;
     density?: number;
     feather?: number;
+    /** Hybrid mask: soft edge modes per segment. */
+    edges?: unknown[];
 }
 /** A layer's effects: the effect list as JSON plus the PSD block they came from (base64). */
 export interface SerializedLayerEffects {
@@ -240,6 +242,8 @@ export interface SerializedLayeredImageEditorState {
     /** Blur migrated from a v1 / v2 document with adjustment layers (runs after the layers). */
     legacyOutputBlur?: number;
     selection?: SerializedSelection;
+    /** The selection's recipe (live selections): the steps that made it, as JSON. */
+    selectionRecipe?: unknown[];
     /** Alpha channels (saved selections), run-length encoded. */
     channels?: SerializedAlphaChannel[];
     /** Document paths (the Paths panel). */

package/dist/image-editor/layers/vector-mask.d.cts

@@ -6,26 +6,31 @@
  */
 import type { CropBox } from '../types.cjs';
 import type { AffineMatrix } from '../../geom/types.cjs';
+import { readRegion } from '../../raster/surface.cjs';
 import type { ImageLayer, RasterMask, VectorMask } from './model.cjs';
 /** Whether a vector mask takes part in compositing. */
 export declare function isActiveVectorMask(vm: VectorMask | undefined): vm is VectorMask;
 /**
- * The vector mask's coverage (0..1) over the `width × height` canvas, with its feather and
- * density applied.
+ * The vector mask's coverage (0..1) over the `width × height` canvas, with its hybrid edges,
+ * feather and density applied.
  */
-export declare function vectorMaskCoverage(vm: VectorMask, width: number, height: number): Float32Array;
+export declare function vectorMaskCoverage(vm: VectorMask, width: number, height: number, guide?: ArrayLike<number> | null): Float32Array;
+/** Where a layer's pixels really are (the Background's come from the source image). */
+export type LayerSurfaceOf = (layer: ImageLayer) => Parameters<typeof readRegion>[0] | undefined;
+/** A layer's own RGBA over the canvas (the guide for hybrid matte edges), or null without pixels. */
+export declare function layerGuide(layer: ImageLayer, width: number, height: number, surfaceOf?: LayerSurfaceOf): Uint8ClampedArray | null;
 /**
  * The raster mask a layer composites with: its raster mask times its vector mask (layer space,
  * feather and density baked in), or the raster mask alone when there is no active vector mask.
  * A depth (parametric) mask cannot be combined, so it wins.
  */
-export declare function effectiveLayerMask(layer: ImageLayer, width: number, height: number): RasterMask | undefined;
+export declare function effectiveLayerMask(layer: ImageLayer, width: number, height: number, surfaceOf?: LayerSurfaceOf): RasterMask | undefined;
 /**
  * The stack as the compositor should see it: each layer with an active vector mask replaced by a
  * copy whose `mask` is `effectiveLayerMask` (cached per layer object and canvas size, so the
  * engine's tile caches keep working). Returns `layers` itself when there are none.
  */
-export declare function resolveVectorMasks(layers: readonly ImageLayer[], width: number, height: number): readonly ImageLayer[];
+export declare function resolveVectorMasks(layers: readonly ImageLayer[], width: number, height: number, surfaceOf?: LayerSurfaceOf): readonly ImageLayer[];
 /** A vector mask moved by (dx, dy) document pixels. */
 export declare function offsetVectorMask(vm: VectorMask, dx: number, dy: number): VectorMask;
 /** A vector mask with its paths mapped by `f` (document space); `affine` keeps live shapes live. */

package/dist/image-editor/layers/vector-mask.d.ts

@@ -6,26 +6,31 @@
  */
 import type { CropBox } from '../types.js';
 import type { AffineMatrix } from '../../geom/types.js';
+import { readRegion } from '../../raster/surface.js';
 import type { ImageLayer, RasterMask, VectorMask } from './model.js';
 /** Whether a vector mask takes part in compositing. */
 export declare function isActiveVectorMask(vm: VectorMask | undefined): vm is VectorMask;
 /**
- * The vector mask's coverage (0..1) over the `width × height` canvas, with its feather and
- * density applied.
+ * The vector mask's coverage (0..1) over the `width × height` canvas, with its hybrid edges,
+ * feather and density applied.
  */
-export declare function vectorMaskCoverage(vm: VectorMask, width: number, height: number): Float32Array;
+export declare function vectorMaskCoverage(vm: VectorMask, width: number, height: number, guide?: ArrayLike<number> | null): Float32Array;
+/** Where a layer's pixels really are (the Background's come from the source image). */
+export type LayerSurfaceOf = (layer: ImageLayer) => Parameters<typeof readRegion>[0] | undefined;
+/** A layer's own RGBA over the canvas (the guide for hybrid matte edges), or null without pixels. */
+export declare function layerGuide(layer: ImageLayer, width: number, height: number, surfaceOf?: LayerSurfaceOf): Uint8ClampedArray | null;
 /**
  * The raster mask a layer composites with: its raster mask times its vector mask (layer space,
  * feather and density baked in), or the raster mask alone when there is no active vector mask.
  * A depth (parametric) mask cannot be combined, so it wins.
  */
-export declare function effectiveLayerMask(layer: ImageLayer, width: number, height: number): RasterMask | undefined;
+export declare function effectiveLayerMask(layer: ImageLayer, width: number, height: number, surfaceOf?: LayerSurfaceOf): RasterMask | undefined;
 /**
  * The stack as the compositor should see it: each layer with an active vector mask replaced by a
  * copy whose `mask` is `effectiveLayerMask` (cached per layer object and canvas size, so the
  * engine's tile caches keep working). Returns `layers` itself when there are none.
  */
-export declare function resolveVectorMasks(layers: readonly ImageLayer[], width: number, height: number): readonly ImageLayer[];
+export declare function resolveVectorMasks(layers: readonly ImageLayer[], width: number, height: number, surfaceOf?: LayerSurfaceOf): readonly ImageLayer[];
 /** A vector mask moved by (dx, dy) document pixels. */
 export declare function offsetVectorMask(vm: VectorMask, dx: number, dy: number): VectorMask;
 /** A vector mask with its paths mapped by `f` (document space); `affine` keeps live shapes live. */

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

@@ -22,6 +22,8 @@ export interface PathAnchorRef {
 export interface PathEditOverlay {
     /** The target's segments: 2 points for a line, 4 for a cubic. */
     curves: ImagePoint[][];
+    /** A hybrid vector mask's edge mode per curve (same order); missing: all hard. */
+    curveModes?: Array<'hard' | 'feather' | 'matte'>;
     /** Anchors shown; selected ones are drawn filled. */
     anchors: Array<{
         point: ImagePoint;
@@ -77,6 +79,8 @@ export declare class PathEditGesture {
     private selectComponent;
     private commit;
     down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt+Shift-click on a vector mask's segment: hard → feather → matte → hard (one undo step). */
+    private cycleEdge;
     /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
     private convert;
     private penDown;

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

@@ -22,6 +22,8 @@ export interface PathAnchorRef {
 export interface PathEditOverlay {
     /** The target's segments: 2 points for a line, 4 for a cubic. */
     curves: ImagePoint[][];
+    /** A hybrid vector mask's edge mode per curve (same order); missing: all hard. */
+    curveModes?: Array<'hard' | 'feather' | 'matte'>;
     /** Anchors shown; selected ones are drawn filled. */
     anchors: Array<{
         point: ImagePoint;
@@ -77,6 +79,8 @@ export declare class PathEditGesture {
     private selectComponent;
     private commit;
     down(p: ImagePoint, tool: PathEditTool, mods?: PathEditModifiers): void;
+    /** Alt+Shift-click on a vector mask's segment: hard → feather → matte → hard (one undo step). */
+    private cycleEdge;
     /** Alt-click: a corner anchor becomes smooth, a smooth one a corner (one undo step). */
     private convert;
     private penDown;

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

@@ -20,3 +20,4 @@ export * from './worker.cjs';
 export * from './inspect.cjs';
 export * from './uncertainty.cjs';
 export * from './diff.cjs';
+export * from './recipe.cjs';

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

@@ -20,3 +20,4 @@ export * from './worker.js';
 export * from './inspect.js';
 export * from './uncertainty.js';
 export * from './diff.js';
+export * from './recipe.js';

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

@@ -0,0 +1,89 @@
+/**
+ * Live selections: a selection kept as the steps that made it (its recipe) beside its bitmap, so a
+ * step can be edited, inserted or removed afterwards and the selection replayed. The bitmap stays
+ * what everything else uses; a change no step can describe drops the recipe (the selection is then
+ * frozen). Steps are plain JSON: the arguments the selection commands took.
+ */
+import type { CropBox, ImagePoint } from '../types.cjs';
+import { type PixelBuffer, type SelectionMask, type SelectionMode } from './mask.cjs';
+import { type ColorRangeSample } from './wand.cjs';
+import { type SelectionModifyOp } from './modify.cjs';
+import { type RefineEdgeParams } from './refine.cjs';
+/** Where pixel steps sample (as the selection commands' `SampleOptions`). */
+export interface RecipeSampling {
+    sample?: 'composite' | 'active-layer';
+    sampleMerged?: boolean;
+}
+/** How a new shape combines with what the earlier steps selected. */
+export interface RecipeCombine {
+    mode?: SelectionMode;
+    /** Feather the new shape by this many pixels before combining. */
+    feather?: number;
+    /** Invert the new shape before combining. */
+    invert?: boolean;
+}
+/** One step of a selection's recipe. */
+export type SelectionRecipeStep = ({
+    op: 'rect' | 'ellipse';
+    rect: CropBox;
+    antiAlias?: boolean;
+} & RecipeCombine) | ({
+    op: 'polygon';
+    points: ImagePoint[];
+    antiAlias?: boolean;
+} & RecipeCombine) | ({
+    op: 'magic-wand';
+    point: ImagePoint;
+    options?: Record<string, unknown>;
+} & RecipeCombine & RecipeSampling) | ({
+    op: 'color-range';
+    samples: ColorRangeSample[];
+    options?: Record<string, unknown>;
+} & RecipeCombine & RecipeSampling) | ({
+    op: 'color-range-preset';
+    preset: string;
+    falloff?: number;
+} & RecipeCombine & RecipeSampling) | {
+    op: 'all';
+} | {
+    op: 'invert';
+} | {
+    op: 'modify';
+    modify: SelectionModifyOp;
+    radius: number;
+} | ({
+    op: 'refine';
+    params: RefineEdgeParams;
+} & RecipeSampling);
+export type SelectionRecipeOp = SelectionRecipeStep['op'];
+export declare const SELECTION_RECIPE_OPS: readonly SelectionRecipeOp[];
+/** Steps that make a new shape (combined by `mode`); the rest change what is already selected. */
+export declare function isShapeStep(step: SelectionRecipeStep): boolean;
+/** Whether a step reads the image's pixels. */
+export declare function stepNeedsPixels(step: SelectionRecipeStep): boolean;
+/** A key for a pixel step's sampling (steps with the same key read the same pixels). */
+export declare function samplingKey(step: SelectionRecipeStep): string;
+/** Checks and copies one step (as JSON from an agent or a document); throws a useful error. */
+export declare function readRecipeStep(raw: unknown, at?: string): SelectionRecipeStep;
+/**
+ * The selection `steps` make on a `width × height` canvas, from nothing (null when nothing ends
+ * up selected). `pixelsFor` gives a pixel step its image (see `samplingKey`).
+ */
+export declare function replaySelectionRecipe(steps: readonly SelectionRecipeStep[], width: number, height: number, pixelsFor: (step: SelectionRecipeStep) => PixelBuffer): SelectionMask | null;
+/** A recipe as an agent reads it: each step with its index. */
+export declare function describeRecipe(steps: readonly SelectionRecipeStep[]): Array<{
+    index: number;
+} & SelectionRecipeStep>;
+/** A step in a few words, for a recipe list ("Rectangle 30 × 20 at 10, 10", "Smooth 2 px"). */
+export declare function describeRecipeStep(step: SelectionRecipeStep): string;
+/**
+ * A step's main setting for a recipe list (feather, tolerance, fuzziness, falloff or radius) and
+ * the change that sets it, or null for steps with none.
+ */
+export declare function recipeStepSetting(step: SelectionRecipeStep): {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    change: (v: number) => Record<string, unknown>;
+} | null;

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

@@ -0,0 +1,89 @@
+/**
+ * Live selections: a selection kept as the steps that made it (its recipe) beside its bitmap, so a
+ * step can be edited, inserted or removed afterwards and the selection replayed. The bitmap stays
+ * what everything else uses; a change no step can describe drops the recipe (the selection is then
+ * frozen). Steps are plain JSON: the arguments the selection commands took.
+ */
+import type { CropBox, ImagePoint } from '../types.js';
+import { type PixelBuffer, type SelectionMask, type SelectionMode } from './mask.js';
+import { type ColorRangeSample } from './wand.js';
+import { type SelectionModifyOp } from './modify.js';
+import { type RefineEdgeParams } from './refine.js';
+/** Where pixel steps sample (as the selection commands' `SampleOptions`). */
+export interface RecipeSampling {
+    sample?: 'composite' | 'active-layer';
+    sampleMerged?: boolean;
+}
+/** How a new shape combines with what the earlier steps selected. */
+export interface RecipeCombine {
+    mode?: SelectionMode;
+    /** Feather the new shape by this many pixels before combining. */
+    feather?: number;
+    /** Invert the new shape before combining. */
+    invert?: boolean;
+}
+/** One step of a selection's recipe. */
+export type SelectionRecipeStep = ({
+    op: 'rect' | 'ellipse';
+    rect: CropBox;
+    antiAlias?: boolean;
+} & RecipeCombine) | ({
+    op: 'polygon';
+    points: ImagePoint[];
+    antiAlias?: boolean;
+} & RecipeCombine) | ({
+    op: 'magic-wand';
+    point: ImagePoint;
+    options?: Record<string, unknown>;
+} & RecipeCombine & RecipeSampling) | ({
+    op: 'color-range';
+    samples: ColorRangeSample[];
+    options?: Record<string, unknown>;
+} & RecipeCombine & RecipeSampling) | ({
+    op: 'color-range-preset';
+    preset: string;
+    falloff?: number;
+} & RecipeCombine & RecipeSampling) | {
+    op: 'all';
+} | {
+    op: 'invert';
+} | {
+    op: 'modify';
+    modify: SelectionModifyOp;
+    radius: number;
+} | ({
+    op: 'refine';
+    params: RefineEdgeParams;
+} & RecipeSampling);
+export type SelectionRecipeOp = SelectionRecipeStep['op'];
+export declare const SELECTION_RECIPE_OPS: readonly SelectionRecipeOp[];
+/** Steps that make a new shape (combined by `mode`); the rest change what is already selected. */
+export declare function isShapeStep(step: SelectionRecipeStep): boolean;
+/** Whether a step reads the image's pixels. */
+export declare function stepNeedsPixels(step: SelectionRecipeStep): boolean;
+/** A key for a pixel step's sampling (steps with the same key read the same pixels). */
+export declare function samplingKey(step: SelectionRecipeStep): string;
+/** Checks and copies one step (as JSON from an agent or a document); throws a useful error. */
+export declare function readRecipeStep(raw: unknown, at?: string): SelectionRecipeStep;
+/**
+ * The selection `steps` make on a `width × height` canvas, from nothing (null when nothing ends
+ * up selected). `pixelsFor` gives a pixel step its image (see `samplingKey`).
+ */
+export declare function replaySelectionRecipe(steps: readonly SelectionRecipeStep[], width: number, height: number, pixelsFor: (step: SelectionRecipeStep) => PixelBuffer): SelectionMask | null;
+/** A recipe as an agent reads it: each step with its index. */
+export declare function describeRecipe(steps: readonly SelectionRecipeStep[]): Array<{
+    index: number;
+} & SelectionRecipeStep>;
+/** A step in a few words, for a recipe list ("Rectangle 30 × 20 at 10, 10", "Smooth 2 px"). */
+export declare function describeRecipeStep(step: SelectionRecipeStep): string;
+/**
+ * A step's main setting for a recipe list (feather, tolerance, fuzziness, falloff or radius) and
+ * the change that sets it, or null for steps with none.
+ */
+export declare function recipeStepSetting(step: SelectionRecipeStep): {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    change: (v: number) => Record<string, unknown>;
+} | null;

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

@@ -285,6 +285,7 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
  | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.cjs';
+import type { SelectionRecipeStep } from './selection/recipe.cjs';
 import type { BitDepth } from '../raster/deep.cjs';
 export interface ImageEditorState {
     sourceUrl: string | null;
@@ -319,6 +320,12 @@ export interface ImageEditorState {
      * growing as the brush moves). View state: not an edit, not in history, not saved.
      */
     selectionPreview?: SelectionMask | null;
+    /**
+     * Live selections: the steps that made `selection` (see `selection/recipe`), so they can be
+     * edited and replayed; null or missing when it is frozen (made or changed by something no step
+     * describes). Recorded in history and saved.
+     */
+    selectionRecipe?: SelectionRecipeStep[] | null;
     /**
      * `compare_selections`' overlay: the added area tinted green, the removed red. Shown while the
      * selection is still `selection` (any change hides it). View state: not in history, not saved.
@@ -418,6 +425,8 @@ export interface LegacySerializedImageEditorState {
     annotations: Annotation[];
     /** The active selection, run-length encoded. Missing when nothing is selected. */
     selection?: SerializedSelection;
+    /** The selection's recipe (live selections): the steps that made it, as JSON. */
+    selectionRecipe?: unknown[];
     /** Alpha channels (saved selections), run-length encoded. */
     channels?: SerializedAlphaChannel[];
     /** Document paths (the Paths panel). */

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

@@ -285,6 +285,7 @@ export type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'a
  | 'path-select' | 'direct-select' | 'path-pen';
 export type ImageEditorFit = 'contain' | 'margin';
 import type { DocumentColorMode, DocumentColorProfile, ProofSetup } from './color-management.js';
+import type { SelectionRecipeStep } from './selection/recipe.js';
 import type { BitDepth } from '../raster/deep.js';
 export interface ImageEditorState {
     sourceUrl: string | null;
@@ -319,6 +320,12 @@ export interface ImageEditorState {
      * growing as the brush moves). View state: not an edit, not in history, not saved.
      */
     selectionPreview?: SelectionMask | null;
+    /**
+     * Live selections: the steps that made `selection` (see `selection/recipe`), so they can be
+     * edited and replayed; null or missing when it is frozen (made or changed by something no step
+     * describes). Recorded in history and saved.
+     */
+    selectionRecipe?: SelectionRecipeStep[] | null;
     /**
      * `compare_selections`' overlay: the added area tinted green, the removed red. Shown while the
      * selection is still `selection` (any change hides it). View state: not in history, not saved.
@@ -418,6 +425,8 @@ export interface LegacySerializedImageEditorState {
     annotations: Annotation[];
     /** The active selection, run-length encoded. Missing when nothing is selected. */
     selection?: SerializedSelection;
+    /** The selection's recipe (live selections): the steps that made it, as JSON. */
+    selectionRecipe?: unknown[];
     /** Alpha channels (saved selections), run-length encoded. */
     channels?: SerializedAlphaChannel[];
     /** Document paths (the Paths panel). */

package/dist/paint-editor/index.cjs

@@ -7,7 +7,7 @@ var _chunkZ64NRDEHcjs = require('../chunk-Z64NRDEH.cjs');
 
 
 
-var _chunkS55JFWDAcjs = require('../chunk-S55JFWDA.cjs');
+var _chunkR35YOUP2cjs = require('../chunk-R35YOUP2.cjs');
 require('../chunk-A2IS7EHE.cjs');
 require('../chunk-SS53NNZO.cjs');
 
@@ -1659,11 +1659,11 @@ function header(state, options) {
   return out;
 }
 function serializePaintDocument(state, options = {}) {
-  const { layers, assets } = _chunkS55JFWDAcjs.serializeLayers.call(void 0, state.layers);
+  const { layers, assets } = _chunkR35YOUP2cjs.serializeLayers.call(void 0, state.layers);
   return { ...header(state, options), layers, assets };
 }
 async function serializePaintDocumentExternal(state, store, options = {}) {
-  const { layers, assets } = await _chunkS55JFWDAcjs.serializeLayersExternal.call(void 0, state.layers, store);
+  const { layers, assets } = await _chunkR35YOUP2cjs.serializeLayersExternal.call(void 0, state.layers, store);
   return { ...header(state, options), layers, assets };
 }
 function paintLayersOnly(layers, problems) {
@@ -1700,7 +1700,7 @@ function deserializePaintDocument(raw) {
   const canvas = normalizeCanvas({ width: r.width, height: r.height, dpi: _nullishCoalesce(r.dpi, () => ( void 0)) });
   const paper = _chunkROVK6AXXcjs.normalizePaper.call(void 0, _nullishCoalesce(r.paper, () => ( {})));
   const assets = r.assets && typeof r.assets === "object" ? r.assets : {};
-  const layers = paintLayersOnly(_chunkS55JFWDAcjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
+  const layers = paintLayersOnly(_chunkR35YOUP2cjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && _chunkB46UQUDCcjs.findLayer.call(void 0, layers, wanted) ? wanted : _nullishCoalesce(_optionalChain([_chunkB46UQUDCcjs.flattenLayers.call(void 0, layers), 'access', _70 => _70.filter, 'call', _71 => _71((l) => l.type === "pixel"), 'access', _72 => _72.pop, 'call', _73 => _73(), 'optionalAccess', _74 => _74.id]), () => ( null));
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
@@ -1716,7 +1716,7 @@ async function deserializePaintDocumentAsync(raw, store) {
   if (!raw || typeof raw !== "object") throw new Error("Not a paint document: expected a JSON object.");
   const r = raw;
   const problems = [];
-  const assets = await _chunkS55JFWDAcjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
+  const assets = await _chunkR35YOUP2cjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
   const loaded = deserializePaintDocument({ ...r, assets });
   return { ...loaded, problems: [...problems, ...loaded.problems] };
 }
@@ -5468,7 +5468,7 @@ var PaintEditorController = (_class10 = class _PaintEditorController {
       return next.type === "group" ? { ...next, children: toStandard(next.children) } : next;
     });
     const layers = toStandard(dried);
-    const result = _chunkS55JFWDAcjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
+    const result = _chunkR35YOUP2cjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
     for (const [mode, names] of changed) {
       const label = _nullishCoalesce(_optionalChain([_chunkOLNIPTB3cjs.BLEND_MODES, 'access', _279 => _279.find, 'call', _280 => _280((m) => m.id === mode), 'optionalAccess', _281 => _281.label]), () => ( mode));
       const std = _nullishCoalesce(_optionalChain([_chunkOLNIPTB3cjs.BLEND_MODES, 'access', _282 => _282.find, 'call', _283 => _283((m) => m.id === _chunkOLNIPTB3cjs.standardBlendMode.call(void 0, mode)), 'optionalAccess', _284 => _284.label]), () => ( _chunkOLNIPTB3cjs.standardBlendMode.call(void 0, mode)));

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-F7Z2MKY2.js";
+} from "../chunk-S6KKLFZO.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {

package/package.json

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

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

@@ -104,17 +104,8 @@ Keep outlines as paths (`make_work_path`, `add_path`) and edit their anchors: se
 
 ### Painting
 
-1. **Paint on its own layer** (`add_pixel_layer`), not on the Background (active on a new image, so
-   strokes without `layerId` land there) unless asked: a layer can be faded, masked or deleted.
-2. **Retouch through masks**, not the eraser (see `pixerate-image-selection-masking`).
-3. **One stroke is one call and one undo step.** Send the path's points in order (a few points
-   per brush diameter is enough; dabs are spaced by `brush.spacing`). Use `opacity` for the
-   overall strength and `flow` for gradual build-up within the stroke.
-4. **Limit paint with a selection**, or lock transparency (`set_layer_properties`
-   `locks.transparency`) to paint only where the layer already has pixels.
-5. **Mixing paint, the Mixer Brush and gradient paint**: `mix_colors` mixes named paints like
-   pigment; `paint_stroke` `tool: "mixer"` picks up and smears the layer's colours; gradient paint
-   changes colour along a stroke. Read [references/painting.md](references/painting.md) first.
+Paint on its own layer (`add_pixel_layer`), one stroke per call and one undo step, limited by a
+selection or locked transparency. Read [references/painting.md](references/painting.md) first.
 
 ### Colour management
 
@@ -207,6 +198,11 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
 | `inspect_mask_edge` | Measure an edge without looking: the selection (default) or a layer's `layer-mask` / `vector-mask` (`layerId`). Returns `haloScore`, `edgeAlignment`, `jaggedness`, `softFraction`, `holes`, `islands`, `worst` regions for `capture_view` and `issues` with fixes. Inspect, fix, inspect again (see `pixerate-image-selection-masking`). |
 | `compare_selections` | What changed between two selections: `a` (default the one before the last undo step) and `b` (default current), each `selection`, `history` (`steps`), `channel` or a layer's `layer-mask` / `vector-mask`. Returns `added` / `removed` (area, largest pieces with bounds), `iou` and `identical`; `show` tints the change on the canvas. Check every modify or refine step. |
+| `get_selection_recipe` | Read-only. Live selections: the steps that made the selection (marquees, polygons, magic wand, Color Range, modify, invert, refine) with indexes; `live: false` when frozen (made by a command steps cannot describe, e.g. `quick_select`). |
+| `edit_selection_step` | Change a recipe step (`index`, `changes`: e.g. `options.tolerance`, `rect`, `radius`, `mode`; a new `op` replaces it) and replay. One undo step. Returns the selection and recipe. |
+| `insert_selection_step` | Insert a step at `index` (length appends), e.g. a subtract rect before a refine, and replay. One undo step. |
+| `remove_selection_step` | Remove a recipe step and replay (not the only one: deselect instead). One undo step. |
+| `freeze_selection` | Keep the selection as it is and drop its recipe. One undo step. |
 | `list_channels` | Read the alpha channels (saved selections): id, name, bounds, percent, overlay and visibility, and whether Quick Mask mode is on. |
 | `select_subject` | Select › Subject. With a host segmentation model, `target` describes what to select ("the dog", "the sky") and the model's outlines are selected (`maxSegments` 1 for one). Without one, the subject that stands out most is found classically; `target` can't choose it (`method: "saliency"`, `note`). Combined by `mode`. Returns the selection, `found` (label, bounds) and `method`; nothing found leaves the selection unchanged. |
 | `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `shape`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`; shapes a `shape` summary of component ops and kinds and paint types, and `annotation` when migrated from one), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |