@pixerate/editor 0.220.0 → 0.221.0

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

@@ -242,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

@@ -242,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.220.0",
+  "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. |

package/skills/pixerate-image-editor/references/painting.md

@@ -1,4 +1,20 @@
-# Painting: mixing paint, the Mixer Brush and gradient paint
+# Painting: strokes, mixing paint, the Mixer Brush and gradient paint
+
+## Strokes
+
+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. See below.
+
+## Mixing paint, the Mixer Brush and gradient paint
 
 Read this before `mix_colors`, a `paint_stroke` with `tool: "mixer"`, or gradient paint
 (`set_paint` / `paint_stroke` `paint`).

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

@@ -40,9 +40,9 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    **Check:** `get_selection` → `empty: false` and a plausible `percent` (for a person in a
    portrait, typically 15–50 %). A wand or range above about 80 % has flooded: undo, then lower
    `tolerance` / `fuzziness`.
-2. **Build it in steps** with `mode`: start with `replace`, `add` what was missed, `subtract`
-   what leaked, and `intersect` to limit it to a region (for example `select_rect` around the
-   subject).
+2. **Build it in steps** with `mode`: `replace`, then `add` what was missed, `subtract` what
+   leaked, `intersect` to limit it. The steps are kept (`get_selection_recipe`): fix one with
+   `edit_selection_step` (a wand's tolerance, a box) rather than starting over.
    **Check:** `bounds` hug the subject. A bounds as large as the image means a leak. Smart tools
    return `uncertainRegions` (edge with no image edge under it): look there, refine with `regions`.
 3. **Measure the edge, then look.** `inspect_mask_edge` scores it: `haloScore` ≥ 0.35 is old