@pixerate/editor 0.221.1 → 0.222.1

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-vector/SKILL.md

@@ -54,6 +54,15 @@ carry a live effect stack. Every command is a `vector.*` command run with `run_c
 Parameter details (gradient fields, effect parameters, width profiles, envelopes) are in
 [references/commands.md](references/commands.md).
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the commands below.
+
+- `pixerate-vector-icon-set`: icons on one grid, one stroke and style, crisp, as symbols and SVG.
+- `pixerate-vector-logo`: marks from booleans, a lockup, colour variants, outlined delivery files.
+- `pixerate-vector-illustration`: block in, gradients and stacked fills, masks, blends, shadows.
+
 ## Working method
 
 1. **Read.** `vector.list` gives the artboard size, every node depth first (id, type, name,
@@ -74,30 +83,16 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
 
 ## Best practices
 
-- **Diagrams with connectors.** Lay the boxes out first, then `vector.connect` them (in one
-  `run_commands` batch) rather than drawing lines: connectors stay attached when boxes move, and
-  `route: "elbow"` with a small `radius` reads well in flowcharts. Leave sides `auto` unless a
-  connector must leave a particular side.
-
 - **Frames for anything that resizes.** Build screens, cards, buttons and banners inside a frame
   (`vector.addFrame` or `vector.frameSelection`), set each child's constraints with
   `vector.setResizing` (backgrounds and dividers `leftRight`, icons pinned to their corner, titles
   `center`), then resize with `vector.setFrame` to produce other sizes from one design. Export each
   artboard with `vector.exportFrameSvg`.
-
-- **Constraints for precise, editable geometry.** For technical drawings, diagrams, floor plans or
-  any shape that must keep exact relations, draw it roughly, run `vector.autoConstrain`, then add
-  the dimensions that matter (`vector.addConstraint` distance / angle / radius) and name them so
-  related sizes follow one another (`vector.setConstraintValue` with expressions like `w / 2`).
-  Check `vector.listConstraints` `dof`: aim for `fully` on parts that must not drift; `over`
-  means some constraints repeat others. Prefer few, meaningful constraints over many.
-
 - **Symbols for repeats.** When the same art appears several times (icons in a set, trees in a
   scene, bullets, a logo mark), make it once and place instances (`vector.makeSymbol`, then
   `vector.placeSymbol` with `x` / `y` or a `transform`), so one edit in isolation changes them all.
   Give each a clear name. Use `vector.setInstanceOptions` `fill` / `stroke` for colour variants and
   `hidden` to drop a part, rather than detaching; detach only when one copy must diverge for good.
-
 - **Text.** Use point text for labels and headlines, area text (`width`, `height`) for anything
   that should wrap, text on a path for badges and seals. Check `overflow` in the summary every
   text write returns: hidden lines or characters mean the box or path is too small. Keep one or
@@ -106,56 +101,11 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
   than splitting text into separate nodes, so it still edits as one paragraph. Create Outlines
   only for final artwork or logos that must not depend on fonts; keep a copy as text if it may
   change.
-  For Japanese, Chinese or Korean set in columns (signage, book spines, posters), use vertical
-  text (`textOrientation: "vertical"` or `vector.setTextOrientation`): CJK stands upright, Latin
-  turns sideways; set a short Latin range `upright: true` to stack it letter by letter. In an
-  area, columns that do not fit past the left edge are `overflow`. Vertical text cannot follow a
-  path.
-
-- **Clean paths.** Use the fewest anchors that describe the shape: anchors at extrema (top,
-  bottom, left, right of a curve) and at true corners, handles horizontal or vertical at extrema,
-  each handle about a third of its segment. Run `vector.removeRedundantPoints` after
-  booleans, knife and pencil work; `vector.smooth` for lumpy curves; `vector.deleteAnchors`
-  keeps the outline by refitting neighbours.
-- **Live corners over drawn arcs.** Give rectangles, polygons and stars a `cornerRadius`
-  (`vector.addShape`) or set it with `vector.setCorners`; the anchors stay sharp and editable and
-  radii shrink to fit short sides. Keep one radius scale across a design. For app icons and UI
-  cards use `smoothing` (about 0.6) on `vector.setCorners` for continuous, squircle corners.
+- **Paths, strokes, booleans, gradients, stacks, masks, shadows, connectors, constraints and
+  vertical text:** read [references/best-practices.md](references/best-practices.md) first.
 - **Non-destructive first.** Live booleans (`vector.boolean` with `live: true`), path effects
   and envelopes keep the operands editable. A destructive boolean or Pathfinder replaces its
   inputs; do that last, and only when asked for flat output.
-- **Boolean vs Pathfinder vs Shape Builder.** `vector.boolean` for a single result shape (union
-  for silhouettes, subtract for cut-outs, intersect, exclude). `vector.pathfinder` when you need
-  every region separately (divide), hidden parts removed (trim, merge) or a crop. Shape Builder
-  when you want to merge or delete particular regions picked by point.
-- **Strokes.** Use `strokeAlign: "inside"` for icons and UI shapes so the outer size stays exact,
-  `outside` for outlines around artwork; open paths always stroke centred. Use round caps and
-  joins for friendly line icons, miter for geometric ones. Keep one stroke width across an icon
-  set (for example 1.5 or 2 units on a 24-unit grid).
-- **Icon grid.** Use a square artboard (24, 32 or 48 units), keep a padding margin, place
-  coordinates on whole or half units so strokes render crisp, and align optical centres.
-- **Gradients.** Two to four stops are usually enough. Use `interpolation: "oklab"` for
-  perceptually even blends without the grey or muddy midpoint sRGB gives between saturated hues;
-  `midpoint` to shift the half-way point instead of adding stops. Prefer linear or radial for
-  portability; conic and diamond export as SVG patterns.
-- **Appearance stacks over duplicate shapes.** For a gradient over a texture, a tinted overlay,
-  an outline around an outline or a stroke inside and another outside, stack layers on one path
-  (`vector.addFill`, `vector.addStroke`) instead of copying the shape: the copies would drift
-  apart when edited. Give each stroke its own `strokeAlign` (outside under, inside or center on
-  top) and widths that step down towards the top. Use per-layer `opacity` and `blendMode`
-  (multiply to darken, screen to lighten, overlay for texture) rather than node opacity when only
-  one paint should fade.
-- **Masks over cut-outs.** To show artwork inside a shape (a photo-like fill in a circle, a
-  pattern inside text-like outlines, a scene seen through a window), use
-  `vector.makeClippingMask` rather than a destructive intersect: the contents stay editable and
-  movable inside the frame. Draw the mask last (on top) and make the mask from it; edit the mask
-  later by its `maskId`. Use `vector.makeOpacityMask` with a white-to-black gradient for fades
-  and reflections (luminance: white shows). A clip's own paint is never drawn, so its fill
-  colour does not matter. Effects and shadows on the mask group follow the masked silhouette.
-- **Shadows and glows.** Keep drop shadows subtle: black at 0.15 to 0.3 opacity, `offsetY` 2 to 8,
-  `blur` about twice the offset. Use one light direction for every shadow in a design. Filters
-  export as SVG filters, which some tools (and older renderers) draw slightly differently or not
-  at all; a design that must look identical everywhere should avoid them or rasterize.
 - **Grouping and naming.** Group the parts of one object (`vector.group` with a `name`), name
   paths that matter (`name` on add), and keep the tree shallow.
 - **SVG hygiene.** Export with `precision` 2 or 3 (default 3); higher only for tiny artboards.

package/skills/pixerate-vector/references/best-practices.md

@@ -0,0 +1,62 @@
+# Drawing best practices
+
+Detail for `SKILL.md`'s best practices, by topic.
+
+- **Clean paths.** Use the fewest anchors that describe the shape: anchors at extrema (top,
+  bottom, left, right of a curve) and at true corners, handles horizontal or vertical at extrema,
+  each handle about a third of its segment. Run `vector.removeRedundantPoints` after
+  booleans, knife and pencil work; `vector.smooth` for lumpy curves; `vector.deleteAnchors`
+  keeps the outline by refitting neighbours.
+- **Live corners over drawn arcs.** Give rectangles, polygons and stars a `cornerRadius`
+  (`vector.addShape`) or set it with `vector.setCorners`; the anchors stay sharp and editable and
+  radii shrink to fit short sides. Keep one radius scale across a design. For app icons and UI
+  cards use `smoothing` (about 0.6) on `vector.setCorners` for continuous, squircle corners.
+- **Boolean vs Pathfinder vs Shape Builder.** `vector.boolean` for a single result shape (union
+  for silhouettes, subtract for cut-outs, intersect, exclude). `vector.pathfinder` when you need
+  every region separately (divide), hidden parts removed (trim, merge) or a crop. Shape Builder
+  when you want to merge or delete particular regions picked by point.
+- **Strokes.** Use `strokeAlign: "inside"` for icons and UI shapes so the outer size stays exact,
+  `outside` for outlines around artwork; open paths always stroke centred. Use round caps and
+  joins for friendly line icons, miter for geometric ones. Keep one stroke width across an icon
+  set (for example 1.5 or 2 units on a 24-unit grid).
+- **Icon grid.** Use a square artboard (24, 32 or 48 units), keep a padding margin, place
+  coordinates on whole or half units so strokes render crisp, and align optical centres.
+- **Gradients.** Two to four stops are usually enough. Use `interpolation: "oklab"` for
+  perceptually even blends without the grey or muddy midpoint sRGB gives between saturated hues;
+  `midpoint` to shift the half-way point instead of adding stops. Prefer linear or radial for
+  portability; conic and diamond export as SVG patterns.
+- **Appearance stacks over duplicate shapes.** For a gradient over a texture, a tinted overlay,
+  an outline around an outline or a stroke inside and another outside, stack layers on one path
+  (`vector.addFill`, `vector.addStroke`) instead of copying the shape: the copies would drift
+  apart when edited. Give each stroke its own `strokeAlign` (outside under, inside or center on
+  top) and widths that step down towards the top. Use per-layer `opacity` and `blendMode`
+  (multiply to darken, screen to lighten, overlay for texture) rather than node opacity when only
+  one paint should fade.
+- **Masks over cut-outs.** To show artwork inside a shape (a photo-like fill in a circle, a
+  pattern inside text-like outlines, a scene seen through a window), use
+  `vector.makeClippingMask` rather than a destructive intersect: the contents stay editable and
+  movable inside the frame. Draw the mask last (on top) and make the mask from it; edit the mask
+  later by its `maskId`. Use `vector.makeOpacityMask` with a white-to-black gradient for fades
+  and reflections (luminance: white shows). A clip's own paint is never drawn, so its fill
+  colour does not matter. Effects and shadows on the mask group follow the masked silhouette.
+- **Shadows and glows.** Keep drop shadows subtle: black at 0.15 to 0.3 opacity, `offsetY` 2 to 8,
+  `blur` about twice the offset. Use one light direction for every shadow in a design. Filters
+  export as SVG filters, which some tools (and older renderers) draw slightly differently or not
+  at all; a design that must look identical everywhere should avoid them or rasterize.
+- **Diagrams with connectors.** Lay the boxes out first, then `vector.connect` them (in one
+  `run_commands` batch) rather than drawing lines: connectors stay attached when boxes move, and
+  `route: "elbow"` with a small `radius` reads well in flowcharts. Leave sides `auto` unless a
+  connector must leave a particular side.
+
+- **Constraints for precise, editable geometry.** For technical drawings, diagrams, floor plans or
+  any shape that must keep exact relations, draw it roughly, run `vector.autoConstrain`, then add
+  the dimensions that matter (`vector.addConstraint` distance / angle / radius) and name them so
+  related sizes follow one another (`vector.setConstraintValue` with expressions like `w / 2`).
+  Check `vector.listConstraints` `dof`: aim for `fully` on parts that must not drift; `over`
+  means some constraints repeat others. Prefer few, meaningful constraints over many.
+
+- **Vertical text.** For Japanese, Chinese or Korean set in columns (signage, book spines, posters), use vertical
+  text (`textOrientation: "vertical"` or `vector.setTextOrientation`): CJK stands upright, Latin
+  turns sideways; set a short Latin range `upright: true` to stack it letter by letter. In an
+  area, columns that do not fit past the left edge are `overflow`. Vertical text cannot follow a
+  path.