@pixerate/editor 0.206.0 → 0.207.0

package/dist/image-editor/selection/select-and-mask.d.cts

@@ -0,0 +1,126 @@
+/**
+ * The Select and Mask workspace without a UI: its settings, strokes, preview and view modes, shared
+ * by the React and Svelte workspaces. Everything it holds is plain data (the strokes are
+ * `RefineEdit`s), and OK runs the same `refineSelectionTo` call an agent makes with `edits`, so
+ * the workspace and an agent produce the same result in one undo step.
+ *
+ * The preview is computed on a copy reduced to {@link PREVIEW_SIZE} px (or at full size with High
+ * Quality Preview) and drawn as RGBA in the chosen view mode.
+ */
+import type { ImageEditorController, RefineOutput, RefineOutputResult } from '../controller.cjs';
+import type { ImagePoint } from '../types.cjs';
+import { type RefineEdgeParams } from './refine.cjs';
+import { type RefineEdit } from './refine-edits.cjs';
+export type SelectAndMaskView = 'onion-skin' | 'marching-ants' | 'overlay' | 'on-black' | 'on-white' | 'black-white' | 'on-layers';
+export type SelectAndMaskTool = 'quick-select' | 'refine-brush' | 'brush' | 'object' | 'lasso' | 'hand' | 'zoom';
+/** The view modes with Photoshop's keys, in menu order. */
+export declare const SELECT_AND_MASK_VIEWS: readonly {
+    id: SelectAndMaskView;
+    label: string;
+    key: string;
+    opacity: number;
+}[];
+/** The workspace tools with Photoshop's keys. */
+export declare const SELECT_AND_MASK_TOOLS: readonly {
+    id: SelectAndMaskTool;
+    label: string;
+    key: string;
+}[];
+export interface SelectAndMaskSettings {
+    params: Required<RefineEdgeParams>;
+    output: RefineOutput;
+    /** Decontaminate Colors amount 0..100 (new-layer outputs). */
+    decontaminate: number;
+    refineMode: 'color' | 'object';
+    view: SelectAndMaskView;
+    /** How strongly the view shows what is not selected, 0..1. */
+    opacity: number;
+    /** Show only the area the refinement changes. */
+    showEdge: boolean;
+    /** Show the selection as it was, before the workspace. */
+    showOriginal: boolean;
+    /** Update the preview while painting (otherwise on release). */
+    realTime: boolean;
+    /** Preview at full size instead of a reduced copy. */
+    highQuality: boolean;
+    /** Keep these settings for the next time the workspace opens. */
+    remember: boolean;
+    tool: SelectAndMaskTool;
+    /** Brush diameter in natural pixels. */
+    brushSize: number;
+    brushMode: 'add' | 'subtract';
+}
+export declare const DEFAULT_SELECT_AND_MASK_SETTINGS: SelectAndMaskSettings;
+/** Long side of the reduced preview. */
+export declare const PREVIEW_SIZE = 1024;
+export declare class SelectAndMaskSession {
+    readonly controller: ImageEditorController;
+    private settingsValue;
+    private readonly editsList;
+    /** The edit being painted, shown in the preview but not yet in `edits`. */
+    private live;
+    private dragStart;
+    private pixels;
+    private previewPixels;
+    private base;
+    private previewMask;
+    private baseMask;
+    private readonly listeners;
+    /** Why the preview could not be made (no pixels), for the UI. */
+    error: string | null;
+    /** A note for the UI, such as object aware refinement applying only on OK. */
+    note: string | null;
+    /** Bumped each time the preview changes, so a UI can redraw. */
+    revision: number;
+    constructor(controller: ImageEditorController);
+    get settings(): SelectAndMaskSettings;
+    get edits(): readonly RefineEdit[];
+    /** Reads the image and makes the first preview. Resolves to false when the pixels are unavailable. */
+    open(): Promise<boolean>;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    /** Preview size and the scale from natural pixels to it. */
+    get previewSize(): {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    /** Changes settings; the preview follows. Choosing a view also sets its usual opacity. */
+    update(changes: Partial<SelectAndMaskSettings>): void;
+    private rescale;
+    /** Recomputes the preview mask from the base selection, the strokes and the settings. */
+    recompute(): void;
+    /** Coverage 0..1 of the preview at (x, y) in preview pixels (for tests and hover readouts). */
+    coverageAt(x: number, y: number): number;
+    /** The preview drawn in the current view mode: RGBA at {@link previewSize}. */
+    render(): Uint8ClampedArray;
+    /**
+     * Pointer down at `point` (natural pixels) with the current tool: starts a stroke (Quick
+     * Selection, brushes, lasso) or a box (Object Selection). Alt (or the subtract mode) removes.
+     * Hand and Zoom are the UI's own; they return false here.
+     */
+    begin(point: ImagePoint, modifiers?: {
+        altKey?: boolean;
+    }): boolean;
+    /** Pointer move while a stroke is down. */
+    move(point: ImagePoint): void;
+    /** Pointer up: the stroke becomes an edit (one step of the workspace's own undo). */
+    end(): void;
+    /** Removes the last stroke (Ctrl/⌘+Z in the workspace). Returns false when there is none. */
+    undoEdit(): boolean;
+    /** Clears the strokes and goes back to the default settings (Reset). */
+    reset(): void;
+    /**
+     * Photoshop's keys in the workspace: a view letter, F (next view), X (all views off and on:
+     * Show Original), J (Show Edge), P (Show Original), a tool letter, [ and ] (brush size).
+     * Returns true when the key was used.
+     */
+    handleKey(key: string): boolean;
+    /**
+     * OK: applies the strokes and settings to the image as one undo step (the same call an agent
+     * makes) and remembers the settings when asked to.
+     */
+    commit(): Promise<RefineOutputResult>;
+}
+/** Forgets the remembered workspace settings. */
+export declare function forgetSelectAndMaskSettings(): void;

package/dist/image-editor/selection/select-and-mask.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The Select and Mask workspace without a UI: its settings, strokes, preview and view modes, shared
+ * by the React and Svelte workspaces. Everything it holds is plain data (the strokes are
+ * `RefineEdit`s), and OK runs the same `refineSelectionTo` call an agent makes with `edits`, so
+ * the workspace and an agent produce the same result in one undo step.
+ *
+ * The preview is computed on a copy reduced to {@link PREVIEW_SIZE} px (or at full size with High
+ * Quality Preview) and drawn as RGBA in the chosen view mode.
+ */
+import type { ImageEditorController, RefineOutput, RefineOutputResult } from '../controller.js';
+import type { ImagePoint } from '../types.js';
+import { type RefineEdgeParams } from './refine.js';
+import { type RefineEdit } from './refine-edits.js';
+export type SelectAndMaskView = 'onion-skin' | 'marching-ants' | 'overlay' | 'on-black' | 'on-white' | 'black-white' | 'on-layers';
+export type SelectAndMaskTool = 'quick-select' | 'refine-brush' | 'brush' | 'object' | 'lasso' | 'hand' | 'zoom';
+/** The view modes with Photoshop's keys, in menu order. */
+export declare const SELECT_AND_MASK_VIEWS: readonly {
+    id: SelectAndMaskView;
+    label: string;
+    key: string;
+    opacity: number;
+}[];
+/** The workspace tools with Photoshop's keys. */
+export declare const SELECT_AND_MASK_TOOLS: readonly {
+    id: SelectAndMaskTool;
+    label: string;
+    key: string;
+}[];
+export interface SelectAndMaskSettings {
+    params: Required<RefineEdgeParams>;
+    output: RefineOutput;
+    /** Decontaminate Colors amount 0..100 (new-layer outputs). */
+    decontaminate: number;
+    refineMode: 'color' | 'object';
+    view: SelectAndMaskView;
+    /** How strongly the view shows what is not selected, 0..1. */
+    opacity: number;
+    /** Show only the area the refinement changes. */
+    showEdge: boolean;
+    /** Show the selection as it was, before the workspace. */
+    showOriginal: boolean;
+    /** Update the preview while painting (otherwise on release). */
+    realTime: boolean;
+    /** Preview at full size instead of a reduced copy. */
+    highQuality: boolean;
+    /** Keep these settings for the next time the workspace opens. */
+    remember: boolean;
+    tool: SelectAndMaskTool;
+    /** Brush diameter in natural pixels. */
+    brushSize: number;
+    brushMode: 'add' | 'subtract';
+}
+export declare const DEFAULT_SELECT_AND_MASK_SETTINGS: SelectAndMaskSettings;
+/** Long side of the reduced preview. */
+export declare const PREVIEW_SIZE = 1024;
+export declare class SelectAndMaskSession {
+    readonly controller: ImageEditorController;
+    private settingsValue;
+    private readonly editsList;
+    /** The edit being painted, shown in the preview but not yet in `edits`. */
+    private live;
+    private dragStart;
+    private pixels;
+    private previewPixels;
+    private base;
+    private previewMask;
+    private baseMask;
+    private readonly listeners;
+    /** Why the preview could not be made (no pixels), for the UI. */
+    error: string | null;
+    /** A note for the UI, such as object aware refinement applying only on OK. */
+    note: string | null;
+    /** Bumped each time the preview changes, so a UI can redraw. */
+    revision: number;
+    constructor(controller: ImageEditorController);
+    get settings(): SelectAndMaskSettings;
+    get edits(): readonly RefineEdit[];
+    /** Reads the image and makes the first preview. Resolves to false when the pixels are unavailable. */
+    open(): Promise<boolean>;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    /** Preview size and the scale from natural pixels to it. */
+    get previewSize(): {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    /** Changes settings; the preview follows. Choosing a view also sets its usual opacity. */
+    update(changes: Partial<SelectAndMaskSettings>): void;
+    private rescale;
+    /** Recomputes the preview mask from the base selection, the strokes and the settings. */
+    recompute(): void;
+    /** Coverage 0..1 of the preview at (x, y) in preview pixels (for tests and hover readouts). */
+    coverageAt(x: number, y: number): number;
+    /** The preview drawn in the current view mode: RGBA at {@link previewSize}. */
+    render(): Uint8ClampedArray;
+    /**
+     * Pointer down at `point` (natural pixels) with the current tool: starts a stroke (Quick
+     * Selection, brushes, lasso) or a box (Object Selection). Alt (or the subtract mode) removes.
+     * Hand and Zoom are the UI's own; they return false here.
+     */
+    begin(point: ImagePoint, modifiers?: {
+        altKey?: boolean;
+    }): boolean;
+    /** Pointer move while a stroke is down. */
+    move(point: ImagePoint): void;
+    /** Pointer up: the stroke becomes an edit (one step of the workspace's own undo). */
+    end(): void;
+    /** Removes the last stroke (Ctrl/⌘+Z in the workspace). Returns false when there is none. */
+    undoEdit(): boolean;
+    /** Clears the strokes and goes back to the default settings (Reset). */
+    reset(): void;
+    /**
+     * Photoshop's keys in the workspace: a view letter, F (next view), X (all views off and on:
+     * Show Original), J (Show Edge), P (Show Original), a tool letter, [ and ] (brush size).
+     * Returns true when the key was used.
+     */
+    handleKey(key: string): boolean;
+    /**
+     * OK: applies the strokes and settings to the image as one undo step (the same call an agent
+     * makes) and remembers the settings when asked to.
+     */
+    commit(): Promise<RefineOutputResult>;
+}
+/** Forgets the remembered workspace settings. */
+export declare function forgetSelectAndMaskSettings(): void;

package/package.json

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

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

@@ -269,7 +269,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `grow_selection` | Select › Grow: add connected pixels within `tolerance` (default 32) of a selected colour; follows colour, not distance. `sample`, `sampleMerged`. Fails when nothing is selected. Returns the summary. |
 | `select_similar` | Select › Similar: add every pixel in the image within `tolerance` of a selected colour, connected or not. Fails when nothing is selected. Returns the summary. |
 | `reselect` | Bring back the last selection `deselect` cleared (one undo step). Fails when there is none. Returns the summary. |
-| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer` or `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), with `decontaminate` 0..100 for new layers. `edits` (`quick-select`, `brush` add/subtract, `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
+| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer` or `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), with `decontaminate` 0..100 for new layers. `edits` (`quick-select`, `brush`, `lasso`, `object` add/subtract; `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
 | `update_adjustment_layer` | Change a layer's `enabled` (false hides it without deleting), `blend`, `opacity` (0..1) or `name` in one undo step. Returns the layer. Its parameters change with `set_adjustments`. Toggle `enabled` to compare a layer's effect before and after. |
 | `move_adjustment_layer` | Move a layer to index `to` (0 = bottom, applied first; past the top means top). Order matters: a curves layer above a hue/saturation layer works on its output. Fails when the layer is already there. Returns the ids bottom to top. |
 | `remove_adjustment_layer` | Delete a layer and its mask. Prefer hiding it with `update_adjustment_layer` when the user may want it back. Returns the remaining ids. |

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

@@ -59,8 +59,10 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
    - `refine_selection` snaps to real edges: radius 2–4 for hard edges, 8–20 for hair and fur;
      `smartRadius: true` for mixed edges. For flyaway hair beyond the radius, add `edits` with a
      `refine-brush` stroke along it (size covering the strands); fix misses and leaks in the same
-     call with `quick-select` or `brush` strokes (`mode: "subtract"` to remove). With a host
-     model, `refineMode: "object"` refines from the model's outline.
+     call with `quick-select`, `brush` or `lasso` strokes, or an `object` box (`mode:
+     "subtract"` to remove). These are the Select and Mask workspace's own tools, so a person
+     can open the same edits in the workspace. With a host model, `refineMode: "object"`
+     refines from the model's outline.
    - `shiftEdge` −10..−30 % tightens a refined edge that picked up background.
    **Check:** `percent` changed by roughly what you intended (a few percent at most for a
    cleanup).