@pixerate/editor 0.185.0 → 0.187.0

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

@@ -9,6 +9,7 @@ import { type SelectionModifyOp } from './selection/modify.cjs';
 import { type SegmentationProvider } from './selection/segmentation.cjs';
 import { type RefineEdgeParams } from './selection/refine.cjs';
 import { type LayerMaskProps } from './selection/layer-mask.cjs';
+import { type AlphaChannel } from './selection/channels.cjs';
 import type { AdjustmentLayerMask } from './types.cjs';
 import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer, type ImageEffectAnimation } from './layers/model.cjs';
 import { type TextLayout, type TextShaper } from './layers/text.cjs';
@@ -112,6 +113,12 @@ export interface SelectionCommandOptions {
 }
 /** How the canvas shows the selection: marching ants, a Quick Mask tint, or not at all. */
 export type SelectionDisplay = 'ants' | 'quickMask' | 'none';
+/** What `exportMaskImage` writes: the selection, an alpha channel or a layer's painted mask. */
+export type MaskImageSource = 'selection' | {
+    channelId: string;
+} | {
+    layerId: string;
+};
 /** Where an AI result goes (see `applyInpaintedImage`, `applyBackgroundRemovedImage`). */
 export interface AIResultOptions {
     /** `new-layer`: a new layer (inpainting) or a mask (background removal); `replace`: the Background's pixels. Default: by `isMultiLayer`. */
@@ -354,6 +361,8 @@ export interface FillOptions {
     /** Limit to the selection when there is one (default true). */
     useSelection?: boolean;
 }
+/** The `layerId` paint results report for Quick Mask edits (the selection, not a layer). */
+export declare const QUICK_MASK_TARGET = "quick-mask";
 /** Edit › Stroke (see `strokeSelection`). */
 export interface StrokeSelectionOptions extends Omit<FillOptions, 'useSelection'> {
     /** Width of the band in pixels (0 < width ≤ 250). */
@@ -1445,6 +1454,29 @@ export declare class ImageEditorController {
         threshold?: number;
         mode?: SelectionMode;
     }): Promise<SelectionMask | null>;
+    /**
+     * Loads a mask image (a data URL / URL or RGBA pixels, any size, resampled) into a new alpha
+     * channel, read like `loadSelectionFromImage`. The selection does not change. One undo step.
+     */
+    loadChannelFromImage(source: string | PixelBuffer, options?: {
+        name?: string;
+        channel?: SelectionChannel;
+        invert?: boolean;
+        threshold?: number;
+    }): Promise<AlphaChannel>;
+    /**
+     * A full-size greyscale PNG (white = selected / revealed) of the selection, an alpha channel or
+     * a layer's painted mask, as a data URL; `invert` swaps black and white, `maxSide` scales it
+     * down. Encoded in code, so it works without a canvas. Throws when the source is missing.
+     */
+    exportMaskImage(source: MaskImageSource, options?: {
+        invert?: boolean;
+        maxSide?: number;
+    }): {
+        width: number;
+        height: number;
+        dataUrl: string;
+    };
     /** A mask image (data URL / URL, or pixels as they are) as RGBA pixels. */
     private decodeMaskImage;
     /**
@@ -1474,6 +1506,61 @@ export declare class ImageEditorController {
      * it (the selection still applies). View state: no undo step, not saved.
      */
     setSelectionDisplay(display: SelectionDisplay): void;
+    /** The alpha channels (saved selections), in panel order. */
+    getChannels(): readonly AlphaChannel[];
+    getChannel(id: string): AlphaChannel | null;
+    private requireChannel;
+    private setChannels;
+    private newChannelId;
+    /**
+     * Select › Save Selection: a new alpha channel (`name`, default "Alpha n") holding the
+     * selection, or with `channelId` the selection combined into that channel by `mode` (replace,
+     * add, subtract, intersect). One undo step. Throws without a selection.
+     */
+    saveSelection(options?: {
+        channelId?: string;
+        name?: string;
+        mode?: SelectionMode;
+    }): AlphaChannel;
+    /** Appends a new channel holding `mask` (canvas-sized) as one undo step. */
+    private addChannel;
+    /**
+     * Select › Load Selection from an alpha channel (inverted with `invert`), combined with the
+     * selection by `mode`. One undo step.
+     */
+    loadSelectionFromChannel(id: string, options?: {
+        mode?: SelectionMode;
+        invert?: boolean;
+    }): boolean;
+    /** Changes a channel's name, overlay colour, opacity, what it indicates or visibility (one undo step). */
+    setChannelProperties(id: string, props: Partial<Pick<AlphaChannel, 'name' | 'color' | 'opacity' | 'indicates' | 'visible'>>): AlphaChannel;
+    /** Deletes an alpha channel (one undo step). */
+    deleteChannel(id: string): void;
+    /** Duplicates an alpha channel just after it (one undo step). Returns the copy. */
+    duplicateChannel(id: string, name?: string): AlphaChannel;
+    /** Channel summaries (no pixels) for panels and agents. */
+    describeChannels(): {
+        bounds: CropBox | null;
+        percent: number;
+        id: string;
+        name: string;
+        color: string;
+        opacity: number;
+        indicates: "masked" | "selected";
+        visible: boolean;
+    }[];
+    /** Whether Quick Mask mode is on (painting edits the selection). */
+    get quickMaskEditing(): boolean;
+    /**
+     * Quick Mask mode (Q): on, the selection shows as a tint and painting, fills and strokes that
+     * name no layer edit the selection itself (white selects, black deselects, grey partly);
+     * off, it shows as marching ants again. View state: no undo step (the edits are).
+     */
+    setQuickMaskMode(on: boolean): void;
+    /** The selection as a 1-channel surface to paint in Quick Mask mode. */
+    private quickMaskSurface;
+    /** The selection a painted Quick Mask surface stands for (`rects` changed since `base`). */
+    private selectionFromSurface;
     private maskFromSelection;
     /**
      * Adds the selection as the layer's mask (Reveal Selection), replacing any mask, as one undo
@@ -1490,6 +1577,8 @@ export declare class ImageEditorController {
      * with `invert`. False without a painted mask (a depth mask is computed, not painted).
      */
     selectionFromLayerMask(layerId: string, mode?: SelectionMode, invert?: boolean): boolean;
+    /** A layer's painted mask over the canvas as a selection mask; null without one (or for a depth mask). */
+    private layerMaskCoverage;
     /**
      * Histogram of the last rendered preview (after adjustments and layers, before annotations),
      * or `null` before the first render or without canvas pixel access.

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

@@ -9,6 +9,7 @@ import { type SelectionModifyOp } from './selection/modify.js';
 import { type SegmentationProvider } from './selection/segmentation.js';
 import { type RefineEdgeParams } from './selection/refine.js';
 import { type LayerMaskProps } from './selection/layer-mask.js';
+import { type AlphaChannel } from './selection/channels.js';
 import type { AdjustmentLayerMask } from './types.js';
 import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer, type ImageEffectAnimation } from './layers/model.js';
 import { type TextLayout, type TextShaper } from './layers/text.js';
@@ -112,6 +113,12 @@ export interface SelectionCommandOptions {
 }
 /** How the canvas shows the selection: marching ants, a Quick Mask tint, or not at all. */
 export type SelectionDisplay = 'ants' | 'quickMask' | 'none';
+/** What `exportMaskImage` writes: the selection, an alpha channel or a layer's painted mask. */
+export type MaskImageSource = 'selection' | {
+    channelId: string;
+} | {
+    layerId: string;
+};
 /** Where an AI result goes (see `applyInpaintedImage`, `applyBackgroundRemovedImage`). */
 export interface AIResultOptions {
     /** `new-layer`: a new layer (inpainting) or a mask (background removal); `replace`: the Background's pixels. Default: by `isMultiLayer`. */
@@ -354,6 +361,8 @@ export interface FillOptions {
     /** Limit to the selection when there is one (default true). */
     useSelection?: boolean;
 }
+/** The `layerId` paint results report for Quick Mask edits (the selection, not a layer). */
+export declare const QUICK_MASK_TARGET = "quick-mask";
 /** Edit › Stroke (see `strokeSelection`). */
 export interface StrokeSelectionOptions extends Omit<FillOptions, 'useSelection'> {
     /** Width of the band in pixels (0 < width ≤ 250). */
@@ -1445,6 +1454,29 @@ export declare class ImageEditorController {
         threshold?: number;
         mode?: SelectionMode;
     }): Promise<SelectionMask | null>;
+    /**
+     * Loads a mask image (a data URL / URL or RGBA pixels, any size, resampled) into a new alpha
+     * channel, read like `loadSelectionFromImage`. The selection does not change. One undo step.
+     */
+    loadChannelFromImage(source: string | PixelBuffer, options?: {
+        name?: string;
+        channel?: SelectionChannel;
+        invert?: boolean;
+        threshold?: number;
+    }): Promise<AlphaChannel>;
+    /**
+     * A full-size greyscale PNG (white = selected / revealed) of the selection, an alpha channel or
+     * a layer's painted mask, as a data URL; `invert` swaps black and white, `maxSide` scales it
+     * down. Encoded in code, so it works without a canvas. Throws when the source is missing.
+     */
+    exportMaskImage(source: MaskImageSource, options?: {
+        invert?: boolean;
+        maxSide?: number;
+    }): {
+        width: number;
+        height: number;
+        dataUrl: string;
+    };
     /** A mask image (data URL / URL, or pixels as they are) as RGBA pixels. */
     private decodeMaskImage;
     /**
@@ -1474,6 +1506,61 @@ export declare class ImageEditorController {
      * it (the selection still applies). View state: no undo step, not saved.
      */
     setSelectionDisplay(display: SelectionDisplay): void;
+    /** The alpha channels (saved selections), in panel order. */
+    getChannels(): readonly AlphaChannel[];
+    getChannel(id: string): AlphaChannel | null;
+    private requireChannel;
+    private setChannels;
+    private newChannelId;
+    /**
+     * Select › Save Selection: a new alpha channel (`name`, default "Alpha n") holding the
+     * selection, or with `channelId` the selection combined into that channel by `mode` (replace,
+     * add, subtract, intersect). One undo step. Throws without a selection.
+     */
+    saveSelection(options?: {
+        channelId?: string;
+        name?: string;
+        mode?: SelectionMode;
+    }): AlphaChannel;
+    /** Appends a new channel holding `mask` (canvas-sized) as one undo step. */
+    private addChannel;
+    /**
+     * Select › Load Selection from an alpha channel (inverted with `invert`), combined with the
+     * selection by `mode`. One undo step.
+     */
+    loadSelectionFromChannel(id: string, options?: {
+        mode?: SelectionMode;
+        invert?: boolean;
+    }): boolean;
+    /** Changes a channel's name, overlay colour, opacity, what it indicates or visibility (one undo step). */
+    setChannelProperties(id: string, props: Partial<Pick<AlphaChannel, 'name' | 'color' | 'opacity' | 'indicates' | 'visible'>>): AlphaChannel;
+    /** Deletes an alpha channel (one undo step). */
+    deleteChannel(id: string): void;
+    /** Duplicates an alpha channel just after it (one undo step). Returns the copy. */
+    duplicateChannel(id: string, name?: string): AlphaChannel;
+    /** Channel summaries (no pixels) for panels and agents. */
+    describeChannels(): {
+        bounds: CropBox | null;
+        percent: number;
+        id: string;
+        name: string;
+        color: string;
+        opacity: number;
+        indicates: "masked" | "selected";
+        visible: boolean;
+    }[];
+    /** Whether Quick Mask mode is on (painting edits the selection). */
+    get quickMaskEditing(): boolean;
+    /**
+     * Quick Mask mode (Q): on, the selection shows as a tint and painting, fills and strokes that
+     * name no layer edit the selection itself (white selects, black deselects, grey partly);
+     * off, it shows as marching ants again. View state: no undo step (the edits are).
+     */
+    setQuickMaskMode(on: boolean): void;
+    /** The selection as a 1-channel surface to paint in Quick Mask mode. */
+    private quickMaskSurface;
+    /** The selection a painted Quick Mask surface stands for (`rects` changed since `base`). */
+    private selectionFromSurface;
     private maskFromSelection;
     /**
      * Adds the selection as the layer's mask (Reveal Selection), replacing any mask, as one undo
@@ -1490,6 +1577,8 @@ export declare class ImageEditorController {
      * with `invert`. False without a painted mask (a depth mask is computed, not painted).
      */
     selectionFromLayerMask(layerId: string, mode?: SelectionMode, invert?: boolean): boolean;
+    /** A layer's painted mask over the canvas as a selection mask; null without one (or for a depth mask). */
+    private layerMaskCoverage;
     /**
      * Histogram of the last rendered preview (after adjustments and layers, before annotations),
      * or `null` before the first render or without canvas pixel access.