@pixerate/editor 0.185.0 → 0.187.0

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

@@ -126,30 +126,9 @@ drawing or editing either.
    overall strength and `flow` for gradual build-up within the stroke.
 4. **Limit paint with a selection**, or lock transparency (`set_layer_properties`
    `locks.transparency`) to paint only where the layer already has pixels.
-5. **Mix paint colours with `mix_colors`** when the user names paints and amounts ("two parts
-   ultramarine to one part yellow", "a tint of red"). It mixes like pigment, so blue and yellow
-   make green and white makes a tint, where averaging RGB gives grey or a dull pastel. Pass its
-   `mixed` hex as the `color` of `paint_stroke` or `fill_pixels`. Give a strong dark paint a
-   `strength` above 1 when a little of it should tint a lot of white.
-6. **Blend and smear with the Mixer Brush** (`paint_stroke` with `tool: "mixer"`) when the
-   user wants paint to pick up and drag the colours already on the layer (wet blending, softening
-   an edge, pulling one colour into another). `mixer.wet` is how much it picks up (0 paints only
-   the loaded colour), `mixer.mix` how far each dab leans from the loaded colour to the picked-up
-   one, and `mixer.load` below 1 makes long strokes run dry. Use `mixing: "pigment"` for
-   painterly results (blue dragged through yellow goes green); keep `rgb` for retouching, where
-   colours should stay between the two you started with. A brush with `blend: "pigment"` mixes
-   its one colour into the layer; only the mixer carries picked-up colour along the stroke. A `brush.flow` around 0.3..0.6 keeps
-   some of the canvas under each dab and blends more naturally than 1. The stroke samples the
-   target layer only, so paint on the layer that holds the colours to blend.
-7. **Keep the mixer stateless unless you need a carried load.** By default each mixer stroke
-   loads `color` (or the foreground) and is cleaned afterwards, so every call is independent and
-   replays the same. To carry dirty paint from stroke to stroke, pass `mixer.loadEachStroke:
-   false` and `cleanEachStroke: false`, start with `load_mixer_brush`, read the brush with
-   `get_mixer_brush` when unsure, and reset it with `clean_mixer_brush`.
-8. **Gradient paint** (colour that changes as the stroke goes): `set_paint` with `{ type:
-   "gradient", stops, map }`, or `paint_stroke` `paint` for one stroke (brush only). `map.by`
-   `distance` (default 300 px, mirrored) for drag-it-out colour, `pressure`, `direction`,
-   `across-tip`, `random`; stops may be `"paint"` / `"secondary"` (foreground / background).
+5. **Mixing paint, the Mixer Brush and gradient paint**: `mix_colors` mixes named paints like
+   pigment; `paint_stroke` `tool: "mixer"` picks up and smears the layer's colours; gradient paint
+   changes colour along a stroke. Read [references/painting.md](references/painting.md) first.
 
 ### Colour management
 
@@ -241,6 +220,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `get_adjustments` | Read the current state: `values` by control id, `process` version (1 or 2), and `layers` bottom to top with id, kind, params, opacity, blend, enabled and mask. Call first, and to find layer ids. |
 | `list_controls` | Get every base control (id, label, section, min, max, step, default, `requiresProcess`), each layer kind's settable controls (plus `opacity`), the blend mode ids and the `layers.<layerId>.<controlId>` path format. Call once per session before writing. |
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
+| `list_channels` | Read the alpha channels (saved selections): id, name, bounds, percent, overlay and visibility, and whether Quick Mask mode is on. |
 | `select_subject` | Select › Subject (only when the host has a segmentation model): `target` describes what to select ("the dog", "the sky"); an AI model finds the matching objects and selects their outlines, combined by `mode`. `maxSegments` 1 for a single subject. Returns the selection and `found` (label, bounds per object); nothing found leaves the selection unchanged. |
 | `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `shape`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`; shapes a `shape` summary of component ops and kinds and paint types, and `annotation` when migrated from one), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |
 | `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. |
@@ -395,6 +375,14 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `copy_pixels` | Copy the selected pixels of a layer (or with `merged` the visible image) to the editor clipboard, cropped to the selection with its soft edge. No undo step. Returns `width`, `height`, `x`, `y`. |
 | `cut_pixels` | Copy, then clear the selected pixels (one undo step). Returns the size and position. |
 | `paste_pixels` | Paste the clipboard as a new layer: `mode` `new-layer` (centred on the selection or canvas), `in-place`, `into` (masked by the selection) or `outside` (masked by its inverse). One undo step. Returns `layerId`, `bounds`, `masked`. |
+| `save_selection` | Save the selection to a new alpha channel (`name`), or into `channelId` by `mode`. Saved with the document and in PSD. Returns the `channel`. |
+| `load_selection_from_channel` | Load an alpha channel as the selection (`channelId`, `invert`, `mode`). Returns the summary. |
+| `set_channel_properties` | Rename a channel or change its overlay `color`, `opacity`, `indicates` (`masked` / `selected`) and `visible`. Returns the `channel`. |
+| `duplicate_channel` | Copy a channel (`name`, default "<name> copy"). Returns the copy. |
+| `delete_channel` | Delete a channel (undoable). Returns the remaining channels. |
+| `export_mask_image` | Read-only. The selection, a channel (`channelId`) or a layer's painted mask (`layerId`) as a greyscale PNG (white = selected), `invert`, `maxSide` (default 1024). Returns the image and its size. |
+| `load_channel_from_image` | Store a mask image (`image` data URL / URL; `channel`, `threshold`, `invert`, `name`) in a new channel without changing the selection. Returns the `channel`. |
+| `set_quick_mask` | Quick Mask mode (`enabled`): paint, fill and retouch tools without `layerId` edit the selection (white selects, black deselects); turn it off before painting layers. Returns the mode. |
 
 ### Save and open
 

package/skills/pixerate-image-editor/references/painting.md

@@ -0,0 +1,29 @@
+# Painting: mixing paint, the Mixer Brush and gradient paint
+
+Read this before `mix_colors`, a `paint_stroke` with `tool: "mixer"`, or gradient paint
+(`set_paint` / `paint_stroke` `paint`).
+
+1. **Mix paint colours with `mix_colors`** when the user names paints and amounts ("two parts
+   ultramarine to one part yellow", "a tint of red"). It mixes like pigment, so blue and yellow
+   make green and white makes a tint, where averaging RGB gives grey or a dull pastel. Pass its
+   `mixed` hex as the `color` of `paint_stroke` or `fill_pixels`. Give a strong dark paint a
+   `strength` above 1 when a little of it should tint a lot of white.
+2. **Blend and smear with the Mixer Brush** (`paint_stroke` with `tool: "mixer"`) when the
+   user wants paint to pick up and drag the colours already on the layer (wet blending, softening
+   an edge, pulling one colour into another). `mixer.wet` is how much it picks up (0 paints only
+   the loaded colour), `mixer.mix` how far each dab leans from the loaded colour to the picked-up
+   one, and `mixer.load` below 1 makes long strokes run dry. Use `mixing: "pigment"` for
+   painterly results (blue dragged through yellow goes green); keep `rgb` for retouching, where
+   colours should stay between the two you started with. A brush with `blend: "pigment"` mixes
+   its one colour into the layer; only the mixer carries picked-up colour along the stroke. A `brush.flow` around 0.3..0.6 keeps
+   some of the canvas under each dab and blends more naturally than 1. The stroke samples the
+   target layer only, so paint on the layer that holds the colours to blend.
+3. **Keep the mixer stateless unless you need a carried load.** By default each mixer stroke
+   loads `color` (or the foreground) and is cleaned afterwards, so every call is independent and
+   replays the same. To carry dirty paint from stroke to stroke, pass `mixer.loadEachStroke:
+   false` and `cleanEachStroke: false`, start with `load_mixer_brush`, read the brush with
+   `get_mixer_brush` when unsure, and reset it with `clean_mixer_brush`.
+4. **Gradient paint** (colour that changes as the stroke goes): `set_paint` with `{ type:
+   "gradient", stops, map }`, or `paint_stroke` `paint` for one stroke (brush only). `map.by`
+   `distance` (default 300 px, mirrored) for drag-it-out colour, `pressure`, `direction`,
+   `across-tip`, `random`; stops may be `"paint"` / `"secondary"` (foreground / background).

package/skills/pixerate-image-selection-masking/SKILL.md

@@ -53,6 +53,9 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    - `grow_selection` (tolerance 10–30) picks up the shades a wand click missed;
      `select_similar` adds the same colours elsewhere in the image.
    - `contract` 1–2 px pulls the edge off a halo.
+   - Paint it directly: `set_quick_mask` `enabled: true`, then `paint_stroke` without
+     `layerId` (white adds, black removes, a soft brush feathers; `blur_stroke` softens a part
+     of the edge), then `set_quick_mask` `enabled: false`.
    - `refine_selection` snaps to real edges: radius 2–4 for hard edges, 8–20 for hair and fur;
      `smartRadius: true` for mixed edges.
    - `shiftEdge` −10..−30 % tightens a refined edge that picked up background.
@@ -70,7 +73,14 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    - A copy elsewhere: `copy_pixels`, then `paste_pixels` (`into` masks it by a selection).
    Soften with the mask's own `feather` / `density` rather than `modify_selection` `feather`, so
    it stays adjustable.
-6. **Verify.** `render_preview` at 1024 px or more, and `capture_view` on the edge at 2–8×.
+6. **Store.** `save_selection` with a clear name before you change a selection that took
+   work, and whenever it will be needed again (a second adjustment, a later refinement). Load
+   it with `load_selection_from_channel`; channels are saved with the document and in PSDs.
+   To hand a mask to another tool or service, or to look at it alone, `export_mask_image`
+   writes the selection, a channel or a layer mask as a greyscale PNG; a matte that comes
+   back goes into a channel with `load_channel_from_image` (or straight to the selection with
+   `load_selection_from_image`).
+7. **Verify.** `render_preview` at 1024 px or more, and `capture_view` on the edge at 2–8×.
    **Check:** no fringe of the old background colour, no stair-steps, no visible line where an
    adjustment ends. Fix by loading the mask back (`load_selection_from_mask`), refining, and
    masking again.
@@ -85,7 +95,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | A colour spread across the image (all the reds, a dress) | `select_color_range` with `samples` (several picks) or a hue `preset`; `localized` to keep one area |
 | Tones (shadows, highlights, a luminosity mask) | `select_color_range` with `preset` `shadows` / `midtones` / `highlights` |
 | Skin for retouching | `select_color_range` `preset: "skinTones"`, then `intersect` with a box around the face |
-| An AI matte or saved mask from the host | `load_selection_from_image` (soft: no `threshold`), then `refine_selection` |
+| An AI matte or saved mask from the host | `load_selection_from_image` (soft: no `threshold`), then `refine_selection`; `load_channel_from_image` to keep it for later |
 | An existing layer mask | `load_selection_from_mask` |
 | A cutout, shape or text already on its own layer | `select_layer_transparency` (exact, soft where the layer is) |
 | A dead pixel row or column | `select_line`, then fill or heal it |
@@ -151,6 +161,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - **A forgotten selection limits new layers and filters:** `add_adjustment_layer`,
   `apply_effect` and `add_smart_filter` mask themselves by it. `deselect` first for a global
   change, or pass `useSelection: false`.
+- **Quick Mask left on:** while it is on, `paint_stroke` and `fill_pixels` without `layerId`
+  edit the selection, not the image. Turn it off when the selection is done.
 - **Hidden selection still applies:** with `set_selection_display` `none`, paint and fills are
   still limited to it. `deselect` before a whole-layer edit.
 - **Wrong coordinates:** use natural image pixels, not preview pixels. On a cropped or rotated
@@ -168,6 +180,12 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere
 - `reselect`: undo a deselect
+- `save_selection`, `load_selection_from_channel`, `list_channels`: keep selections as alpha channels
+- `set_channel_properties`, `duplicate_channel`, `delete_channel`: manage channels
+- `export_mask_image`: a selection, channel or layer mask as a greyscale PNG
+- `load_channel_from_image`: a mask image into a new channel
+- `set_quick_mask`: paint the selection
+- `fill_pixels`, `blur_stroke`: fill or soften the selection in Quick Mask mode
 - `magic_wand`: similar colour from a seed
 - `select_color_range`: colour samples, hue, tone and skin presets
 - `select_subject`: a subject by description (needs a host model)