@pixerate/editor 0.221.1 → 0.222.1

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

package/skills/README.md

@@ -40,7 +40,13 @@ 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-vector-icon-set`](pixerate-vector-icon-set/SKILL.md) | Vector (`pixerate-vector`) | Icons on one grid with padding, one stroke, cap, join and radius, crisp coordinates, clean paths, symbols and SVG export. |
+| [`pixerate-vector-logo`](pixerate-vector-logo/SKILL.md) | Vector (`pixerate-vector`) | Marks from primitives with live booleans, optical corrections, an aligned lockup, colour variants as symbols, outlined delivery files. |
+| [`pixerate-vector-illustration`](pixerate-vector-illustration/SKILL.md) | Vector (`pixerate-vector`) | Block in back to front, gradients and stacked fills for form, masks, blends, subtle shadows with one light, export. |
 | [`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. |
 
@@ -102,9 +108,10 @@ same change.
   it ships evals. Add its row to the workflow table above.
 - **Evals.** Each workflow skill ships at least three scenarios in `evals/*.json`, run by
   `packages/core/tests/agent-skill-evals.test.ts`. An eval has a `prompt` (the task, in the
-  user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }` or
-  `{ "editor": "image", "width", "height", "background", "shapes" }`), `checks` (a read-only
-  tool, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
+  user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }`,
+  `{ "editor": "image", "width", "height", "background", "shapes" }` or `{ "editor":
+  "vector", "width", "height", "setup" }` with commands that draw the starting art), `checks` (a read-only
+  tool, or `run_command` with a read-only command such as `vector.list`, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
   tool calls an expert would make). The test proves each eval: some check fails on the fixture,
   and all pass after the solution. A model harness runs the same file with the model in place
   of the solution. In `expect`, objects match key by key and arrays element by element, with

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