@pixerate/editor 0.221.0 → 0.222.0

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 } }
+	]
+}

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" } }
+	]
+}