@pixerate/editor 0.220.0 → 0.221.1

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/inspect.d.cts

@@ -31,7 +31,7 @@ export interface MaskEdgeReport {
     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). */
+    /** 0–1: the share of edge pixels in a transition wider than anti-aliasing (partly covered, no fully selected and unselected pixel within 2 px). */
     softFraction: number;
     /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
     holes: {

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

@@ -31,7 +31,7 @@ export interface MaskEdgeReport {
     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). */
+    /** 0–1: the share of edge pixels in a transition wider than anti-aliasing (partly covered, no fully selected and unselected pixel within 2 px). */
     softFraction: number;
     /** Unselected areas enclosed by the selection, largest first (at most 10 listed). */
     holes: {

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.1",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -5,6 +5,11 @@ Each editor domain in `@pixerate/editor` ships an [Agent Skill](https://agentski
 expert in the domain would follow. They are published with the package, so an app or agent
 that uses the tools can load the matching skill.
 
+## Reference skills
+
+One per editor domain. A reference skill owns its domain's tool and command tables, its mental
+model and its general practice.
+
 | Skill | Covers |
 | --- | --- |
 | [`pixerate-agent-tools`](pixerate-agent-tools/SKILL.md) | What every editor has in common: the MCP bridge, toolsets and tool naming, finding tools with `list_toolsets` / `search_tools` / `enable_tools` / `get_skill`, `list_commands` / `run_command` / `run_commands`, errors, undo. Load it with any domain skill. |
@@ -15,12 +20,9 @@ that uses the tools can load the matching skill.
 | [`pixerate-chart`](pixerate-chart/SKILL.md) | Chart specs, data, series, presets, trendlines, Office and Mermaid charts. |
 | [`pixerate-diagram`](pixerate-diagram/SKILL.md) | Mermaid diagrams: nodes, edges, groups, layout. |
 | [`pixerate-image-editor`](pixerate-image-editor/SKILL.md) | Adjustments, adjustment layers, selections and masks. |
-| [`pixerate-image-selection-masking`](pixerate-image-selection-masking/SKILL.md) | Workflow: cutouts, background and sky replacement, local adjustments through masks; choosing a selection method, checking and refining edges, and outputting an editable mask. Built on `pixerate-image-editor`'s tools. |
 | [`pixerate-paint-editor`](pixerate-paint-editor/SKILL.md) | Natural-media painting: paper and grain, dry-media brushes, the brush library, strokes as data, pigment mixing. |
 | [`pixerate-animation-editor`](pixerate-animation-editor/SKILL.md) | Vector animation: shots, commands, timing, Flair and Lottie. |
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
-| [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. |
-| [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
 | [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
 | [`pixerate-tokens`](pixerate-tokens/SKILL.md) | Design tokens: collections, modes, variables and aliases, through the whole-set document tools. |
@@ -28,6 +30,20 @@ that uses the tools can load the matching skill.
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 | [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
 
+## Workflow skills
+
+A workflow skill covers one job from start to finish: what to confirm first, the steps in
+order with a check after each, a decision table, recipes and the job's pitfalls. It is built on
+its reference skill's tools (load both), and its description is written about the job, so a
+request like "clean up this export" finds it.
+
+| Skill | Editor | Covers |
+| --- | --- | --- |
+| [`pixerate-image-selection-masking`](pixerate-image-selection-masking/SKILL.md) | Image (`pixerate-image-editor`) | Cutouts, background and sky replacement, local adjustments through masks; choosing a selection method, checking and refining edges, and outputting an editable mask. |
+| [`pixerate-spreadsheet-clean-import`](pixerate-spreadsheet-clean-import/SKILL.md) | Spreadsheet (`pixerate-spreadsheet`) | Imported or pasted data made tidy: structure, headers, types (currency, comma decimals, day-first dates, leading zeros, missing values), text, duplicates and validation. |
+| [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Video (`pixerate-video-editor`) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. Owns the dialogue tools. |
+| [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Video (`pixerate-video-editor`) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. Owns the music tools. |
+
 ## Using them
 
 Copy or symlink the directories into your agent's skills folder, for example for Claude Code:
@@ -75,12 +91,27 @@ same change.
   `create*ToolProvider` / `create*Commands` factory is not mapped to a skill. A new domain
   gets a new skill directory, an entry in `expectedBySkill()` and `FACTORIES`, and a row in
   the table above.
-- **Workflow skills.** A skill that covers one job end to end on another skill's tools (for
-  example `pixerate-image-selection-masking` on `pixerate-image-editor`) has no tool table.
-  Its frontmatter adds `metadata` with `kind: workflow` and `reference: <skill>`, it lists the
-  tools it uses as bullets under `## Tools used`, and it is mapped in `WORKFLOWS` in the test
-  (and to `[]` in `expectedBySkill()`). The test checks that every tool it uses exists in the
-  reference skill.
+- **Workflow skills.** A skill that covers one job end to end on another skill's tools has no
+  tool table (unless the job has its own provider, as the two video ones do). Start from
+  [`WORKFLOW_TEMPLATE.md`](WORKFLOW_TEMPLATE.md). Its frontmatter adds `metadata` with
+  `kind: workflow` and `reference: <skill>`; it lists the tools it uses as bullets under
+  `## Tools used`; and it is mapped in `WORKFLOWS` in the test (and to `[]` in
+  `expectedBySkill()`). The test checks that every tool it uses exists in the reference skill,
+  that every backticked tool or command name in its prose is real, that the reference skill
+  names it under `## Workflow skills`, that it stays under 250 body lines (aim for 200) and that
+  it ships evals. Add its row to the workflow table above.
+- **Evals.** Each workflow skill ships at least three scenarios in `evals/*.json`, run by
+  `packages/core/tests/agent-skill-evals.test.ts`. An eval has a `prompt` (the task, in the
+  user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }` or
+  `{ "editor": "image", "width", "height", "background", "shapes" }`), `checks` (a read-only
+  tool, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
+  tool calls an expert would make). The test proves each eval: some check fails on the fixture,
+  and all pass after the solution. A model harness runs the same file with the model in place
+  of the solution. In `expect`, objects match key by key and arrays element by element, with
+  operators for ranges and lists (`$min`, `$max`, `$match`, `$every`, `$some`, `$length`,
+  `$unique`, `$distinct`, `$sum`, `$column`, `$nonEmpty`, `$not`, `$in`, `$type`); a check's
+  argument can read a value the job created with `{ "$read": "list_layers", "path":
+  "layers.-1.id" }`. Checks test the outcome the user asked for, not one way of getting it.
 - **Workflows and practice.** The test cannot check advice. When a feature changes the best
   way to do something (a new batch tool, a new check, a better default), update the working
   method and best practices too.

package/skills/WORKFLOW_TEMPLATE.md

@@ -0,0 +1,50 @@
+---
+name: pixerate-<editor>-<job>
+description: The <job> workflow in the Pixerate <editor> - <what it produces, in the user's words, and the main steps>. Use when asked to <trigger phrases: the verbs and nouns people use for this job>, or when <a tool or two that signal the job> are available. Load with pixerate-<editor>, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-<editor>
+---
+
+# <The job, as a short title>
+
+<Two to four sentences: the model of the job a person needs before starting. What the
+document is made of here, and the one or two facts that make this job go right or wrong.>
+
+This skill is the method. `pixerate-<editor>` has the full tool reference.
+
+## Goal and quality bar
+
+- <What the finished result is, stated so it can be checked: numbers, ranges, absences.>
+- <What must stay editable, reversible or untouched.>
+
+## Inputs to confirm
+
+Ask when you cannot tell from the document; say what you assumed when you can.
+
+- **<Decision>:** <the options, and the default when the user does not say>.
+
+## Working method
+
+1. **<Step>.** <What to do, with which tool and which arguments matter (units, defaults).>
+   **Check:** <a read tool and what its result must show before going on>.
+2. **<Step>.** ...
+   **Check:** ...
+
+## Decision table
+
+| Situation | Approach |
+| --- | --- |
+| <case> | <method, tool, setting> |
+
+## Recipes
+
+**<Common request>.** <The tool calls in order, with arguments, as short prose.>
+
+## Pitfalls
+
+- **<Failure>.** <Why it happens and how to avoid or detect it.>
+
+## Tools used
+
+- `<tool_name>`, `<tool_name>`: <one-line purpose in this job>

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

@@ -33,6 +33,13 @@ Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for
 - **Coordinates** for selections are natural pixels of the source image (before crop, rotate
   or flip). Read `get_selection` bounds or the image size, never screen pixels.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-image-selection-masking`: cutouts, background and sky replacement, local adjustments through masks.
+
 ## Working method
 
 1. **Read.** `get_adjustments` for the current values, process version and layers;
@@ -104,17 +111,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 +205,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

package/skills/pixerate-image-selection-masking/evals/local-adjustment.json

@@ -0,0 +1,22 @@
+{
+	"prompt": "Make just the red ball black and white, and keep it adjustable so I can tweak it later. The sign in the corner should stay red.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [40, 90, 200],
+		"shapes": [
+			{ "shape": "ellipse", "x": 40, "y": 20, "width": 40, "height": 40, "color": [210, 40, 40] },
+			{ "shape": "rect", "x": 100, "y": 6, "width": 12, "height": 8, "color": [210, 40, 40] }
+		]
+	},
+	"checks": [
+		{ "why": "a Black & White adjustment layer, masked to the ball and not the sign", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "adjustment", "kind": "blackWhite", "mask": { "kind": "raster", "defaultValue": 0, "paintedBounds": { "x": { "$min": 38, "$max": 41 }, "y": { "$min": 18, "$max": 21 }, "width": { "$min": 39, "$max": 44 }, "height": { "$min": 39, "$max": 44 } } } } } } },
+		{ "why": "the photo's own pixels are not changed", "tool": "list_layers", "expect": { "layers": { "$some": { "id": "background", "type": "pixel", "mask": null } } } }
+	],
+	"solution": [
+		{ "tool": "magic_wand", "args": { "x": 60, "y": 40, "tolerance": 20, "contiguous": true } },
+		{ "tool": "get_selection" },
+		{ "tool": "add_adjustment_layer", "args": { "kind": "blackWhite" } }
+	]
+}

package/skills/pixerate-image-selection-masking/evals/mask-out-background.json

@@ -0,0 +1,24 @@
+{
+	"prompt": "Hide the blue background so only the red ball shows. Don't delete any pixels; I may want the background back later.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [40, 90, 200],
+		"shapes": [
+			{ "shape": "ellipse", "x": 40, "y": 20, "width": 40, "height": 40, "color": [210, 40, 40] },
+			{ "shape": "rect", "x": 100, "y": 6, "width": 12, "height": 8, "color": [210, 40, 40] }
+		]
+	},
+	"checks": [
+		{ "why": "the top layer has a layer mask that reveals only the ball", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "pixel", "mask": { "kind": "raster", "enabled": true, "defaultValue": 0, "paintedBounds": { "x": { "$min": 38, "$max": 41 }, "y": { "$min": 18, "$max": 21 }, "width": { "$min": 39, "$max": 44 }, "height": { "$min": 39, "$max": 44 } } } } } } },
+		{ "why": "the mask edge is clean", "tool": "inspect_mask_edge", "args": { "target": "layer-mask", "layerId": { "$read": "list_layers", "path": "layers.-1.id" } }, "expect": { "issues": [], "haloScore": { "$max": 0.35 } } }
+	],
+	"solution": [
+		{ "tool": "list_layers" },
+		{ "tool": "magic_wand", "args": { "x": 60, "y": 40, "tolerance": 20, "contiguous": true } },
+		{ "tool": "inspect_mask_edge" },
+		{ "tool": "add_layer_mask", "args": { "layerId": "background", "from": "selection" } },
+		{ "tool": "inspect_mask_edge", "args": { "target": "layer-mask", "layerId": "background" } }
+	]
+}

package/skills/pixerate-image-selection-masking/evals/select-one-of-two.json

@@ -0,0 +1,22 @@
+{
+	"prompt": "Select the red ball in the middle of the photo, not the red sign in the top-right corner. Just the selection for now; I'll decide what to do with it.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [40, 90, 200],
+		"shapes": [
+			{ "shape": "ellipse", "x": 40, "y": 20, "width": 40, "height": 40, "color": [210, 40, 40] },
+			{ "shape": "rect", "x": 100, "y": 6, "width": 12, "height": 8, "color": [210, 40, 40] }
+		]
+	},
+	"checks": [
+		{ "why": "the selection hugs the ball and leaves the sign out", "tool": "get_selection", "expect": { "empty": false, "bounds": { "x": { "$min": 38, "$max": 41 }, "y": { "$min": 18, "$max": 21 }, "width": { "$min": 39, "$max": 44 }, "height": { "$min": 39, "$max": 44 } }, "percent": { "$min": 12, "$max": 14.5 } } },
+		{ "why": "a clean edge: no halo, holes or islands", "tool": "inspect_mask_edge", "expect": { "issues": [], "holes": { "count": 0 }, "islands": { "count": 0 } } }
+	],
+	"solution": [
+		{ "tool": "magic_wand", "args": { "x": 60, "y": 40, "tolerance": 20, "contiguous": true } },
+		{ "tool": "get_selection" },
+		{ "tool": "inspect_mask_edge" }
+	]
+}

package/skills/pixerate-spreadsheet/SKILL.md

@@ -15,6 +15,13 @@ leading `'` forces text.
 
 Errors, namespacing and `run_commands` batching are in the `pixerate-agent-tools` skill.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-spreadsheet-clean-import`: tidying imported or pasted data: structure, headers, types, dates, duplicates.
+
 ## Working method
 
 1. **Read.** `get_range` on the area you will touch (and its header row). The result gives