@pixerate/editor 0.221.1 → 0.222.0

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

@@ -2,7 +2,7 @@ import type { AgentTool } from '../tools/registry.cjs';
 import type { ImageEditorController } from './controller.cjs';
 /**
  * Agent tools for the image editor's layers, geometry and history: `get_image_info`,
- * `get_histogram`, `update_adjustment_layer`, `remove_adjustment_layer`,
+ * `get_histogram`, `measure_region`, `update_adjustment_layer`, `remove_adjustment_layer`,
  * `move_adjustment_layer`, `set_crop`, `reset_crop`, `set_rotation`, `flip_image`,
  * `set_bit_depth`, `undo_image` and `redo_image`. Each write is one undo step and returns what changed.
  */

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

@@ -2,7 +2,7 @@ import type { AgentTool } from '../tools/registry.js';
 import type { ImageEditorController } from './controller.js';
 /**
  * Agent tools for the image editor's layers, geometry and history: `get_image_info`,
- * `get_histogram`, `update_adjustment_layer`, `remove_adjustment_layer`,
+ * `get_histogram`, `measure_region`, `update_adjustment_layer`, `remove_adjustment_layer`,
  * `move_adjustment_layer`, `set_crop`, `reset_crop`, `set_rotation`, `flip_image`,
  * `set_bit_depth`, `undo_image` and `redo_image`. Each write is one undo step and returns what changed.
  */

package/dist/image-editor/index.cjs

@@ -15325,10 +15325,43 @@ function createImageEditTools(controller) {
     annotations: { title: "Read the histogram", ...READ },
     handler: ({ bins }) => {
       const h = controller.getHistogram();
-      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again.");
+      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again, or measure_region, which needs no render.");
       return histogramSummary(h, bins);
     }
   };
+  const measureRegion = {
+    name: "measure_region",
+    title: "Measure part of the image",
+    description: "Measures the composited image (every layer and adjustment, before crop, rotation and output opacity) in a rectangle, without rendering: the histogram summary of get_histogram (per channel and luminance mean, 1st / 99th percentiles 0-255, clipping percentages) plus the mean colour as hex and a cast (red minus blue, green minus the red-blue average, in levels; near 0 is neutral). Use it to check a correction in numbers: a known-neutral area (a white wall, a grey card) should have a cast within about \xB14; skin, sky or a product colour should land where you aim. Works where render_preview cannot. Annotation layers are left out.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "integer", minimum: 0, description: "Left edge in natural image pixels (default: the crop, else the whole image)." },
+        y: { type: "integer", minimum: 0, description: "Top edge in natural image pixels." },
+        width: { type: "integer", minimum: 1, description: "Width in pixels." },
+        height: { type: "integer", minimum: 1, description: "Height in pixels." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Measure part of the image", ...READ },
+    handler: ({ x, y, width, height }) => {
+      const given = [x, y, width, height].filter((v) => v !== void 0).length;
+      if (given !== 0 && given !== 4) throw new Error("Give x, y, width and height together, or none to measure the crop (or the whole image).");
+      const { width: W, height: H } = controller.getState().imageDimensions;
+      const rect3 = given ? { x, y, width, height } : _nullishCoalesce(controller.getState().crop, () => ( { x: 0, y: 0, width: W, height: H }));
+      if (rect3.x + rect3.width > W || rect3.y + rect3.height > H) throw new Error(`The rectangle runs past the image (${W} \xD7 ${H} px); keep x + width \u2264 ${W} and y + height \u2264 ${H}.`);
+      const h = computeHistogram(controller.compositePixels(rect3));
+      const summary3 = histogramSummary(h, void 0);
+      const mean = (bins) => {
+        let sum = 0;
+        for (let i = 0; i < bins.length; i++) sum += i * bins[i];
+        return h.samples ? sum / h.samples : 0;
+      };
+      const [r, g, b] = [mean(h.red), mean(h.green), mean(h.blue)];
+      const hex = "#" + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+      return { rect: rect3, ...summary3, meanColor: h.samples ? hex : null, cast: { redBlue: round(r - b, 1), greenMagenta: round(g - (r + b) / 2, 1) } };
+    }
+  };
   const updateLayer = {
     name: "update_adjustment_layer",
     title: "Change an adjustment layer",
@@ -15485,7 +15518,7 @@ function createImageEditTools(controller) {
       return history();
     }
   };
-  return [getImageInfo, getHistogram, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
+  return [getImageInfo, getHistogram, measureRegion, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
 }
 
 // src/image-editor/layer-tools.ts

package/dist/image-editor/index.js

@@ -15325,10 +15325,43 @@ function createImageEditTools(controller) {
     annotations: { title: "Read the histogram", ...READ },
     handler: ({ bins }) => {
       const h = controller.getHistogram();
-      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again.");
+      if (!h) throw new Error("No histogram yet: it comes from the rendered preview. Call render_preview, then try again, or measure_region, which needs no render.");
       return histogramSummary(h, bins);
     }
   };
+  const measureRegion = {
+    name: "measure_region",
+    title: "Measure part of the image",
+    description: "Measures the composited image (every layer and adjustment, before crop, rotation and output opacity) in a rectangle, without rendering: the histogram summary of get_histogram (per channel and luminance mean, 1st / 99th percentiles 0-255, clipping percentages) plus the mean colour as hex and a cast (red minus blue, green minus the red-blue average, in levels; near 0 is neutral). Use it to check a correction in numbers: a known-neutral area (a white wall, a grey card) should have a cast within about \xB14; skin, sky or a product colour should land where you aim. Works where render_preview cannot. Annotation layers are left out.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "integer", minimum: 0, description: "Left edge in natural image pixels (default: the crop, else the whole image)." },
+        y: { type: "integer", minimum: 0, description: "Top edge in natural image pixels." },
+        width: { type: "integer", minimum: 1, description: "Width in pixels." },
+        height: { type: "integer", minimum: 1, description: "Height in pixels." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Measure part of the image", ...READ },
+    handler: ({ x, y, width, height }) => {
+      const given = [x, y, width, height].filter((v) => v !== void 0).length;
+      if (given !== 0 && given !== 4) throw new Error("Give x, y, width and height together, or none to measure the crop (or the whole image).");
+      const { width: W, height: H } = controller.getState().imageDimensions;
+      const rect3 = given ? { x, y, width, height } : controller.getState().crop ?? { x: 0, y: 0, width: W, height: H };
+      if (rect3.x + rect3.width > W || rect3.y + rect3.height > H) throw new Error(`The rectangle runs past the image (${W} \xD7 ${H} px); keep x + width \u2264 ${W} and y + height \u2264 ${H}.`);
+      const h = computeHistogram(controller.compositePixels(rect3));
+      const summary3 = histogramSummary(h, void 0);
+      const mean = (bins) => {
+        let sum = 0;
+        for (let i = 0; i < bins.length; i++) sum += i * bins[i];
+        return h.samples ? sum / h.samples : 0;
+      };
+      const [r, g, b] = [mean(h.red), mean(h.green), mean(h.blue)];
+      const hex = "#" + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+      return { rect: rect3, ...summary3, meanColor: h.samples ? hex : null, cast: { redBlue: round(r - b, 1), greenMagenta: round(g - (r + b) / 2, 1) } };
+    }
+  };
   const updateLayer = {
     name: "update_adjustment_layer",
     title: "Change an adjustment layer",
@@ -15485,7 +15518,7 @@ function createImageEditTools(controller) {
       return history();
     }
   };
-  return [getImageInfo, getHistogram, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
+  return [getImageInfo, getHistogram, measureRegion, updateLayer, removeLayer2, moveLayer2, setCrop, resetCrop, setRotation, flipImage, setBitDepth, undo, redo];
 }
 
 // src/image-editor/layer-tools.ts

package/package.json

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

package/skills/README.md

@@ -40,6 +40,9 @@ 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-image-photo-correction`](pixerate-image-photo-correction/SKILL.md) | Image (`pixerate-image-editor`) | Global correction in order: straighten and crop, exposure and white balance, points and contrast, colour, local, look; each checked for clipping and neutral greys. |
+| [`pixerate-image-portrait-retouch`](pixerate-image-portrait-retouch/SKILL.md) | Image (`pixerate-image-editor`) | Blemishes, stray hairs and flaws healed on their own layer, dodge and burn, eyes and teeth, kept natural. |
+| [`pixerate-image-product-photo`](pixerate-image-product-photo/SKILL.md) | Image (`pixerate-image-editor`) | Product cutouts on pure white or a brand colour, a grounding shadow, accurate colour, centred marketplace crops. |
 | [`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. |

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

@@ -7,20 +7,13 @@ description: How to colour-correct, composite and retouch a photo in the Pixerat
 
 The image editor holds a layer stack over a canvas the size of the source image. Opening an
 image gives one pixel layer, **Background**, whose pixels are the source and whose `develop`
-filter holds the base adjustments; adjustment layers sit above it (bottom to top, each through
-its mask, opacity and blend mode) and every annotation is its own layer on top (pen, rectangle,
-ellipse, line and arrow annotations are shape layers, text annotations type layers, that remember
-them). `list_layers`
-shows the whole stack. Edits never touch the source pixels. The base controls edit the develop
-filter of the active pixel layer (the Background unless another pixel layer is active); base
-`blur` blurs that layer (or, in documents saved before layers with blur and adjustment layers,
-the output after the layers), and base `opacity` is the output's alpha. Pixel, annotation, group
-and smart object layers can carry live effects (shadows, glows, bevels, overlays, strokes). A smart
-object places contents (pixels or a nested layer document) through a transform and smart filters,
-re-rendered from the contents on every change. A shape layer holds vector paths with a fill and a
-stroke, rendered again from the paths on every change, so it stays sharp through any transform. A
-type layer holds live, styled text (point or paragraph) drawn with the editor's fonts.
-Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for errors and batching.
+filter holds the base adjustments (the base controls edit the develop filter of the active pixel
+layer). Adjustment layers sit above it, each through its mask, opacity and blend mode, and
+annotations are shape and type layers on top. Edits never touch the source pixels; `list_layers`
+shows the whole stack. Pixel, group and smart object layers can carry live effects; a smart
+object places contents through a transform and smart filters; shape layers hold vector paths and
+type layers live text, re-rendered on every change. There is also an optional selection and a
+crop, rotation and flip. See `pixerate-agent-tools` for errors and batching.
 
 - **Control ids** for base adjustments: `brightness`, `contrast`, `exposure`, `temperature`,
   `tint`, `saturation` (all -100..100, default 0), `blur` (0..30 px) and `opacity` (0..1).
@@ -38,7 +31,10 @@ Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for
 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-photo-correction`: global correction in order (frame, light, colour, local, look), with clipping and neutral checks.
 - `pixerate-image-selection-masking`: cutouts, background and sky replacement, local adjustments through masks.
+- `pixerate-image-portrait-retouch`: blemishes, stray hairs, dodge and burn, eyes and teeth.
+- `pixerate-image-product-photo`: product on white, a grounding shadow, marketplace crops.
 
 ## Working method
 
@@ -46,19 +42,15 @@ the pitfalls, and uses the tools below.
    `get_image_info` for the image size, crop and rotation; `list_controls` once for control
    ids, ranges, layer kinds and blend modes; `render_preview` (default 512 px) to see the
    image, then `get_histogram` to judge exposure and clipping in numbers.
-2. **Plan the order of corrections** (see Best practices): straighten and crop first (so
-   later judgements are on the final frame), then global tone and white balance,
-   then contrast and tone curves, then colour, then local fixes through masks, then creative
-   looks.
+2. **Plan the order:** frame, light, colour, local, look (`pixerate-image-photo-correction`).
 3. **Write in few steps.** Put every base change of one correction into one `set_adjustments`
    call (one undo step) with a `label`. Create layers with their `params` in the same
    `add_adjustment_layer` call rather than adding a neutral layer and then setting it.
 4. **Local edits:** select, refine, check with `get_selection`, then `apply_selection_as_mask`
    with a `kind`. Load `pixerate-image-selection-masking` for cutouts, masks and local edits.
-5. **Verify.** `render_preview` after each group of corrections, not after each slider, then
-   `get_histogram` (it reads the last render) for clipping. Compare against the previous
-   preview; read the `applied` and `clamped` lists that writes return. `undo_image` takes back a
-   step that made things worse.
+5. **Verify** after each group of corrections: `measure_region` (no render needed) or
+   `render_preview` then `get_histogram`; read the `applied` and `clamped` lists writes return.
+   `undo_image` takes back a step that made things worse.
 
 ### Working with layers
 
@@ -92,12 +84,9 @@ filters, so nothing degrades. Read [references/smart-objects.md](references/smar
 
 ### Shapes and text
 
-Draw boxes, badges, arrows and callouts as shape layers (`add_shape_layer` with a live `shape`,
-then `set_shape_component` / `update_shape` / `add_shape_component`), and text as type layers
-(`add_text_layer`, then `set_text`, `set_text_style`, `set_paragraph_style` by `start` / `end`
-range). Both stay sharp through transforms and take effects, masks and blend modes; rasterize only
-to paint on them. Read [references/shapes-and-type.md](references/shapes-and-type.md) before
-drawing or editing either.
+Boxes, badges, arrows and callouts are shape layers (`add_shape_layer`), text is type layers
+(`add_text_layer`); both stay sharp and take effects, masks and blends. Read
+[references/shapes-and-type.md](references/shapes-and-type.md) before drawing or editing either.
 
 ### Layer effects
 
@@ -117,12 +106,11 @@ selection or locked transparency. Read [references/painting.md](references/paint
 ### Colour management
 
 Working space, profiles, soft proofing and print conversions: read [references/color-management.md](references/color-management.md).
+
 ### Retouching
 
-Clone Stamp, Healing Brush, Spot Healing, Smudge, Dodge, Burn, Sponge, Blur, Sharpen and the
-History Brush: retouch on an empty layer with `sample: "current-below"`, pick `spot_heal` for small
-spots, `heal_brush` for larger flaws and `clone_stamp` to copy exactly (`set_clone_transform` scales,
-rotates or flips the source), and keep strokes short and soft. Read [references/retouching.md](references/retouching.md) first.
+Heal, clone, dodge and burn on layers above the photo (`sample: "current-below"`): load
+`pixerate-image-portrait-retouch`, and read [references/retouching.md](references/retouching.md) first.
 
 ### Photoshop files
 
@@ -135,27 +123,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 - **Non-destructive first.** Prefer an adjustment layer over pushing a base slider to its
   limit: layers can be masked, faded with `opacity`, blended and stacked. Use base sliders for
   global exposure and white balance, layers for everything you may want to tune later.
-- **Order of corrections** (as in a raw / Photoshop workflow): exposure and white balance
-  (`exposure`, `temperature`, `tint`) → black and white points and contrast (a `levels` layer,
-  then a gentle S-curve `curves` layer) → colour (`vibrance` before `saturation`,
-  `hueSaturation` per range, `colorBalance`) → local adjustments through masks → creative looks
-  (`photoFilter`, `blackWhite`, `posterize`). Correct before you stylise.
-- **Avoid clipping.** Set levels black and white points (`master.inBlack`, `master.inWhite`)
-  just inside where the image data starts (the histogram's `p1` / `p99`), not past it; large
-  `exposure` or `contrast` values blow highlights and crush shadows in the output. More than
-  about 0.5% of pixels in `clipping.highlightsPercent` or `shadowsPercent` on a normal photo
-  means detail is lost; check bright skies, skin and deep shadows in `render_preview` too.
-- **Straighten, then crop.** Level horizons with `set_rotation` (small angles such as -2.5);
-  any angle that is not a quarter turn leaves transparent corners, so crop inside them with
-  `set_crop` afterwards. Keep a standard aspect ratio (3:2, 4:3, 16:9, 1:1, 4:5) unless asked
-  otherwise, and do not crop away the subject's space to look or move into.
-- **Small moves.** Real corrections are usually within ±10..30 on these scales. Prefer
-  `vibrance` over `saturation` for portraits (it protects already-saturated colours and skin).
-- **Contrast through curves.** A curves S-curve keeps endpoints fixed and avoids the flat
-  greys that a big `contrast` value with low `exposure` produces. Curve points are levels
-  0..255 (`{ input, output }`); keep `(0,0)` and `(255,255)` and move quarter-tones by 10..25.
-- **Neutral greys.** Use `temperature` / `tint` (or `colorBalance` midtones) so known-neutral
-  areas (white walls, grey roads, clouds) have no cast; then add warmth deliberately if wanted.
+- **Correct in order** (frame, light, colour, local, look) and measure clipping and neutrals after
+  each step: `pixerate-image-photo-correction` has the method and settings.
 - **Masks:** select, refine, then mask; see `pixerate-image-selection-masking`.
 - **Blend modes for tone-only or colour-only changes:** `luminosity` applies a curves or
   levels layer without shifting hue or saturation; `color` applies a tint without changing
@@ -166,29 +135,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
   natural colour mixing and painterly strokes; it is not a Photoshop mode, so keep it off
   layers that must survive a PSD round trip. It costs about ten times a normal blend.
 - **Name layers** (`name`) by intent ("Sky darken", "Warm skin"), so the stack stays readable.
-- **Effects: subtle first.** A drop shadow reads as natural with a small `distance` (2..10 px),
-  a `size` a little larger than the distance, `opacity` 0.3..0.6 and the default multiply; a
-  hard, dark, far shadow looks pasted on. Glows want `screen` and a light colour; strokes on
-  text 1..4 px. Bevels: `depth` 1..2 and `size` a fraction of the shape's thickness.
-- **Outline-only looks** (an outlined title, a glass button): set the layer's `fillOpacity` to
-  0 with `set_layer_properties` and keep its effects; fill opacity hides the layer's own pixels,
-  layer `opacity` fades the effects too.
-- **Prefer an effect over painted pixels** for shadows, glows, outlines and colour fills of a
-  shape: it follows later edits and stays adjustable.
-- **Transforms: one resample, bicubic, whole pixels when you can.** Combine a scale, rotation and
-  move into one `transform_layer` call; use `rotate_layer_90` / `flip_layer` (exact) instead of
-  `rotate: 90` or `scaleX: -100`. `interpolation: "nearest"` keeps hard pixel art crisp; bicubic
-  (default) is right for photos, bilinear is a little softer. Enlarging past about 200 % shows
-  softness: prefer a larger source.
-- **Scale proportionally** unless asked to stretch: give `scaleX` and `scaleY` the same value.
-  Keep the subject in frame: after a scale about `center` the layer can run past the canvas,
-  which `bounds` in the result shows.
-- **Smart objects for anything you may scale again.** Convert first, then transform as often as
-  needed; set exact sizes with `set_smart_object_transform` `scaleX` / `scaleY` (percent of the
-  contents) rather than chaining relative scales. Prefer smart filters over layer filters when
-  the user may want to mask, blend or reorder them later.
-- **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
-  identical (a logo placed twice); use `linked: false` when the copies will be edited apart.
+- **Effects, transforms and smart objects** have their own best practices in
+  `references/layer-effects.md`, `references/free-transform.md` and `references/smart-objects.md`.
 - **Merge Down only onto an opaque, 100 % lower layer** when the result must look the same:
   the merged layer keeps the lower layer's opacity and blend, so a faded lower layer fades the
   merged content too, and a blend mode on the upper layer stops seeing what was below the lower
@@ -216,6 +164,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
 | `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, `bitDepth` (8, 16 or 32), the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
 | `get_histogram` | Judge exposure numerically: per channel and luminance `mean`, `p1` and `p99` (0..255), and `clipping` percent at pure black and white per channel. Reads the last render, so call `render_preview` first. `bins` (16, 32, 64 or 256) adds the counts. Cheaper than another image for checking a tonal change. |
+| `measure_region` | Measure a rectangle of the composited image (`x`, `y`, `width`, `height` in natural pixels; default the crop, else the whole image) without a render: the `get_histogram` summary plus `meanColor` (hex) and `cast` (`redBlue`, `greenMagenta` in levels; within about ±4 is neutral). Check a neutral reference, skin, a background or clipping after each correction. |
 | `render_preview` | See the edited image (crop, adjustments, layers, annotations) as a PNG, or with `layerId` one layer alone. `maxSide` 16..2048 px, default 512. Images cost tokens: render after a group of edits, use 512 for overall look and 1024+ to judge clipping, edges and masks. Fails in environments without rendering. |
 | `inspect_psd` | Read a PSD / PSB (`data` base64) without opening it: size, `depth`, `colorMode`, `resolution`, every layer bottom first with `psdKind`, the `type` it would become (`smart`, `shape` and `type` for Photoshop smart objects, shapes and text) and `status` (`mapped`, `approximated`, `dropped`) with `notes`, and the import `warnings`. Call before `import_psd`. |
 | `export_psd` | Save the document as an RGB PSD at its bit depth (PSB above 30000 px) with layers, groups, adjustment layers and masks. Returns `data` (base64), `size` in bytes, `psb` and `warnings` (crop or rotation not applied, filters and depth masks baked, annotations rasterized or left out, Pigment blends written as Normal). Shape and type layers are written as real Photoshop shape and type layers. Changes nothing. |

package/skills/pixerate-image-editor/references/free-transform.md

@@ -20,3 +20,14 @@ How to move, scale, rotate, skew, distort and warp layers, selected pixels and m
 4. **Transform once.** Every call resamples the pixels, so chained calls soften them: put scale,
    rotation and move into one `transform_layer` call (or one matrix) instead of several.
 5. **Look**: `render_preview`, or `capture_view` at the edges; each call is one undo step.
+
+## Best practices
+
+- **Transforms: one resample, bicubic, whole pixels when you can.** Combine a scale, rotation and
+  move into one `transform_layer` call; use `rotate_layer_90` / `flip_layer` (exact) instead of
+  `rotate: 90` or `scaleX: -100`. `interpolation: "nearest"` keeps hard pixel art crisp; bicubic
+  (default) is right for photos, bilinear is a little softer. Enlarging past about 200 % shows
+  softness: prefer a larger source.
+- **Scale proportionally** unless asked to stretch: give `scaleX` and `scaleY` the same value.
+  Keep the subject in frame: after a scale about `center` the layer can run past the canvas,
+  which `bounds` in the result shows.

package/skills/pixerate-image-editor/references/layer-effects.md

@@ -22,3 +22,15 @@ Read this before `add_layer_effect`, `update_layer_effect`, `set_global_light` o
    every effect of a layer (each keeps its own `enabled`); `scale` resizes them all (Scale
    Effects), e.g. after resizing a layer's content.
 5. **Look after each change**: `render_preview` (with `layerId` for one layer alone).
+
+## Best practices
+
+- **Effects: subtle first.** A drop shadow reads as natural with a small `distance` (2..10 px),
+  a `size` a little larger than the distance, `opacity` 0.3..0.6 and the default multiply; a
+  hard, dark, far shadow looks pasted on. Glows want `screen` and a light colour; strokes on
+  text 1..4 px. Bevels: `depth` 1..2 and `size` a fraction of the shape's thickness.
+- **Outline-only looks** (an outlined title, a glass button): set the layer's `fillOpacity` to
+  0 with `set_layer_properties` and keep its effects; fill opacity hides the layer's own pixels,
+  layer `opacity` fades the effects too.
+- **Prefer an effect over painted pixels** for shadows, glows, outlines and colour fills of a
+  shape: it follows later edits and stays adjustable.

package/skills/pixerate-image-editor/references/smart-objects.md

@@ -26,3 +26,12 @@ How to work with smart objects in the image editor (see the main skill for the t
    in a new image for every linked instance; `export_smart_object_contents` returns the file.
 6. **Finish**: `rasterize_smart_object` only when the user wants plain pixels to paint on; the
    placement and filters are then gone.
+
+## Best practices
+
+- **Smart objects for anything you may scale again.** Convert first, then transform as often as
+  needed; set exact sizes with `set_smart_object_transform` `scaleX` / `scaleY` (percent of the
+  contents) rather than chaining relative scales. Prefer smart filters over layer filters when
+  the user may want to mask, blend or reorder them later.
+- **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
+  identical (a logo placed twice); use `linked: false` when the copies will be edited apart.

package/skills/pixerate-image-photo-correction/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: pixerate-image-photo-correction
+description: The global photo correction workflow in the Pixerate image editor - straightening and cropping, then exposure and white balance, black and white points, contrast and tone curves, colour and saturation, local fixes and finally a look, each checked in numbers (histogram, clipping, neutral greys) before the next. Use when asked to fix, correct, enhance, edit, brighten, darken, warm up, cool down or colour-correct a photo, remove a colour cast, recover shadows or highlights, add contrast or punch, straighten a horizon or crop to a ratio, or when set_adjustments, add_adjustment_layer, get_histogram or measure_region are available. Load with pixerate-image-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-image-editor
+---
+
+# Correcting a photo
+
+A correction is a sequence where each step changes what the next one sees, so the order
+matters: frame, then light, then colour, then local, then style. The base controls
+(`set_adjustments`) edit the Background's develop filter; adjustment layers stack above it and
+can be masked, faded and blended later. Judge with numbers as well as eyes: `measure_region`
+measures any rectangle of the composited image without a render (mean colour, cast, percentiles,
+clipping), and `get_histogram` summarises the last `render_preview`.
+
+This skill is the method. `pixerate-image-editor` has the full tool reference and control ids.
+
+## Goal and quality bar
+
+- Nothing important clips: under about 0.5 % of pixels at pure black or white per channel on a
+  normal photo (`clipping` in `measure_region` or `get_histogram`), unless a light source or a
+  specular highlight is meant to.
+- Things that should be neutral are: a white wall, a grey card or clouds within about ±4 levels
+  of cast (`cast.redBlue`, `cast.greenMagenta`).
+- The tones span the range the scene has: shadows near but above 0, highlights near but below
+  255 (`stats.luminance.p1` / `p99`), midtones where the subject reads well.
+- Every correction is still adjustable: base sliders for global light and white balance, layers
+  for the rest, named by intent. Nothing is merged or flattened unless asked.
+
+## Inputs to confirm
+
+- **The intent:** a faithful correction (the default) or a look (warm, moody, high contrast).
+- **A neutral reference** if there is one: a grey card, white paper, a wall the user knows is
+  white. Ask when the scene has none and the "right" colour is a matter of taste.
+- **Output ratio** if the user mentions a destination (Instagram 4:5, a print size, 16:9).
+
+## Working method
+
+1. **Read.** `get_image_info` (size, crop, rotation), `get_adjustments` (what is already set),
+   `list_layers`, then `measure_region` with no rectangle (the whole frame) and on the subject.
+   **Check:** you know where the image clips, its overall cast and where the subject is.
+2. **Straighten and crop first**, so every later judgement is on the final frame. Level a
+   horizon or vertical with `set_rotation` (small angles, -3..3), then `set_crop` inside the
+   transparent corners at the asked ratio; keep the subject's space to look or move into.
+   **Check:** `get_image_info` `crop` has the ratio you meant and contains the subject.
+3. **Exposure and white balance** with one `set_adjustments` call (`exposure`, `temperature`,
+   `tint`, with a `label`). Set white balance from the neutral reference: `measure_region` on
+   it, move `temperature` against `cast.redBlue` and `tint` against `cast.greenMagenta`, measure
+   again. For a precise fix, a `levels` layer with per-channel `inWhite` scales each channel so
+   the reference comes out grey (scale each channel to the same level).
+   **Check:** the reference's `cast` is within ±4; the frame does not clip.
+4. **Black and white points, then contrast.** A `levels` layer with `master.inBlack` /
+   `master.inWhite` just inside where the data starts (`p1` / `p99`), never past it. Then a
+   gentle S-curve `curves` layer (quarter-tones moved 10..25 levels, endpoints fixed). To lift
+   dark areas without touching bright ones, raise `master.gamma` (1.2..1.8) instead of exposure.
+   **Check:** `clipping` stays under 0.5 % per channel; shadows and highlights still have detail.
+5. **Colour.** `vibrance` before `saturation` (it spares skin and colours already strong),
+   `hueSaturation` per range for one colour, `colorBalance` for a cast left in the shadows or
+   highlights. Small moves: real corrections are ±10..30.
+   **Check:** neutrals still neutral; skin has red above green above blue and no orange or magenta.
+6. **Local fixes** through masks: a sky darkened, a face lifted. Select (see
+   `pixerate-image-selection-masking`), then `add_adjustment_layer` while the selection is
+   active, or `apply_selection_as_mask` with a `kind`.
+   **Check:** `measure_region` inside and just outside the mask: the change stops where it should.
+7. **Look last**, if asked: `photoFilter`, `blackWhite`, a split tone with `colorBalance`, at
+   reduced `opacity`. Correct before you stylise.
+8. **Verify the whole.** `measure_region` on the frame and the reference again; `render_preview`
+   and `get_histogram` where a canvas is available to look as well as measure. `undo_image` any
+   step that made it worse, and report the settings you used.
+
+## Decision table
+
+| Problem | Fix |
+| --- | --- |
+| Whole image too dark or bright, nothing clipping | `exposure` (base), ±10..30 |
+| Dark shadows, bright sky or window | `levels` `master.gamma` 1.2..1.8, or a curves lift in the lower quarter; never exposure, which clips the sky |
+| Bright areas blown, shadows fine | Lower the top of a curve, or `levels` `master.outWhite` a little; clipped detail cannot come back |
+| Flat, grey, low contrast | `levels` points at `p1` / `p99`, then a gentle S-curve |
+| Colour cast, with a neutral reference | Per-channel `levels` `inWhite` (precise), or `temperature` / `tint` (quick) |
+| Colour cast, no reference | `temperature` / `tint` until whites and clouds look clean; ask whether warmth is wanted |
+| Cast only in the shadows or highlights | `colorBalance` shadows or highlights |
+| Dull colour | `vibrance` +10..25; `saturation` only for non-portrait scenes |
+| One colour wrong (green grass too yellow, sky too cyan) | `hueSaturation` on that range |
+| Contrast change shifts colours | Put the curves or levels layer in `luminosity` blend (`set_layer_properties`) |
+| Tilted horizon | `set_rotation`, then `set_crop` inside the corners |
+
+## Recipes
+
+**Neutral from a grey card.** `measure_region` on the card gives mean levels per channel (from
+`stats`). Pick the target (the green level, or the mean), and set each channel's `inWhite` to
+`255 × channel / target` in one `add_adjustment_layer` `levels` call (`params: { red: { inWhite },
+green: { inWhite }, blue: { inWhite } }`). Measure the card again, and the whole frame for clipping.
+
+**Lift shadows, keep the sky.** `add_adjustment_layer` `levels` with `params: { master: { gamma:
+1.6 } }`; measure the sky's `clipping` and the foreground's luminance mean; raise or lower gamma.
+For a lift limited to the foreground, add it while a selection of the foreground is active.
+
+**Crop to a ratio, as large as possible.** The largest crop with ratio `w:h` inside an image of
+`W × H` is `W` wide when `W / H` < `w / h`, else `H` tall; position it to keep the subject in
+frame and give it room on the side it faces.
+
+## Pitfalls
+
+- **Correcting in the wrong order.** Colour judged before exposure or white balance gets redone;
+  a crop after grading changes what the histogram meant.
+- **Exposure for shadows.** Raising exposure to open shadows clips the sky; use gamma or curves.
+- **Points past the data.** `inBlack` above `p1` or `inWhite` below `p99` crushes or blows
+  everything beyond; `clipping` shows it.
+- **Saturation on skin.** It turns skin orange fast; use vibrance, and measure a skin patch.
+- **Trusting the screen alone.** Measure neutrals and clipping; a preview at 512 px hides small
+  clipped areas.
+- **Stacking corrections in base sliders.** They cannot be masked or faded; use layers for
+  anything beyond global exposure and white balance.
+- **`get_histogram` before a render.** It reads the last `render_preview` and fails without one;
+  `measure_region` needs no render.
+
+## Tools used
+
+- `get_image_info`, `get_adjustments`, `list_controls`, `list_layers`: read the frame, settings, control ids and stack
+- `measure_region`: mean colour, cast, percentiles and clipping of any rectangle, without a render
+- `render_preview`, `get_histogram`, `capture_view`: look at the result and read its histogram
+- `set_rotation`, `set_crop`, `reset_crop`: straighten and frame
+- `set_adjustments`: exposure, white balance and other base controls, one undo step per call
+- `add_adjustment_layer`, `update_adjustment_layer`, `remove_adjustment_layer`: levels, curves, vibrance, hue and colour balance as layers
+- `set_layer_properties`: blend mode (luminosity), opacity and name of a correction layer
+- `apply_selection_as_mask`: a masked adjustment layer for a local fix
+- `undo_image`: take back a step

package/skills/pixerate-image-photo-correction/evals/crop-for-instagram.json

@@ -0,0 +1,19 @@
+{
+	"prompt": "Crop this photo to a 4:5 portrait for Instagram, as large as possible, keeping the whole person (the tall figure at x 50-70, y 15-70) in frame.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [110, 140, 90],
+		"shapes": [{ "shape": "rect", "x": 50, "y": 15, "width": 20, "height": 55, "color": [180, 120, 100] }]
+	},
+	"checks": [
+		{ "why": "a 4:5 portrait crop", "tool": "get_image_info", "expect": { "crop": { "$expr": "v && Math.abs(v.width / v.height - 0.8) <= 0.02" } } },
+		{ "why": "as large as the frame allows (full height)", "tool": "get_image_info", "expect": { "crop": { "height": { "$min": 78 } } } },
+		{ "why": "the whole person is inside", "tool": "get_image_info", "expect": { "crop": { "$expr": "v && v.x <= 50 && v.x + v.width >= 70 && v.y <= 15 && v.y + v.height >= 70" } } }
+	],
+	"solution": [
+		{ "tool": "get_image_info" },
+		{ "tool": "set_crop", "args": { "x": 28, "y": 0, "width": 64, "height": 80 } }
+	]
+}

package/skills/pixerate-image-photo-correction/evals/lift-shadows-keep-sky.json

@@ -0,0 +1,20 @@
+{
+	"prompt": "The foreground of this landscape is far too dark, but the sky is already bright. Brighten the foreground without blowing out the sky.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [40, 45, 40],
+		"shapes": [{ "shape": "rect", "x": 0, "y": 0, "width": 120, "height": 30, "color": [225, 232, 245] }]
+	},
+	"checks": [
+		{ "why": "the foreground is lifted into the midtones", "tool": "measure_region", "args": { "x": 0, "y": 40, "width": 120, "height": 40 }, "expect": { "stats": { "luminance": { "mean": { "$min": 70, "$max": 160 } } } } },
+		{ "why": "the sky keeps its detail: nothing clips to white", "tool": "measure_region", "args": { "x": 0, "y": 0, "width": 120, "height": 30 }, "expect": { "clipping": { "highlightsPercent": { "red": { "$max": 0.5 }, "green": { "$max": 0.5 }, "blue": { "$max": 0.5 } } } } },
+		{ "why": "the sky stays bright", "tool": "measure_region", "args": { "x": 0, "y": 0, "width": 120, "height": 30 }, "expect": { "stats": { "luminance": { "mean": { "$min": 200 } } } } }
+	],
+	"solution": [
+		{ "tool": "measure_region" },
+		{ "tool": "add_adjustment_layer", "args": { "kind": "levels", "name": "Lift shadows", "params": { "master": { "gamma": 1.8 } } } },
+		{ "tool": "measure_region", "args": { "x": 0, "y": 0, "width": 120, "height": 30 } }
+	]
+}

package/skills/pixerate-image-photo-correction/evals/neutralise-cast.json

@@ -0,0 +1,25 @@
+{
+	"prompt": "This photo has a cold blue cast. The grey card in the lower left (x 10-30, y 50-70) should be neutral grey. Fix the colour without clipping anything, and keep it adjustable.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 80,
+		"background": [50, 60, 85],
+		"shapes": [
+			{ "shape": "rect", "x": 0, "y": 0, "width": 120, "height": 20, "color": [120, 135, 170] },
+			{ "shape": "rect", "x": 10, "y": 50, "width": 20, "height": 20, "color": [70, 80, 105] }
+		]
+	},
+	"checks": [
+		{ "why": "the grey card is neutral (cast within ±4 levels)", "tool": "measure_region", "args": { "x": 12, "y": 52, "width": 16, "height": 16 }, "expect": { "cast": { "redBlue": { "$min": -4, "$max": 4 }, "greenMagenta": { "$min": -4, "$max": 4 } } } },
+		{ "why": "the card is a mid grey, not crushed or blown", "tool": "measure_region", "args": { "x": 12, "y": 52, "width": 16, "height": 16 }, "expect": { "stats": { "luminance": { "mean": { "$min": 90, "$max": 170 } } } } },
+		{ "why": "no channel clips anywhere", "tool": "measure_region", "expect": { "clipping": { "highlightsPercent": { "red": { "$max": 0.5 }, "green": { "$max": 0.5 }, "blue": { "$max": 0.5 } }, "shadowsPercent": { "red": { "$max": 0.5 }, "green": { "$max": 0.5 }, "blue": { "$max": 0.5 } } } } },
+		{ "why": "the correction is a layer, not baked into the photo", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "adjustment" } } } }
+	],
+	"solution": [
+		{ "tool": "measure_region", "args": { "x": 12, "y": 52, "width": 16, "height": 16 } },
+		{ "tool": "add_adjustment_layer", "args": { "kind": "levels", "name": "Neutralise cast", "params": { "red": { "inWhite": 140 }, "green": { "inWhite": 159 }, "blue": { "inWhite": 209 } } } },
+		{ "tool": "measure_region", "args": { "x": 12, "y": 52, "width": 16, "height": 16 } },
+		{ "tool": "measure_region" }
+	]
+}

package/skills/pixerate-image-portrait-retouch/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pixerate-image-portrait-retouch
+description: The portrait retouching workflow in the Pixerate image editor - removing blemishes, spots and stray hairs, healing larger flaws, evening skin while keeping its texture, dodging and burning, brightening eyes and teeth, and keeping the result natural and reversible on separate layers. Use when asked to retouch, clean up, airbrush or touch up a portrait, headshot or face, remove spots, pimples, acne, wrinkles, stray hairs or dust, smooth or even skin, brighten eyes or whiten teeth, or when spot_heal, heal_brush, clone_stamp, dodge or burn are available. Load with pixerate-image-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-image-editor
+---
+
+# Retouching a portrait
+
+Good retouching removes what is temporary (a spot, a stray hair, a shine) and keeps what makes
+the person look like themselves (moles they keep, freckles, pores, laughter lines). Work from
+the global to the small, on layers above the photo, so every step can be faded or taken back.
+The healing tools paint onto an empty layer when they sample `current-below`; tonal tools
+(dodge, burn, sponge, smudge) change the pixels they touch, so they work on a duplicate.
+
+This skill is the method. `pixerate-image-editor` has the tool reference, and its
+`references/retouching.md` the detail of each retouching tool.
+
+## Goal and quality bar
+
+- Temporary flaws are gone: a blemish area measures like the skin around it (`measure_region`
+  on a small box around it: luminance `p1` close to the surrounding skin).
+- Skin keeps its texture: no flat, plastic patches. Heal and clone copy real texture; blur only
+  locally and lightly.
+- Tone and colour are natural: skin has red above green above blue, eyes and teeth brightened
+  only a little (they stay off-white).
+- The photo layer is unchanged: retouching lives on named layers ("Retouch", "Dodge & burn",
+  "Eyes") the user can fade or switch off.
+
+## Inputs to confirm
+
+- **How much:** a light clean-up (temporary flaws only, the default), a polished commercial
+  retouch, or something specific.
+- **What to keep:** moles, freckles, scars and features that are part of the person stay unless
+  the user asks.
+- **Where:** the flaws to fix when the user has named them (positions or a description).
+
+## Working method
+
+1. **Global correction first.** Exposure and white balance as in `pixerate-image-photo-correction`,
+   so retouching is judged on the final tones.
+   **Check:** skin `measure_region` has a plausible colour (red > green > blue, no strong cast).
+2. **Find the flaws.** `capture_view` the face at 2-4× scale in parts; list spots, hairs and
+   flaws with positions. `measure_region` on a small box around a suspect spot compared with a
+   box of clean skin beside it tells a spot from a shadow.
+   **Check:** a list of flaws with coordinates and sizes.
+3. **Make a retouch layer.** `add_pixel_layer` named "Retouch" above the photo; all healing goes
+   on it with `sample: "current-below"`.
+   **Check:** `list_layers` shows it active above the photo.
+4. **Heal small to large.** `spot_heal` for spots (one dab, `brush.size` a little larger than the
+   spot, `hardness` 0.2-0.5); a short stroke of dabs along a stray hair. `heal_brush` from a clean
+   source of the same texture for larger flaws; `clone_stamp` near edges (lips, eyes, hairline)
+   where healing would pull colour across.
+   **Check:** `measure_region` around each flaw: its `p1` is near the clean skin's; `capture_view`
+   shows texture, not a smear.
+5. **Even tone (dodge and burn)**, only if asked for more than a clean-up. Duplicate the photo
+   (`duplicate_layer`) and `dodge` / `burn` at `exposure` 0.1-0.2, `range: "midtones"`, along
+   shadows under the eyes or uneven patches; or paint on a layer in `soft-light` blend.
+   **Check:** the area's luminance moved by a few levels, not tens.
+6. **Eyes and teeth.** Select them (`select_ellipse`, `select_polygon`), feather 1-2 px, and add a
+   `levels` or `curves` layer while the selection is active (`master.gamma` 1.2-1.6). For yellow
+   teeth, a `hueSaturation` layer lowering the yellows' saturation, masked the same way.
+   **Check:** `measure_region` inside rises; just outside (skin, lips) does not change.
+7. **Review the whole face** at normal scale (`render_preview` or `capture_view` at 1×). Lower a
+   layer's `opacity` where it went too far (`set_layer_properties`). Report what you removed.
+
+## Decision table
+
+| Flaw | Tool |
+| --- | --- |
+| Spot, pimple, dust (smaller than about 15 px) | `spot_heal`, `proximity-match` or `content-aware` |
+| Stray hair across skin | `spot_heal` along it, short strokes; `clone_stamp` where it crosses an edge |
+| Larger blemish, scar the user wants gone | `heal_brush` from clean skin of the same texture and light |
+| Flaw next to an edge (lip line, eyelid, hairline) | `clone_stamp`, with a source along the same edge |
+| Shine on forehead or nose | `heal_brush` at reduced brush opacity from matte skin nearby |
+| Dark circles, uneven patches | `dodge` (midtones, exposure 0.1-0.2) on a duplicate, or a masked curves layer |
+| Dull eyes | Masked `levels` gamma 1.2-1.6; `sharpen_stroke` lightly on the iris |
+| Yellow teeth | Masked `hueSaturation` (yellows, saturation -20..-40), then a little brightness |
+| Redness | Masked `hueSaturation` (reds, saturation down a little) |
+
+## Recipes
+
+**Clean-up pass.** `add_pixel_layer` "Retouch" → one `spot_heal` per spot (`points: [{x, y}]`,
+`sample: "current-below"`, `brush: { size, hardness: 0.3 }`) → `measure_region` around each.
+
+**Stray hair.** `spot_heal` with `points` every 8-10 px along the hair and a brush 1.5-2× its
+width; check the whole length with one `measure_region` box over it.
+
+**Brighter eyes.** `select_ellipse` each eye (`mode: "add"` for the second) → `modify_selection`
+`feather` 1 → `add_adjustment_layer` `levels` with `params: { master: { gamma: 1.4 } }` →
+`measure_region` on an eye and on the skin beside it.
+
+## Pitfalls
+
+- **Healing on the photo layer.** Mistakes become permanent; heal onto an empty layer with
+  `current-below`.
+- **An empty layer with `sample: "current"`** has nothing to copy, so the stroke does nothing.
+- **Over-smoothing.** Blurring skin removes pores and looks fake; heal flaws instead.
+- **Big brushes.** A heal brush much larger than the flaw pulls in colour from around it; keep it
+  just over the flaw.
+- **Healing across an edge** smears lips or lashes into skin; clone along edges instead.
+- **Removing features.** Moles, freckles and scars are part of a face; ask before removing them.
+- **Bright white eyes and teeth** look unnatural; small gamma moves, and measure.
+
+## Tools used
+
+- `list_layers`, `capture_view`, `render_preview`, `measure_region`: find flaws, check each fix, review
+- `add_pixel_layer`, `duplicate_layer`, `set_layer_properties`: retouch and dodge-and-burn layers; fade them
+- `spot_heal`, `heal_brush`, `clone_stamp`, `set_clone_source`: remove spots, hairs and flaws
+- `dodge`, `burn`, `sponge`: even tone and colour on a duplicate
+- `sharpen_stroke`, `blur_stroke`: crisp eyes, soften a harsh edge, locally
+- `select_ellipse`, `select_polygon`, `modify_selection`: select eyes and teeth
+- `add_adjustment_layer`: masked brightening or colour change of eyes and teeth
+- `undo_image`: take back a step

package/skills/pixerate-image-portrait-retouch/evals/brighten-eyes.json

@@ -0,0 +1,25 @@
+{
+	"prompt": "Brighten the eyes a little (the two dark ovals at x 35-45 and x 55-65, y 15-21) without changing the skin.",
+	"fixture": {
+		"editor": "image",
+		"width": 100,
+		"height": 60,
+		"background": [200, 160, 140],
+		"shapes": [
+			{ "shape": "ellipse", "x": 35, "y": 15, "width": 10, "height": 6, "color": [70, 55, 50] },
+			{ "shape": "ellipse", "x": 55, "y": 15, "width": 10, "height": 6, "color": [70, 55, 50] }
+		]
+	},
+	"checks": [
+		{ "why": "the eyes are brighter", "tool": "measure_region", "args": { "x": 38, "y": 17, "width": 4, "height": 2 }, "expect": { "stats": { "luminance": { "mean": { "$min": 75, "$max": 140 } } } } },
+		{ "why": "the other eye too", "tool": "measure_region", "args": { "x": 58, "y": 17, "width": 4, "height": 2 }, "expect": { "stats": { "luminance": { "mean": { "$min": 75, "$max": 140 } } } } },
+		{ "why": "the skin is unchanged", "tool": "measure_region", "args": { "x": 10, "y": 35, "width": 80, "height": 20 }, "expect": { "meanColor": "#c8a08c" } },
+		{ "why": "it is an adjustable, masked layer", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "adjustment", "mask": { "kind": "raster" } } } } }
+	],
+	"solution": [
+		{ "tool": "select_ellipse", "args": { "x": 35, "y": 15, "width": 10, "height": 6 } },
+		{ "tool": "select_ellipse", "args": { "x": 55, "y": 15, "width": 10, "height": 6, "mode": "add" } },
+		{ "tool": "modify_selection", "args": { "op": "feather", "radius": 1 } },
+		{ "tool": "add_adjustment_layer", "args": { "kind": "levels", "name": "Eyes", "params": { "master": { "gamma": 1.6 } } } }
+	]
+}

package/skills/pixerate-image-portrait-retouch/evals/remove-blemishes.json

@@ -0,0 +1,23 @@
+{
+	"prompt": "Remove the two dark blemishes on this skin (around x 30, y 30 and x 70, y 22). Don't change the original photo layer.",
+	"fixture": {
+		"editor": "image",
+		"width": 100,
+		"height": 60,
+		"background": [200, 160, 140],
+		"shapes": [
+			{ "shape": "rect", "x": 29, "y": 29, "width": 3, "height": 3, "color": [120, 80, 70] },
+			{ "shape": "rect", "x": 69, "y": 21, "width": 3, "height": 3, "color": [120, 80, 70] }
+		]
+	},
+	"checks": [
+		{ "why": "the first blemish is gone", "tool": "measure_region", "args": { "x": 26, "y": 26, "width": 9, "height": 9 }, "expect": { "stats": { "luminance": { "p1": { "$min": 155 } } } } },
+		{ "why": "the second blemish is gone", "tool": "measure_region", "args": { "x": 66, "y": 18, "width": 9, "height": 9 }, "expect": { "stats": { "luminance": { "p1": { "$min": 155 } } } } },
+		{ "why": "the retouching is on its own layer above the photo", "tool": "list_layers", "expect": { "layers": { "$length": { "$min": 2 }, "$some": { "id": "background", "mask": null } } } }
+	],
+	"solution": [
+		{ "tool": "add_pixel_layer", "args": { "name": "Retouch" } },
+		{ "tool": "spot_heal", "args": { "points": [{ "x": 30, "y": 30 }], "sample": "current-below", "brush": { "size": 10, "hardness": 0.3 } } },
+		{ "tool": "spot_heal", "args": { "points": [{ "x": 70, "y": 22 }], "sample": "current-below", "brush": { "size": 10, "hardness": 0.3 } } }
+	]
+}

package/skills/pixerate-image-portrait-retouch/evals/remove-stray-hair.json

@@ -0,0 +1,18 @@
+{
+	"prompt": "There's a stray dark hair across the cheek (a thin line at y 45, from x 20 to 60). Remove it without touching the original layer.",
+	"fixture": {
+		"editor": "image",
+		"width": 100,
+		"height": 60,
+		"background": [200, 160, 140],
+		"shapes": [{ "shape": "rect", "x": 20, "y": 45, "width": 41, "height": 1, "color": [90, 70, 60] }]
+	},
+	"checks": [
+		{ "why": "the hair is gone along its whole length", "tool": "measure_region", "args": { "x": 18, "y": 43, "width": 45, "height": 5 }, "expect": { "stats": { "luminance": { "p1": { "$min": 155 } } } } },
+		{ "why": "on its own layer", "tool": "list_layers", "expect": { "layers": { "$length": { "$min": 2 } } } }
+	],
+	"solution": [
+		{ "tool": "add_pixel_layer", "args": { "name": "Retouch" } },
+		{ "tool": "spot_heal", "args": { "points": [{ "x": 20, "y": 45.5 }, { "x": 30, "y": 45.5 }, { "x": 40, "y": 45.5 }, { "x": 50, "y": 45.5 }, { "x": 60, "y": 45.5 }], "sample": "current-below", "brush": { "size": 8, "hardness": 0.3 } } }
+	]
+}

package/skills/pixerate-image-product-photo/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: pixerate-image-product-photo
+description: The product photo workflow in the Pixerate image editor - cutting a product out of its backdrop, putting it on pure white or a brand colour, grounding it with a soft shadow, keeping its colours accurate, cropping and centring it to marketplace ratios with consistent margins, and checking the result before export. Use when asked to prepare product shots, packshots or e-commerce, marketplace, Amazon, Etsy or catalogue images, put a product on white, remove or replace a product background, add a product shadow, or crop and centre products consistently, or when select_subject, add_layer_mask, add_layer_effect or set_crop are available. Load with pixerate-image-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-image-editor
+---
+
+# Preparing a product photo
+
+A product shot is a cutout on a controlled background: the product's edge and colour must be
+exact, the background uniform, and every image in a set framed the same way. Build it as layers
+so each part stays adjustable: the photo with a mask hiding its backdrop, a background fill
+layer below it, a shadow (an effect, or its own layer) between, and the crop on top.
+
+This skill is the method. `pixerate-image-editor` has the full tool reference, and
+`pixerate-image-selection-masking` the detail of selecting and refining the edge.
+
+## Goal and quality bar
+
+- The background is uniform: pure white is 255 in every channel (`measure_region` `stats`
+  luminance `p1` ≥ 250 and a cast within ±2), or exactly the brand colour asked for.
+- The product's colour is unchanged by the cutout (measure it before and after) and its edge
+  has no halo of the old backdrop (`inspect_mask_edge` `haloScore` under 0.35).
+- The product sits on something: a soft shadow below it, unless the user wants it floating.
+- The frame matches the destination: ratio, product centred (or as the set requires), and the
+  product filling a consistent share of the frame (about 75-85 % of the longer side for most
+  marketplaces).
+- Everything stays editable: masked, not erased; the shadow an effect or a layer.
+
+## Inputs to confirm
+
+- **Background:** pure white (the default for marketplaces), a colour (hex), or transparent.
+- **Destination ratio and margin:** 1:1 (most marketplaces), 4:5, 3:2, or a size in pixels; how
+  much of the frame the product should fill. For a set, the same for every image.
+- **Shadow:** a soft contact or drop shadow (the default), a reflection, or none.
+- **Colour reference:** a swatch or hex the product must match, when colour accuracy matters.
+
+## Working method
+
+1. **Read and measure the product.** `list_layers`, `get_image_info`, then `measure_region` on a
+   flat part of the product: its mean colour is the reference you will protect.
+   **Check:** you have the product's bounds and colour.
+2. **Correct the photo first** if it needs it (white balance from the backdrop, exposure): the
+   cutout and the measure should be on corrected colours (`pixerate-image-photo-correction`).
+   **Check:** the backdrop is neutral before you remove it.
+3. **Select the product.** On a plain backdrop, `magic_wand` on the product (`contiguous: true`)
+   or on the backdrop and `invert_selection`; on a busy one, `select_subject` or `select_object`
+   with a box, then `refine_selection`. Hard-edged products want a crisp edge (refine radius
+   1-3, no feather).
+   **Check:** `get_selection` bounds hug the product; `inspect_mask_edge` `issues` is empty.
+4. **Hide the backdrop, do not delete it.** `add_layer_mask` `from: "selection"` on the photo
+   layer (or `add_vector_mask` for a geometric product that must stay razor sharp). Then
+   `add_pixel_layer` with the background `color` placed `belowId` the photo layer.
+   **Check:** `measure_region` on a corner: `p1` ≥ 250 (white) or the brand colour; on the
+   product: the colour from step 1.
+5. **Fix the edge colour** if the old backdrop tints it: `set_edge_decontamination`, or
+   `modify_selection` `contract` 1 px before masking.
+   **Check:** `inspect_mask_edge` with `target: "layer-mask"` shows no halo.
+6. **Ground it.** With the product on its own layer (`layer_via_copy`, or the masked photo),
+   `add_layer_effect` `drop-shadow` with `angle` 90 (light from above), a small `distance`
+   (3-10 px at web sizes), a `size` larger than the distance and `opacity` 0.25-0.45.
+   **Check:** `list_layers` shows the effect; the shadow reads as contact, not as a cutout.
+7. **Frame it.** `set_crop` at the ratio, centred on the product's bounds, with the margin asked.
+   **Check:** `get_image_info` `crop`: ratio right, centre within a pixel or two of the
+   product's centre, product share of the side as intended.
+8. **Final check.** `measure_region` on the background corners and the product; `render_preview`
+   where available. Report the crop, the background colour and the shadow settings so the rest
+   of the set can match.
+
+## Decision table
+
+| Backdrop | Selection |
+| --- | --- |
+| Plain, contrasting | `magic_wand` on the product or backdrop (tolerance 10-30) |
+| Plain but close to the product colour | `select_color_range` on the backdrop with low fuzziness, then refine |
+| Busy or textured | `select_subject`, or `select_object` with the product's box |
+| Glass, transparent or reflective product | Select the outline, then lower the mask's `density` where it should show through; ask how it should look |
+| Product with straight edges (a box, a screen) | `add_vector_mask` from the selection, or a path |
+
+| Destination | Frame |
+| --- | --- |
+| Marketplace main image | 1:1, white, product about 85 % of the frame |
+| Catalogue or site grid | The grid's ratio, the same margin on every image |
+| Social post | 4:5 or 1:1, room for text if the user asks |
+
+## Recipes
+
+**On white.** `magic_wand` on the product → `inspect_mask_edge` → `add_layer_mask` (`layerId`
+of the photo, `from: "selection"`) → `add_pixel_layer` (`color: "#ffffff"`, `belowId` the photo)
+→ `measure_region` on a corner and on the product.
+
+**Centred square crop.** Product bounds `x, y, w, h`; side `S = max(w, h) / share` (share 0.7-0.85,
+no larger than the image allows); `set_crop` with `x + w/2 - S/2`, `y + h/2 - S/2`, `S`, `S`.
+
+**Contact shadow.** `layer_via_copy` the selected product (or use the masked layer), then
+`add_layer_effect` `kind: "drop-shadow"` with `settings: { angle: 90, distance: 6, size: 10,
+opacity: 0.4 }`; adjust with `update_layer_effect`.
+
+## Pitfalls
+
+- **Off-white that looks white.** 245 grey reads as white on screen and fails a marketplace
+  check; measure `p1`, not the mean.
+- **Erasing the backdrop.** Deleted pixels cannot be fixed later; mask instead.
+- **Colour shift from the cutout.** A decontamination or a colour adjustment above the product
+  changes it; measure the product before and after, and keep corrections below the product.
+- **A halo of the old backdrop** shows on white more than anywhere; inspect the edge and
+  decontaminate or contract by a pixel.
+- **A shadow that floats.** A large distance or a sideways angle looks pasted on; keep it short
+  and below.
+- **Inconsistent sets.** Each image cropped by eye drifts; compute the crop from the product's
+  bounds with the same share for every image.
+
+## Tools used
+
+- `list_layers`, `get_image_info`, `measure_region`: read the stack, the frame and the colours
+- `magic_wand`, `select_color_range`, `select_subject`, `select_object`, `invert_selection`: select the product
+- `refine_selection`, `modify_selection`, `get_selection`, `inspect_mask_edge`: refine and check the edge
+- `add_layer_mask`, `add_vector_mask`, `set_layer_mask_properties`: hide the backdrop, editably
+- `set_edge_decontamination`: remove the backdrop's colour from the edge
+- `add_pixel_layer`: the background fill below the product
+- `layer_via_copy`: the product on its own layer
+- `add_layer_effect`, `update_layer_effect`: the shadow
+- `set_crop`, `reset_crop`: the frame
+- `render_preview`: look at the result
+- `undo_image`: take back a step

package/skills/pixerate-image-product-photo/evals/grounding-shadow.json

@@ -0,0 +1,19 @@
+{
+	"prompt": "The product looks like it's floating. Put it on its own layer and add a soft shadow under it that I can still adjust.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 90,
+		"background": [200, 198, 195],
+		"shapes": [{ "shape": "rect", "x": 40, "y": 25, "width": 40, "height": 40, "color": [30, 90, 160] }]
+	},
+	"checks": [
+		{ "why": "the product is on its own layer, cut to its shape", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "pixel", "bounds": { "x": { "$min": 39, "$max": 41 }, "y": { "$min": 24, "$max": 26 }, "width": { "$min": 39, "$max": 42 }, "height": { "$min": 39, "$max": 42 } } } } } },
+		{ "why": "a live drop shadow on that layer", "tool": "list_layers", "expect": { "layers": { "$some": { "effects": { "$expr": "v && JSON.stringify(v).includes('drop-shadow')" } } } } }
+	],
+	"solution": [
+		{ "tool": "magic_wand", "args": { "x": 60, "y": 45, "tolerance": 20, "contiguous": true } },
+		{ "tool": "layer_via_copy", "args": {} },
+		{ "tool": "add_layer_effect", "args": { "layerId": { "$read": "list_layers", "path": "activeLayerId" }, "kind": "drop-shadow", "settings": { "distance": 6, "size": 10, "opacity": 0.4, "angle": 90 } } }
+	]
+}

package/skills/pixerate-image-product-photo/evals/square-crop.json

@@ -0,0 +1,19 @@
+{
+	"prompt": "Crop to a square for the marketplace listing with the product centred, leaving some breathing room around it (the product should fill roughly two thirds of the frame).",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 90,
+		"background": [200, 198, 195],
+		"shapes": [{ "shape": "rect", "x": 40, "y": 25, "width": 40, "height": 40, "color": [30, 90, 160] }]
+	},
+	"checks": [
+		{ "why": "a square crop", "tool": "get_image_info", "expect": { "crop": { "$expr": "v && Math.abs(v.width - v.height) <= 1" } } },
+		{ "why": "the product is centred (within 2 px)", "tool": "get_image_info", "expect": { "crop": { "$expr": "v && Math.abs(v.x + v.width / 2 - 60) <= 2 && Math.abs(v.y + v.height / 2 - 45) <= 2" } } },
+		{ "why": "the product fills 60-85 % of the side", "tool": "get_image_info", "expect": { "crop": { "$expr": "v && 40 / v.width >= 0.6 && 40 / v.width <= 0.85" } } }
+	],
+	"solution": [
+		{ "tool": "get_image_info" },
+		{ "tool": "set_crop", "args": { "x": 32, "y": 17, "width": 56, "height": 56 } }
+	]
+}

package/skills/pixerate-image-product-photo/evals/white-background.json

@@ -0,0 +1,23 @@
+{
+	"prompt": "Put this product on a pure white background for the shop, without changing the product's colour. Keep it editable.",
+	"fixture": {
+		"editor": "image",
+		"width": 120,
+		"height": 90,
+		"background": [200, 198, 195],
+		"shapes": [{ "shape": "rect", "x": 40, "y": 25, "width": 40, "height": 40, "color": [30, 90, 160] }]
+	},
+	"checks": [
+		{ "why": "the background is pure, neutral white", "tool": "measure_region", "args": { "x": 0, "y": 0, "width": 30, "height": 20 }, "expect": { "stats": { "luminance": { "p1": { "$min": 250 } } }, "cast": { "redBlue": { "$min": -2, "$max": 2 } } } },
+		{ "why": "the area under the product is white too", "tool": "measure_region", "args": { "x": 0, "y": 72, "width": 120, "height": 18 }, "expect": { "stats": { "luminance": { "p1": { "$min": 250 } } } } },
+		{ "why": "the product keeps its colour", "tool": "measure_region", "args": { "x": 45, "y": 30, "width": 30, "height": 30 }, "expect": { "stats": { "red": { "mean": { "$min": 26, "$max": 34 } }, "green": { "mean": { "$min": 86, "$max": 94 } }, "blue": { "mean": { "$min": 156, "$max": 164 } } } } },
+		{ "why": "the backdrop is hidden by a mask, not deleted", "tool": "list_layers", "expect": { "layers": { "$some": { "type": "pixel", "mask": { "kind": "raster" } } } } }
+	],
+	"solution": [
+		{ "tool": "magic_wand", "args": { "x": 60, "y": 45, "tolerance": 20, "contiguous": true } },
+		{ "tool": "inspect_mask_edge" },
+		{ "tool": "add_layer_mask", "args": { "layerId": "background", "from": "selection" } },
+		{ "tool": "add_pixel_layer", "args": { "name": "White", "color": "#ffffff", "belowId": "background" } },
+		{ "tool": "measure_region", "args": { "x": 0, "y": 0, "width": 30, "height": 20 } }
+	]
+}