@pixerate/editor 0.185.0 → 0.186.0

package/dist/image-editor/layers/model.d.cts

@@ -474,7 +474,11 @@ export interface SmartObjectLayer extends LayerBase {
 export type ImageLayer = PixelLayer | AdjustmentLayerNode | GroupLayer | AnnotationLayer | SmartObjectLayer | ShapeLayer | TypeLayer;
 export type ImageLayerType = ImageLayer['type'];
 /** Which part of the active layer painting targets (`filter-mask`: a smart object's filter mask). */
-export type LayerTarget = 'pixels' | 'mask' | 'filter-mask';
+/**
+ * What a paint, fill or retouch writes: a layer's pixels, its mask, a smart object's filter mask,
+ * or (in Quick Mask mode) the selection itself (`quick-mask`, not a layer).
+ */
+export type LayerTarget = 'pixels' | 'mask' | 'filter-mask' | 'quick-mask';
 /** A fresh id with `prefix` (`layer`, `flt`, …). */
 export declare function newLayerId(prefix?: string): string;
 export type LayerLocation = RasterLayerLocation<ImageLayer>;

package/dist/image-editor/layers/model.d.ts

@@ -474,7 +474,11 @@ export interface SmartObjectLayer extends LayerBase {
 export type ImageLayer = PixelLayer | AdjustmentLayerNode | GroupLayer | AnnotationLayer | SmartObjectLayer | ShapeLayer | TypeLayer;
 export type ImageLayerType = ImageLayer['type'];
 /** Which part of the active layer painting targets (`filter-mask`: a smart object's filter mask). */
-export type LayerTarget = 'pixels' | 'mask' | 'filter-mask';
+/**
+ * What a paint, fill or retouch writes: a layer's pixels, its mask, a smart object's filter mask,
+ * or (in Quick Mask mode) the selection itself (`quick-mask`, not a layer).
+ */
+export type LayerTarget = 'pixels' | 'mask' | 'filter-mask' | 'quick-mask';
 /** A fresh id with `prefix` (`layer`, `flt`, …). */
 export declare function newLayerId(prefix?: string): string;
 export type LayerLocation = RasterLayerLocation<ImageLayer>;

package/dist/image-editor/layers/paint-ui.d.cts

@@ -139,7 +139,8 @@ export interface ShortcutEvent {
 /**
  * Applies a paint shortcut. Returns true when it was one (the caller then prevents the default).
  * B / Shift+B (Mixer Brush) / E / V choose the tool; [ and ] change the size, with Shift the hardness by 25 %; 1..9 set the
- * opacity to 10..90 % and 0 to 100 %; D resets the colours to black and white; X swaps them.
+ * opacity to 10..90 % and 0 to 100 %; D resets the colours to black and white; X swaps them; Q
+ * toggles Quick Mask mode (painting then edits the selection).
  */
 export declare function handlePaintShortcut(controller: ImageEditorController, e: ShortcutEvent): boolean;
 /** One pointer sample in document pixels. */

package/dist/image-editor/layers/paint-ui.d.ts

@@ -139,7 +139,8 @@ export interface ShortcutEvent {
 /**
  * Applies a paint shortcut. Returns true when it was one (the caller then prevents the default).
  * B / Shift+B (Mixer Brush) / E / V choose the tool; [ and ] change the size, with Shift the hardness by 25 %; 1..9 set the
- * opacity to 10..90 % and 0 to 100 %; D resets the colours to black and white; X swaps them.
+ * opacity to 10..90 % and 0 to 100 %; D resets the colours to black and white; X swaps them; Q
+ * toggles Quick Mask mode (painting then edits the selection).
  */
 export declare function handlePaintShortcut(controller: ImageEditorController, e: ShortcutEvent): boolean;
 /** One pointer sample in document pixels. */

package/dist/image-editor/layers/serialize.d.cts

@@ -8,6 +8,7 @@
  */
 import type { Annotation, CropBox, DepthMaskOptions, ImageTransform } from '../types.cjs';
 import type { SerializedSelection } from '../selection/mask.cjs';
+import type { SerializedAlphaChannel } from '../selection/channels.cjs';
 import type { SerializedColorMode, SerializedColorProfile } from '../color-management.cjs';
 import { type PsdSmartFilter, type EffectSmartFilter, type ImageEffectGenerator, type SmartContents, type ImageLayer, type LayerFilter, type LayerLocks, type ShapeComponent, type ShapePaint, type ShapeStroke, type ParagraphRun, type TextRun, type TypeLayer } from './model.cjs';
 import { type GlobalLight, type LayerEffect, type LayerEffects } from '../../raster/effects/model.cjs';
@@ -222,6 +223,8 @@ export interface SerializedLayeredImageEditorState {
     /** Blur migrated from a v1 / v2 document with adjustment layers (runs after the layers). */
     legacyOutputBlur?: number;
     selection?: SerializedSelection;
+    /** Alpha channels (saved selections), run-length encoded. */
+    channels?: SerializedAlphaChannel[];
     /** Global light for layer effects (missing = 120°, 30°). */
     globalLight?: GlobalLight;
     /** The document's patterns for pattern effects, each an RGBA PNG data URL. */

package/dist/image-editor/layers/serialize.d.ts

@@ -8,6 +8,7 @@
  */
 import type { Annotation, CropBox, DepthMaskOptions, ImageTransform } from '../types.js';
 import type { SerializedSelection } from '../selection/mask.js';
+import type { SerializedAlphaChannel } from '../selection/channels.js';
 import type { SerializedColorMode, SerializedColorProfile } from '../color-management.js';
 import { type PsdSmartFilter, type EffectSmartFilter, type ImageEffectGenerator, type SmartContents, type ImageLayer, type LayerFilter, type LayerLocks, type ShapeComponent, type ShapePaint, type ShapeStroke, type ParagraphRun, type TextRun, type TypeLayer } from './model.js';
 import { type GlobalLight, type LayerEffect, type LayerEffects } from '../../raster/effects/model.js';
@@ -222,6 +223,8 @@ export interface SerializedLayeredImageEditorState {
     /** Blur migrated from a v1 / v2 document with adjustment layers (runs after the layers). */
     legacyOutputBlur?: number;
     selection?: SerializedSelection;
+    /** Alpha channels (saved selections), run-length encoded. */
+    channels?: SerializedAlphaChannel[];
     /** Global light for layer effects (missing = 120°, 30°). */
     globalLight?: GlobalLight;
     /** The document's patterns for pattern effects, each an RGBA PNG data URL. */

package/dist/image-editor/psd/channels.d.cts

@@ -0,0 +1,24 @@
+import type { PsdResource } from './file.cjs';
+/** An alpha channel as the PSD code reads and writes it: an 8-bit plane over the canvas. */
+export interface PsdAlphaChannel {
+    name: string;
+    /** `width × height` coverage, 255 = selected. */
+    data: Uint8Array;
+    /** `#rrggbb` overlay colour. */
+    color: string;
+    /** 0..1. */
+    opacity: number;
+    indicates: 'masked' | 'selected';
+}
+/** The image resources that name and describe `channels`. */
+export declare function alphaChannelResources(channels: readonly PsdAlphaChannel[]): PsdResource[];
+/**
+ * The alpha channels of a file: merged planes `first … channels − 1`, named from 1045 (or
+ * 1006), described by 1077. Spot colour channels (kind 2) are left out and reported.
+ */
+export declare function readAlphaChannels(planes: Uint8Array, header: {
+    width: number;
+    height: number;
+    depth: number;
+    channels: number;
+}, first: number, resource: (id: number) => Uint8Array | undefined, warn: (message: string) => void): PsdAlphaChannel[];

package/dist/image-editor/psd/channels.d.ts

@@ -0,0 +1,24 @@
+import type { PsdResource } from './file.js';
+/** An alpha channel as the PSD code reads and writes it: an 8-bit plane over the canvas. */
+export interface PsdAlphaChannel {
+    name: string;
+    /** `width × height` coverage, 255 = selected. */
+    data: Uint8Array;
+    /** `#rrggbb` overlay colour. */
+    color: string;
+    /** 0..1. */
+    opacity: number;
+    indicates: 'masked' | 'selected';
+}
+/** The image resources that name and describe `channels`. */
+export declare function alphaChannelResources(channels: readonly PsdAlphaChannel[]): PsdResource[];
+/**
+ * The alpha channels of a file: merged planes `first … channels − 1`, named from 1045 (or
+ * 1006), described by 1077. Spot colour channels (kind 2) are left out and reported.
+ */
+export declare function readAlphaChannels(planes: Uint8Array, header: {
+    width: number;
+    height: number;
+    depth: number;
+    channels: number;
+}, first: number, resource: (id: number) => Uint8Array | undefined, warn: (message: string) => void): PsdAlphaChannel[];

package/dist/image-editor/psd/export.d.cts

@@ -1,4 +1,5 @@
 import { type ImageLayer, type SmartContents } from '../layers/model.cjs';
+import { type PsdAlphaChannel } from './channels.cjs';
 import { type GlobalLight } from '../../raster/effects/model.cjs';
 import { type EffectPattern } from '../../raster/effects/patterns.cjs';
 export interface PsdExportInput {
@@ -8,6 +9,8 @@ export interface PsdExportInput {
     layers: readonly ImageLayer[];
     /** The composite, `width × height` RGBA, written as the merged image. */
     merged: ArrayLike<number>;
+    /** Alpha channels, written as extra merged planes with their names and display info. */
+    alphaChannels?: readonly PsdAlphaChannel[];
     /** Pixels per inch (default 72). */
     resolution?: number;
     /** The document's patterns; those the effects use are embedded (built-in ones too). */

package/dist/image-editor/psd/export.d.ts

@@ -1,4 +1,5 @@
 import { type ImageLayer, type SmartContents } from '../layers/model.js';
+import { type PsdAlphaChannel } from './channels.js';
 import { type GlobalLight } from '../../raster/effects/model.js';
 import { type EffectPattern } from '../../raster/effects/patterns.js';
 export interface PsdExportInput {
@@ -8,6 +9,8 @@ export interface PsdExportInput {
     layers: readonly ImageLayer[];
     /** The composite, `width × height` RGBA, written as the merged image. */
     merged: ArrayLike<number>;
+    /** Alpha channels, written as extra merged planes with their names and display info. */
+    alphaChannels?: readonly PsdAlphaChannel[];
     /** Pixels per inch (default 72). */
     resolution?: number;
     /** The document's patterns; those the effects use are embedded (built-in ones too). */

package/dist/image-editor/psd/import.d.cts

@@ -1,3 +1,11 @@
+/**
+ * PSD / PSB → our layer tree. Everything the model holds maps directly (smart objects with their
+ * embedded contents, placement, warp, smart filters and filter mask; shape layers with their
+ * paths, fill, stroke and live shapes; type layers with their text, styles and Photoshop's pixels
+ * until edited); everything else comes in as close as it can (fill layers as their stored pixels)
+ * with a warning naming the layers.
+ */
+import { type PsdAlphaChannel } from './channels.cjs';
 import type { ImageLayer, LayerBlendMode } from '../layers/model.cjs';
 import { type PsdFile } from './file.cjs';
 import type { DocumentColorProfile } from '../color-management.cjs';
@@ -54,6 +62,8 @@ export interface PsdImportResult {
     };
     /** The bits per channel the layers keep: 16 or 32 for such files (not indexed or bitmap), else 8. */
     bitDepth: 8 | 16 | 32;
+    /** The file's alpha channels (saved selections), as 8-bit planes. */
+    alphaChannels?: PsdAlphaChannel[];
 }
 export interface PsdImportOptions {
     /** Makes layer ids (defaults to `psd-<n>`). */

package/dist/image-editor/psd/import.d.ts

@@ -1,3 +1,11 @@
+/**
+ * PSD / PSB → our layer tree. Everything the model holds maps directly (smart objects with their
+ * embedded contents, placement, warp, smart filters and filter mask; shape layers with their
+ * paths, fill, stroke and live shapes; type layers with their text, styles and Photoshop's pixels
+ * until edited); everything else comes in as close as it can (fill layers as their stored pixels)
+ * with a warning naming the layers.
+ */
+import { type PsdAlphaChannel } from './channels.js';
 import type { ImageLayer, LayerBlendMode } from '../layers/model.js';
 import { type PsdFile } from './file.js';
 import type { DocumentColorProfile } from '../color-management.js';
@@ -54,6 +62,8 @@ export interface PsdImportResult {
     };
     /** The bits per channel the layers keep: 16 or 32 for such files (not indexed or bitmap), else 8. */
     bitDepth: 8 | 16 | 32;
+    /** The file's alpha channels (saved selections), as 8-bit planes. */
+    alphaChannels?: PsdAlphaChannel[];
 }
 export interface PsdImportOptions {
     /** Makes layer ids (defaults to `psd-<n>`). */

package/dist/image-editor/renderer.d.cts

@@ -174,6 +174,12 @@ export declare class ImageEditorRenderer {
     private publishHistogram;
     private quickMaskCache;
     private outlineCache;
+    private emptyMaskCache;
+    /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
+    private emptyMask;
+    private overlayCache;
+    /** A channel's tint (colour, opacity, masked or selected area), drawn in natural image space. */
+    private drawMaskOverlay;
     /** Rubylith over the unselected area, drawn in natural image space. */
     private drawQuickMask;
     /**

package/dist/image-editor/renderer.d.ts

@@ -174,6 +174,12 @@ export declare class ImageEditorRenderer {
     private publishHistogram;
     private quickMaskCache;
     private outlineCache;
+    private emptyMaskCache;
+    /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
+    private emptyMask;
+    private overlayCache;
+    /** A channel's tint (colour, opacity, masked or selected area), drawn in natural image space. */
+    private drawMaskOverlay;
     /** Rubylith over the unselected area, drawn in natural image space. */
     private drawQuickMask;
     /**

package/dist/image-editor/selection/channels.d.cts

@@ -0,0 +1,52 @@
+import { type SelectionMask, type SerializedSelection } from './mask.cjs';
+/**
+ * An alpha channel: a saved selection kept with the document (Select › Save Selection), shown
+ * as a tinted overlay when visible. Its mask is the selection's 8-bit coverage over the canvas
+ * (immutable, so undo steps share it).
+ */
+export interface AlphaChannel {
+    id: string;
+    name: string;
+    /** Coverage (255 = selected). An empty channel has a mask with `bounds: null`. */
+    mask: SelectionMask;
+    /** Overlay tint, `#rrggbb` (default red, the Quick Mask's). */
+    color: string;
+    /** Overlay opacity 0..1 (default 0.5). */
+    opacity: number;
+    /** Whether the tint covers the `masked` (unselected, default) or the `selected` area. */
+    indicates: 'masked' | 'selected';
+    /** Shown as an overlay on the canvas (default false). */
+    visible: boolean;
+}
+/** An alpha channel as stored in a document. */
+export interface SerializedAlphaChannel extends Omit<AlphaChannel, 'mask'> {
+    mask: SerializedSelection;
+}
+export declare const DEFAULT_CHANNEL_COLOR = "#ff0000";
+/** A summary of a channel for agents and panels (no pixels). */
+export declare function describeChannel(channel: AlphaChannel): {
+    bounds: import("../index.cjs").CropBox | null;
+    percent: number;
+    id: string;
+    name: string;
+    /** Overlay tint, `#rrggbb` (default red, the Quick Mask's). */
+    color: string;
+    /** Overlay opacity 0..1 (default 0.5). */
+    opacity: number;
+    /** Whether the tint covers the `masked` (unselected, default) or the `selected` area. */
+    indicates: "masked" | "selected";
+    /** Shown as an overlay on the canvas (default false). */
+    visible: boolean;
+};
+export declare function serializeChannels(channels: readonly AlphaChannel[]): SerializedAlphaChannel[];
+/** Restores stored channels, skipping (and reporting) damaged ones or ones of another size. */
+export declare function deserializeChannels(value: unknown, size: {
+    width: number;
+    height: number;
+}, problems?: string[]): AlphaChannel[];
+/** A channel's grey thumbnail (white = selected) as RGBA pixels, at most `maxSide` px. */
+export declare function channelThumbnail(channel: AlphaChannel, maxSide?: number): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};

package/dist/image-editor/selection/channels.d.ts

@@ -0,0 +1,52 @@
+import { type SelectionMask, type SerializedSelection } from './mask.js';
+/**
+ * An alpha channel: a saved selection kept with the document (Select › Save Selection), shown
+ * as a tinted overlay when visible. Its mask is the selection's 8-bit coverage over the canvas
+ * (immutable, so undo steps share it).
+ */
+export interface AlphaChannel {
+    id: string;
+    name: string;
+    /** Coverage (255 = selected). An empty channel has a mask with `bounds: null`. */
+    mask: SelectionMask;
+    /** Overlay tint, `#rrggbb` (default red, the Quick Mask's). */
+    color: string;
+    /** Overlay opacity 0..1 (default 0.5). */
+    opacity: number;
+    /** Whether the tint covers the `masked` (unselected, default) or the `selected` area. */
+    indicates: 'masked' | 'selected';
+    /** Shown as an overlay on the canvas (default false). */
+    visible: boolean;
+}
+/** An alpha channel as stored in a document. */
+export interface SerializedAlphaChannel extends Omit<AlphaChannel, 'mask'> {
+    mask: SerializedSelection;
+}
+export declare const DEFAULT_CHANNEL_COLOR = "#ff0000";
+/** A summary of a channel for agents and panels (no pixels). */
+export declare function describeChannel(channel: AlphaChannel): {
+    bounds: import("../index.js").CropBox | null;
+    percent: number;
+    id: string;
+    name: string;
+    /** Overlay tint, `#rrggbb` (default red, the Quick Mask's). */
+    color: string;
+    /** Overlay opacity 0..1 (default 0.5). */
+    opacity: number;
+    /** Whether the tint covers the `masked` (unselected, default) or the `selected` area. */
+    indicates: "masked" | "selected";
+    /** Shown as an overlay on the canvas (default false). */
+    visible: boolean;
+};
+export declare function serializeChannels(channels: readonly AlphaChannel[]): SerializedAlphaChannel[];
+/** Restores stored channels, skipping (and reporting) damaged ones or ones of another size. */
+export declare function deserializeChannels(value: unknown, size: {
+    width: number;
+    height: number;
+}, problems?: string[]): AlphaChannel[];
+/** A channel's grey thumbnail (white = selected) as RGBA pixels, at most `maxSide` px. */
+export declare function channelThumbnail(channel: AlphaChannel, maxSide?: number): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};

package/dist/image-editor/selection/gesture.d.cts

@@ -76,3 +76,10 @@ export declare function handleSelectionShortcut(controller: ImageEditorControlle
     shiftKey?: boolean;
     altKey?: boolean;
 }, onError?: (message: string) => void): boolean;
+/** Q (no modifiers) toggles Quick Mask mode. Returns true when the key was used. */
+export declare function handleQuickMaskKey(controller: ImageEditorController, e: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}): boolean;

package/dist/image-editor/selection/gesture.d.ts

@@ -76,3 +76,10 @@ export declare function handleSelectionShortcut(controller: ImageEditorControlle
     shiftKey?: boolean;
     altKey?: boolean;
 }, onError?: (message: string) => void): boolean;
+/** Q (no modifiers) toggles Quick Mask mode. Returns true when the key was used. */
+export declare function handleQuickMaskKey(controller: ImageEditorController, e: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}): boolean;

package/dist/image-editor/selection/index.d.cts

@@ -9,3 +9,4 @@ export * from './tool-options.cjs';
 export * from './gesture.cjs';
 export * from './segmentation.cjs';
 export * from './stroke.cjs';
+export * from './channels.cjs';

package/dist/image-editor/selection/index.d.ts

@@ -9,3 +9,4 @@ export * from './tool-options.js';
 export * from './gesture.js';
 export * from './segmentation.js';
 export * from './stroke.js';
+export * from './channels.js';

package/dist/image-editor/selection/overlay.d.cts

@@ -10,6 +10,8 @@ export interface QuickMaskStyle {
     color?: readonly [number, number, number];
     /** 0..1 (default 0.5): opacity over fully unselected pixels. */
     opacity?: number;
+    /** Tint the unselected area (`masked`, default) or the selected area (`selected`). */
+    indicates?: 'masked' | 'selected';
 }
 /**
  * Quick Mask view: RGBA pixels (natural image size) tinting the *unselected* area, so the

package/dist/image-editor/selection/overlay.d.ts

@@ -10,6 +10,8 @@ export interface QuickMaskStyle {
     color?: readonly [number, number, number];
     /** 0..1 (default 0.5): opacity over fully unselected pixels. */
     opacity?: number;
+    /** Tint the unselected area (`masked`, default) or the selected area (`selected`). */
+    indicates?: 'masked' | 'selected';
 }
 /**
  * Quick Mask view: RGBA pixels (natural image size) tinting the *unselected* area, so the

package/dist/image-editor/tools.d.cts

@@ -27,7 +27,9 @@ export interface ImageEditorToolProviderOptions {
  *   `select_rect`, `select_ellipse`, `select_polygon`, `select_line`, `magic_wand`,
  *   `select_color_range`, `grow_selection`, `select_similar`, `reselect`,
  *   `select_layer_transparency`, `stroke_selection`, `crop_to_selection`, `content_aware_fill`,
- *   `copy_pixels`, `cut_pixels`, `paste_pixels`,
+ *   `copy_pixels`, `cut_pixels`, `paste_pixels`, alpha channels (`list_channels`, `save_selection`,
+ *   `load_selection_from_channel`, `set_channel_properties`, `duplicate_channel`,
+ *   `delete_channel`), `set_quick_mask`,
  *   `load_selection_from_image`, `load_selection_from_mask`, `set_selection_display`,
  *   `modify_selection`, `refine_selection`, `apply_selection_as_mask` and the deprecated
  *   `select_region` / `select_by_color` (see `createImageSelectionTools`).

package/dist/image-editor/tools.d.ts

@@ -27,7 +27,9 @@ export interface ImageEditorToolProviderOptions {
  *   `select_rect`, `select_ellipse`, `select_polygon`, `select_line`, `magic_wand`,
  *   `select_color_range`, `grow_selection`, `select_similar`, `reselect`,
  *   `select_layer_transparency`, `stroke_selection`, `crop_to_selection`, `content_aware_fill`,
- *   `copy_pixels`, `cut_pixels`, `paste_pixels`,
+ *   `copy_pixels`, `cut_pixels`, `paste_pixels`, alpha channels (`list_channels`, `save_selection`,
+ *   `load_selection_from_channel`, `set_channel_properties`, `duplicate_channel`,
+ *   `delete_channel`), `set_quick_mask`,
  *   `load_selection_from_image`, `load_selection_from_mask`, `set_selection_display`,
  *   `modify_selection`, `refine_selection`, `apply_selection_as_mask` and the deprecated
  *   `select_region` / `select_by_color` (see `createImageSelectionTools`).

package/dist/image-editor/types.d.cts

@@ -2,6 +2,7 @@ import type { GlobalLight } from '../raster/effects/model.cjs';
 import type { EffectPattern } from '../raster/effects/patterns.cjs';
 import type { BlendMode } from './blend.cjs';
 import type { SelectionMask, SerializedSelection } from './selection/mask.cjs';
+import type { AlphaChannel, SerializedAlphaChannel } from './selection/channels.cjs';
 import type { ImageLayer, LayerTarget } from './layers/model.cjs';
 import type { SerializedLayeredImageEditorState } from './layers/serialize.cjs';
 import type { PaintOptions } from './controller.cjs';
@@ -313,6 +314,13 @@ export interface ImageEditorState {
     quickMask?: boolean;
     /** How the canvas shows the selection (view state; `quickMask` mirrors `'quickMask'`). */
     selectionDisplay?: 'ants' | 'quickMask' | 'none';
+    /**
+     * Quick Mask mode: painting and fills without a layer edit the selection itself (white
+     * selects, black deselects), shown as a tint. View state; the edits are undo steps.
+     */
+    quickMaskEditing?: boolean;
+    /** Alpha channels: saved selections kept with the document, recorded in undo history. */
+    channels?: AlphaChannel[];
     /**
      * The layer stack, bottom to top. Opening an image gives one pixel layer, "Background", whose
      * pixels are the source image. Layers are immutable: compare them by identity.
@@ -380,6 +388,8 @@ export interface LegacySerializedImageEditorState {
     annotations: Annotation[];
     /** The active selection, run-length encoded. Missing when nothing is selected. */
     selection?: SerializedSelection;
+    /** Alpha channels (saved selections), run-length encoded. */
+    channels?: SerializedAlphaChannel[];
 }
 /**
  * A stored editor state: the document-level schema (v1 / v2) or the layered schema (v3, see

package/dist/image-editor/types.d.ts

@@ -2,6 +2,7 @@ import type { GlobalLight } from '../raster/effects/model.js';
 import type { EffectPattern } from '../raster/effects/patterns.js';
 import type { BlendMode } from './blend.js';
 import type { SelectionMask, SerializedSelection } from './selection/mask.js';
+import type { AlphaChannel, SerializedAlphaChannel } from './selection/channels.js';
 import type { ImageLayer, LayerTarget } from './layers/model.js';
 import type { SerializedLayeredImageEditorState } from './layers/serialize.js';
 import type { PaintOptions } from './controller.js';
@@ -313,6 +314,13 @@ export interface ImageEditorState {
     quickMask?: boolean;
     /** How the canvas shows the selection (view state; `quickMask` mirrors `'quickMask'`). */
     selectionDisplay?: 'ants' | 'quickMask' | 'none';
+    /**
+     * Quick Mask mode: painting and fills without a layer edit the selection itself (white
+     * selects, black deselects), shown as a tint. View state; the edits are undo steps.
+     */
+    quickMaskEditing?: boolean;
+    /** Alpha channels: saved selections kept with the document, recorded in undo history. */
+    channels?: AlphaChannel[];
     /**
      * The layer stack, bottom to top. Opening an image gives one pixel layer, "Background", whose
      * pixels are the source image. Layers are immutable: compare them by identity.
@@ -380,6 +388,8 @@ export interface LegacySerializedImageEditorState {
     annotations: Annotation[];
     /** The active selection, run-length encoded. Missing when nothing is selected. */
     selection?: SerializedSelection;
+    /** Alpha channels (saved selections), run-length encoded. */
+    channels?: SerializedAlphaChannel[];
 }
 /**
  * A stored editor state: the document-level schema (v1 / v2) or the layered schema (v3, see

package/dist/paint-editor/index.cjs

@@ -7,7 +7,7 @@ var _chunkZ64NRDEHcjs = require('../chunk-Z64NRDEH.cjs');
 
 
 
-var _chunkC6TRAAG4cjs = require('../chunk-C6TRAAG4.cjs');
+var _chunkX2KQQZBTcjs = require('../chunk-X2KQQZBT.cjs');
 require('../chunk-A2IS7EHE.cjs');
 
 
@@ -1653,11 +1653,11 @@ function header(state, options) {
   return out;
 }
 function serializePaintDocument(state, options = {}) {
-  const { layers, assets } = _chunkC6TRAAG4cjs.serializeLayers.call(void 0, state.layers);
+  const { layers, assets } = _chunkX2KQQZBTcjs.serializeLayers.call(void 0, state.layers);
   return { ...header(state, options), layers, assets };
 }
 async function serializePaintDocumentExternal(state, store, options = {}) {
-  const { layers, assets } = await _chunkC6TRAAG4cjs.serializeLayersExternal.call(void 0, state.layers, store);
+  const { layers, assets } = await _chunkX2KQQZBTcjs.serializeLayersExternal.call(void 0, state.layers, store);
   return { ...header(state, options), layers, assets };
 }
 function paintLayersOnly(layers, problems) {
@@ -1694,7 +1694,7 @@ function deserializePaintDocument(raw) {
   const canvas = normalizeCanvas({ width: r.width, height: r.height, dpi: _nullishCoalesce(r.dpi, () => ( void 0)) });
   const paper = _chunkYQ5C5BVKcjs.normalizePaper.call(void 0, _nullishCoalesce(r.paper, () => ( {})));
   const assets = r.assets && typeof r.assets === "object" ? r.assets : {};
-  const layers = paintLayersOnly(_chunkC6TRAAG4cjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
+  const layers = paintLayersOnly(_chunkX2KQQZBTcjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && _chunkHGTDMKNEcjs.findLayer.call(void 0, layers, wanted) ? wanted : _nullishCoalesce(_optionalChain([_chunkHGTDMKNEcjs.flattenLayers.call(void 0, layers), 'access', _70 => _70.filter, 'call', _71 => _71((l) => l.type === "pixel"), 'access', _72 => _72.pop, 'call', _73 => _73(), 'optionalAccess', _74 => _74.id]), () => ( null));
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
@@ -1710,7 +1710,7 @@ async function deserializePaintDocumentAsync(raw, store) {
   if (!raw || typeof raw !== "object") throw new Error("Not a paint document: expected a JSON object.");
   const r = raw;
   const problems = [];
-  const assets = await _chunkC6TRAAG4cjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
+  const assets = await _chunkX2KQQZBTcjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
   const loaded = deserializePaintDocument({ ...r, assets });
   return { ...loaded, problems: [...problems, ...loaded.problems] };
 }
@@ -5409,7 +5409,7 @@ var PaintEditorController = (_class10 = class _PaintEditorController {
       return next.type === "group" ? { ...next, children: toStandard(next.children) } : next;
     });
     const layers = toStandard(dried);
-    const result = _chunkC6TRAAG4cjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
+    const result = _chunkX2KQQZBTcjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
     for (const [mode, names] of changed) {
       const label = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _271 => _271.find, 'call', _272 => _272((m) => m.id === mode), 'optionalAccess', _273 => _273.label]), () => ( mode));
       const std = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _274 => _274.find, 'call', _275 => _275((m) => m.id === _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)), 'optionalAccess', _276 => _276.label]), () => ( _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)));

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-GYYSPMVU.js";
+} from "../chunk-FW7N64XK.js";
 import "../chunk-3CI7FRMK.js";
 import {
   EffectRendererPool

package/package.json

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

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

@@ -241,6 +241,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 +396,12 @@ 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. |
+| `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-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,10 @@ 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.
+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.
@@ -151,6 +157,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 +176,10 @@ 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
+- `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)