@pixerate/editor 0.185.0 → 0.187.0

package/dist/image-editor/index.js

@@ -370,7 +370,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-GYYSPMVU.js";
+} from "../chunk-FW7N64XK.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -939,12 +939,13 @@ function selectionOutline(mask, threshold = 128) {
 function quickMaskPixels(mask, style = {}) {
   const [r, g, b] = style.color ?? [255, 0, 0];
   const k = Math.min(1, Math.max(0, style.opacity ?? 0.5));
+  const selected = style.indicates === "selected";
   const out = new Uint8ClampedArray(mask.data.length * 4);
   for (let i = 0, p = 0; i < mask.data.length; i++, p += 4) {
     out[p] = r;
     out[p + 1] = g;
     out[p + 2] = b;
-    out[p + 3] = Math.round((255 - mask.data[i]) * k);
+    out[p + 3] = Math.round((selected ? mask.data[i] : 255 - mask.data[i]) * k);
   }
   return out;
 }
@@ -1363,14 +1364,30 @@ var ImageEditorRenderer = class {
       ctx.restore();
     }
     const display = options.selectionDisplay ?? state.selectionDisplay ?? (state.quickMask ? "quickMask" : "ants");
-    if (state.selection?.bounds && display !== "none" || options.draftSelectionPath?.length) {
+    const shownChannels = (state.channels ?? []).filter((c) => c.visible);
+    if (shownChannels.length) {
       ctx.save();
       try {
         applyImageProjectionToContext(ctx, projection);
         ctx.beginPath();
         ctx.rect(region.x, region.y, region.width, region.height);
         ctx.clip();
-        if (state.selection?.bounds && display === "quickMask") this.drawQuickMask(ctx, state.selection);
+        for (const c of shownChannels) this.drawMaskOverlay(ctx, c.mask, { color: hexRgb(c.color), opacity: c.opacity, indicates: c.indicates });
+      } catch {
+      }
+      ctx.restore();
+    }
+    const { width: iw, height: ih } = state.imageDimensions;
+    const quickMaskSel = display === "quickMask" && state.quickMaskEditing && !state.selection?.bounds ? this.emptyMask(Math.round(iw), Math.round(ih)) : null;
+    if (state.selection?.bounds && display !== "none" || quickMaskSel || options.draftSelectionPath?.length) {
+      ctx.save();
+      try {
+        applyImageProjectionToContext(ctx, projection);
+        ctx.beginPath();
+        ctx.rect(region.x, region.y, region.width, region.height);
+        ctx.clip();
+        if (quickMaskSel) this.drawQuickMask(ctx, quickMaskSel);
+        else if (state.selection?.bounds && display === "quickMask") this.drawQuickMask(ctx, state.selection);
         else if (state.selection?.bounds && display === "ants") this.drawAnts(ctx, state.selection, projection.scale / u, options.antsOffset ?? 0);
         if (options.draftSelectionPath?.length) this.drawDraftPath(ctx, options.draftSelectionPath, projection.scale / u);
       } catch {
@@ -1776,6 +1793,31 @@ var ImageEditorRenderer = class {
   }
   quickMaskCache = /* @__PURE__ */ new WeakMap();
   outlineCache = /* @__PURE__ */ new WeakMap();
+  emptyMaskCache = null;
+  /** An empty selection of the image's size (Quick Mask mode with nothing selected). */
+  emptyMask(width, height) {
+    const m = this.emptyMaskCache;
+    if (m && m.width === width && m.height === height) return m;
+    this.emptyMaskCache = createSelectionMask(Math.max(1, width), Math.max(1, height));
+    return this.emptyMaskCache;
+  }
+  overlayCache = /* @__PURE__ */ new WeakMap();
+  /** A channel's tint (colour, opacity, masked or selected area), drawn in natural image space. */
+  drawMaskOverlay(ctx, mask, style) {
+    const key = `${style.color?.join(",")}|${style.opacity}|${style.indicates}`;
+    let cached = this.overlayCache.get(mask);
+    if (!cached || cached.key !== key) {
+      const canvas = this.createCanvas(mask.width, mask.height);
+      const mctx = canvas.getContext("2d");
+      if (!mctx || typeof mctx.createImageData !== "function") return;
+      const img = mctx.createImageData(mask.width, mask.height);
+      img.data.set(quickMaskPixels(mask, style));
+      mctx.putImageData(img, 0, 0);
+      cached = { key, canvas };
+      this.overlayCache.set(mask, cached);
+    }
+    ctx.drawImage(cached.canvas, 0, 0, mask.width, mask.height);
+  }
   /** Rubylith over the unselected area, drawn in natural image space. */
   drawQuickMask(ctx, selection) {
     let canvas = this.quickMaskCache.get(selection);
@@ -2320,6 +2362,12 @@ function removeAnnotationLayers(layers) {
   }
   return out;
 }
+function hexRgb(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex);
+  if (!m) return [255, 0, 0];
+  const v = parseInt(m[1], 16);
+  return [v >> 16 & 255, v >> 8 & 255, v & 255];
+}
 
 // src/image-editor/layers/shape-type-ui.ts
 var DEFAULT_SHAPE_TOOL_OPTIONS = {
@@ -3479,6 +3527,57 @@ function selectionRing(sel, width, location) {
   return createSelectionMask(sel.width, sel.height, out);
 }
 
+// src/image-editor/selection/channels.ts
+var DEFAULT_CHANNEL_COLOR = "#ff0000";
+function describeChannel(channel) {
+  const { mask, ...rest } = channel;
+  let sum = 0;
+  for (let i = 0; i < mask.data.length; i++) sum += mask.data[i];
+  const percent = Math.round(sum / 255 / Math.max(1, mask.data.length) * 1e4) / 100;
+  return { ...rest, bounds: mask.bounds, percent };
+}
+function serializeChannels(channels) {
+  return channels.map((c) => ({ ...c, mask: serializeSelection(c.mask) }));
+}
+function deserializeChannels(value, size, problems = []) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const raw of value) {
+    const v = raw;
+    try {
+      const mask = deserializeSelection(v.mask);
+      if (mask.width !== size.width || mask.height !== size.height) throw new Error("the channel is a different size from the canvas");
+      out.push({
+        id: typeof v.id === "string" && v.id ? v.id : `ch_${out.length + 1}`,
+        name: typeof v.name === "string" && v.name.trim() ? v.name : `Alpha ${out.length + 1}`,
+        mask,
+        color: typeof v.color === "string" && /^#[0-9a-f]{6}$/i.test(v.color) ? v.color : DEFAULT_CHANNEL_COLOR,
+        opacity: typeof v.opacity === "number" && v.opacity >= 0 && v.opacity <= 1 ? v.opacity : 0.5,
+        indicates: v.indicates === "selected" ? "selected" : "masked",
+        visible: v.visible === true
+      });
+    } catch (err) {
+      problems.push(`Alpha channel "${String(v?.name ?? "?")}" could not be read: ${err instanceof Error ? err.message : String(err)}.`);
+    }
+  }
+  return out;
+}
+function channelThumbnail(channel, maxSide = 64) {
+  const { width: w, height: h, data } = channel.mask;
+  const k = Math.min(1, maxSide / Math.max(w, h));
+  const tw = Math.max(1, Math.round(w * k));
+  const th = Math.max(1, Math.round(h * k));
+  const out = new Uint8ClampedArray(tw * th * 4);
+  for (let y = 0; y < th; y++) {
+    const sy = Math.min(h - 1, Math.floor((y + 0.5) / k));
+    for (let x = 0; x < tw; x++) {
+      const v = data[sy * w + Math.min(w - 1, Math.floor((x + 0.5) / k))];
+      out.set([v, v, v, 255], (y * tw + x) * 4);
+    }
+  }
+  return { width: tw, height: th, data: out };
+}
+
 // src/image-editor/effect-layers.ts
 function hasLayersBelow(layers, id) {
   const all = flattenLayers(layers);
@@ -4389,6 +4488,7 @@ var IMAGE_EDITOR_SCHEMA_VERSION = LAYERED_SCHEMA_VERSION;
 var RETOUCH_TOOLS = ["clone", "heal", "spot-heal", "smudge", "dodge", "burn", "sponge", "blur", "sharpen", "history"];
 var isRetouchTool = (tool) => RETOUCH_TOOLS.includes(tool);
 var STROKE_TOOLS = ["brush", "eraser", "mixer", ...RETOUCH_TOOLS];
+var QUICK_MASK_TARGET = "quick-mask";
 var PASTE_MODES = ["new-layer", "in-place", "into", "outside"];
 function paintCoverageInto(base, coverage, apply, rects, depth = null) {
   const tiles = new Map(base.tiles);
@@ -4899,6 +4999,10 @@ var ImageEditorController = class {
       } catch {
       }
     }
+    if (options.initialState?.channels) {
+      const channels = deserializeChannels(options.initialState.channels, this.naturalSize, this.lastLoadProblems);
+      if (channels.length) this.state.channels = channels;
+    }
     this.initialSnapshot = this.captureHistoryEntry();
     if (typeof options.image === "string") {
       this.loadImage(options.image);
@@ -5279,6 +5383,7 @@ var ImageEditorController = class {
       transform: { ...s.transform },
       outputOpacity: s.outputOpacity,
       selection: s.selection ?? null,
+      ...s.channels?.length ? { channels: s.channels } : {},
       source: {
         sourceUrl: s.sourceUrl,
         element: this.imageElement,
@@ -5314,6 +5419,8 @@ var ImageEditorController = class {
     if (entry.colorMode) s.colorMode = entry.colorMode;
     else delete s.colorMode;
     s.selection = entry.selection;
+    if (entry.channels?.length) s.channels = entry.channels;
+    else delete s.channels;
     if (this.imageElement !== entry.source.element && !this.samplePixelsOverride) this.samplePixels = null;
     this.imageElement = entry.source.element;
     s.sourceUrl = entry.source.sourceUrl;
@@ -7025,6 +7132,12 @@ var ImageEditorController = class {
   }
   /** Resolves and validates what a stroke, fill or clear paints into. */
   paintTarget(layerId, channel, action) {
+    if (channel === "quick-mask" || channel === void 0 && layerId === void 0 && this.state.quickMaskEditing) {
+      if (!this.state.quickMaskEditing) {
+        throw new LayerOperationError(`Quick Mask is off; turn it on (set_quick_mask) to ${action} on the selection, or target a layer.`, `Turn on Quick Mask (Q) to ${action} on the selection.`);
+      }
+      return { id: QUICK_MASK_TARGET, layer: null, channel: "quick-mask", offset: { x: 0, y: 0 }, surface: this.quickMaskSurface(), lockTransparency: false };
+    }
     const id = layerId ?? this.state.activeLayerId;
     if (!id) throw new LayerOperationError(`No layer given and none is active; pass layerId (see list_layers) to ${action}.`, `Pick a layer to ${action} on in the Layers panel.`);
     const layer = requireLayer(this.state.layers, id).layer;
@@ -7093,10 +7206,11 @@ var ImageEditorController = class {
       opacity: brush.opacity,
       blend: target.channel !== "pixels" ? "normal" : brush.blend,
       lockTransparency: target.lockTransparency,
-      selection: this.state.selection?.bounds ? this.state.selection : null,
+      // In Quick Mask mode the selection is what is painted, so it does not limit the stroke.
+      selection: target.channel !== "quick-mask" && this.state.selection?.bounds ? this.state.selection : null,
       offset: target.offset
     };
-    const depth = target.channel !== "filter-mask" && this.bitDepth !== 8 ? this.bitDepth : null;
+    const depth = target.channel !== "filter-mask" && target.channel !== "quick-mask" && this.bitDepth !== 8 ? this.bitDepth : null;
     if (tool === "mixer") return new PaintStrokeSession(this, target, this.mixerStroke(init, brush), apply, depth);
     if (isRetouchTool(tool)) return new PaintStrokeSession(this, target, this.retouchStroke(tool, init, brush, target, apply), apply, depth);
     const gradient = tool === "brush" && strokePaint?.type === "gradient" ? resolvePaintGradient(strokePaint, { paint: toHex(color), secondary: toHex(background) }) : null;
@@ -7261,12 +7375,19 @@ var ImageEditorController = class {
   }
   /** @internal Shows a stroke's live surface (no history). */
   _strokeUpdate(layerId, channel, surface, rects) {
+    if (channel === "quick-mask") {
+      this.state.selection = this.selectionFromSurface(surface, this.state.selection ?? null, rects);
+      this.notify();
+      return;
+    }
     this.state.layers = mapLayer(this.state.layers, layerId, (l) => this.withSurface(l, channel, surface));
     this.notify(channel === "filter-mask" ? void 0 : rects);
   }
   /** @internal Commits a finished stroke as one undo step (`before` is the pre-stroke state). */
   _strokeCommit(before, layerId, channel, surface) {
-    if (surface) {
+    if (channel === "quick-mask") {
+      this.state.selection = surface ? this.selectionFromSurface(surface) : before.selection;
+    } else if (surface) {
       const prev = before.layers;
       this.state.layers = mapLayer(this.state.layers, layerId, (l) => this.withSurface(l, channel, surface));
       if (this.bitDepth !== 8) this.state.layers = keepDeepLayers(prev, this.state.layers);
@@ -7482,7 +7603,8 @@ var ImageEditorController = class {
     const opacity = options.opacity ?? 1;
     if (!(opacity >= 0 && opacity <= 1)) throw new LayerOperationError("opacity must be from 0 to 1.");
     const blend = parseBlend(options.blend) ?? "normal";
-    const sel = coverageMask ?? (options.useSelection !== false && this.state.selection?.bounds ? this.state.selection : null);
+    const quickMask = target.channel === "quick-mask";
+    const sel = coverageMask ?? (!quickMask && options.useSelection !== false && this.state.selection?.bounds ? this.state.selection : null);
     const region = sel?.bounds ?? { x: 0, y: 0, width, height };
     const coverage = new CoverageMap();
     const ones = new Float32Array(region.width * region.height);
@@ -7508,8 +7630,14 @@ var ImageEditorController = class {
       selection: null,
       offset: target.offset
     };
-    const depth = target.channel !== "filter-mask" && this.bitDepth !== 8 ? this.bitDepth : null;
+    const depth = target.channel !== "filter-mask" && target.channel !== "quick-mask" && this.bitDepth !== 8 ? this.bitDepth : null;
     const surface = paintCoverageInto(target.surface, coverage, apply, [region], depth);
+    if (quickMask) {
+      this.recordHistory();
+      this.state.selection = this.selectionFromSurface(surface);
+      this.notify();
+      return { layerId: target.id, channel: target.channel, bounds: region, dabs: 0 };
+    }
     const next = mapLayer(this.state.layers, target.id, (l) => this.withSurface(l, target.channel, surface));
     this.commitLayers(next);
     return { layerId: target.id, channel: target.channel, bounds: region, dabs: 0 };
@@ -8092,6 +8220,39 @@ var ImageEditorController = class {
     this.setSelection(selectionFromPixels(pixels, options), options.mode ?? "replace");
     return this.getSelection();
   }
+  /**
+   * 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.
+   */
+  async loadChannelFromImage(source, options = {}) {
+    const mask = selectionFromPixels(await this.decodeMaskImage(source), options);
+    const { width, height } = this.naturalSize;
+    return this.addChannel(mask.width === width && mask.height === height ? mask : resizeSelection(mask, width, height), options.name);
+  }
+  /**
+   * 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, options = {}) {
+    let mask;
+    if (source === "selection") {
+      const sel = this.state.selection;
+      if (!sel?.bounds) throw new LayerOperationError("Nothing is selected; select first, or export a channel or a layer mask.");
+      mask = sel;
+    } else if ("channelId" in source) {
+      mask = this.requireChannel(source.channelId).mask;
+    } else {
+      const layer = requireLayer(this.state.layers, source.layerId).layer;
+      const coverage = this.layerMaskCoverage(source.layerId);
+      if (!coverage) throw new LayerOperationError(`Layer "${layer.name || source.layerId}" has no painted mask to export.`);
+      mask = coverage;
+    }
+    const k = options.maxSide ? Math.min(1, options.maxSide / Math.max(mask.width, mask.height)) : 1;
+    if (k < 1) mask = resizeSelection(mask, Math.max(1, Math.round(mask.width * k)), Math.max(1, Math.round(mask.height * k)));
+    if (options.invert) mask = invertSelection(mask);
+    return { width: mask.width, height: mask.height, dataUrl: pngDataUrl(mask.width, mask.height, mask.data, 1) };
+  }
   /** A mask image (data URL / URL, or pixels as they are) as RGBA pixels. */
   async decodeMaskImage(source) {
     if (typeof source !== "string") return source;
@@ -8158,10 +8319,165 @@ var ImageEditorController = class {
       throw new Error(`Unknown selection display "${String(display)}". Use ants, quickMask or none.`);
     }
     if (this.getSelectionDisplay() === display) return;
+    if (display !== "quickMask") delete this.state.quickMaskEditing;
     this.state.selectionDisplay = display;
     this.state.quickMask = display === "quickMask";
     this.notify();
   }
+  // --- Alpha channels ---
+  /** The alpha channels (saved selections), in panel order. */
+  getChannels() {
+    return this.state.channels ?? [];
+  }
+  getChannel(id) {
+    return this.state.channels?.find((c) => c.id === id) ?? null;
+  }
+  requireChannel(id) {
+    const channel = this.getChannel(id);
+    if (!channel) {
+      const ids = this.getChannels().map((c) => `${c.id} (${c.name})`);
+      throw new LayerOperationError(`There is no alpha channel "${id}"; the channels are ${ids.join(", ") || "none (save a selection first)"}.`);
+    }
+    return channel;
+  }
+  setChannels(next, commitToHistory = true) {
+    if (commitToHistory) this.recordHistory();
+    if (next.length) this.state.channels = next;
+    else delete this.state.channels;
+    this.notify();
+  }
+  newChannelId() {
+    const ids = new Set(this.getChannels().map((c) => c.id));
+    let n = this.getChannels().length + 1;
+    while (ids.has(`ch_${n}`)) n++;
+    return `ch_${n}`;
+  }
+  /**
+   * 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 = {}) {
+    const sel = this.state.selection;
+    if (!sel?.bounds) throw new LayerOperationError("Nothing is selected; select first, then save the selection to a channel.");
+    const { width, height } = this.naturalSize;
+    const sized = sel.width === width && sel.height === height ? sel : resizeSelection(sel, width, height);
+    const channels = [...this.getChannels()];
+    if (options.channelId !== void 0) {
+      const existing = this.requireChannel(options.channelId);
+      const mask = combineSelections(existing.mask.bounds ? existing.mask : null, sized, options.mode ?? "replace") ?? createSelectionMask(width, height);
+      const next = { ...existing, mask, ...options.name?.trim() ? { name: options.name.trim() } : {} };
+      this.setChannels(channels.map((c) => c.id === existing.id ? next : c));
+      return next;
+    }
+    return this.addChannel(sized, options.name);
+  }
+  /** Appends a new channel holding `mask` (canvas-sized) as one undo step. */
+  addChannel(mask, name) {
+    const channels = this.getChannels();
+    const channel = {
+      id: this.newChannelId(),
+      name: name?.trim() || `Alpha ${channels.length + 1}`,
+      mask,
+      color: DEFAULT_CHANNEL_COLOR,
+      opacity: 0.5,
+      indicates: "masked",
+      visible: false
+    };
+    this.setChannels([...channels, channel]);
+    return channel;
+  }
+  /**
+   * Select › Load Selection from an alpha channel (inverted with `invert`), combined with the
+   * selection by `mode`. One undo step.
+   */
+  loadSelectionFromChannel(id, options = {}) {
+    const channel = this.requireChannel(id);
+    const mask = options.invert ? invertSelection(channel.mask) : channel.mask;
+    return this.setSelection(mask.bounds ? mask : null, options.mode ?? "replace");
+  }
+  /** Changes a channel's name, overlay colour, opacity, what it indicates or visibility (one undo step). */
+  setChannelProperties(id, props) {
+    const channel = this.requireChannel(id);
+    if (props.name !== void 0 && !props.name.trim()) throw new LayerOperationError("A channel name cannot be empty.");
+    if (props.color !== void 0 && !/^#[0-9a-f]{6}$/i.test(props.color)) throw new LayerOperationError("color must be #rrggbb.");
+    if (props.opacity !== void 0 && !(props.opacity >= 0 && props.opacity <= 1)) throw new LayerOperationError("opacity must be from 0 to 1.");
+    if (props.indicates !== void 0 && props.indicates !== "masked" && props.indicates !== "selected") throw new LayerOperationError("indicates must be masked or selected.");
+    const next = {
+      ...channel,
+      ...props.name !== void 0 ? { name: props.name.trim() } : {},
+      ...props.color !== void 0 ? { color: props.color.toLowerCase() } : {},
+      ...props.opacity !== void 0 ? { opacity: props.opacity } : {},
+      ...props.indicates !== void 0 ? { indicates: props.indicates } : {},
+      ...props.visible !== void 0 ? { visible: props.visible } : {}
+    };
+    this.setChannels(this.getChannels().map((c) => c.id === id ? next : c));
+    return next;
+  }
+  /** Deletes an alpha channel (one undo step). */
+  deleteChannel(id) {
+    this.requireChannel(id);
+    this.setChannels(this.getChannels().filter((c) => c.id !== id));
+  }
+  /** Duplicates an alpha channel just after it (one undo step). Returns the copy. */
+  duplicateChannel(id, name) {
+    const channel = this.requireChannel(id);
+    const copy = { ...channel, id: this.newChannelId(), name: name?.trim() || `${channel.name} copy` };
+    const channels = [...this.getChannels()];
+    channels.splice(channels.findIndex((c) => c.id === id) + 1, 0, copy);
+    this.setChannels(channels);
+    return copy;
+  }
+  /** Channel summaries (no pixels) for panels and agents. */
+  describeChannels() {
+    return this.getChannels().map(describeChannel);
+  }
+  // --- Quick Mask mode ---
+  /** Whether Quick Mask mode is on (painting edits the selection). */
+  get quickMaskEditing() {
+    return Boolean(this.state.quickMaskEditing);
+  }
+  /**
+   * 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) {
+    if (this.quickMaskEditing === on) return;
+    if (on) this.state.quickMaskEditing = true;
+    else delete this.state.quickMaskEditing;
+    this.setSelectionDisplay(on ? "quickMask" : "ants");
+    this.notify();
+  }
+  /** The selection as a 1-channel surface to paint in Quick Mask mode. */
+  quickMaskSurface() {
+    const { width, height } = this.naturalSize;
+    const sel = this.state.selection;
+    if (!sel?.bounds) return emptySurface(1, 0);
+    const sized = sel.width === width && sel.height === height ? sel : resizeSelection(sel, width, height);
+    return surfaceFromPixels({ width, height, data: sized.data }, 1, 0, 0, 0);
+  }
+  /** The selection a painted Quick Mask surface stands for (`rects` changed since `base`). */
+  selectionFromSurface(surface, base = null, rects) {
+    const { width, height } = this.naturalSize;
+    let data;
+    if (base && rects && base.width === width && base.height === height) {
+      data = new Uint8Array(base.data);
+      for (const r of rects) {
+        const x0 = Math.max(0, Math.floor(r.x));
+        const y0 = Math.max(0, Math.floor(r.y));
+        const x1 = Math.min(width, Math.ceil(r.x + r.width));
+        const y1 = Math.min(height, Math.ceil(r.y + r.height));
+        if (x1 <= x0 || y1 <= y0) continue;
+        const part = readRegion(surface, { x: x0, y: y0, width: x1 - x0, height: y1 - y0 });
+        for (let y = y0; y < y1; y++) data.set(part.subarray((y - y0) * (x1 - x0), (y - y0 + 1) * (x1 - x0)), y * width + x0);
+      }
+    } else {
+      const all = readRegion(surface, { x: 0, y: 0, width, height });
+      data = new Uint8Array(all.buffer, all.byteOffset, all.length);
+    }
+    return normalizeSelection(createSelectionMask(width, height, data));
+  }
   // --- Layer masks ---
   maskFromSelection(sel, props = {}) {
     const { width, height } = this.naturalSize;
@@ -8208,14 +8524,19 @@ var ImageEditorController = class {
    * with `invert`. False without a painted mask (a depth mask is computed, not painted).
    */
   selectionFromLayerMask(layerId, mode = "replace", invert2 = false) {
+    const sel = this.layerMaskCoverage(layerId);
+    if (!sel) return false;
+    return this.setSelection(invert2 ? invertSelection(sel) : sel, mode);
+  }
+  /** A layer's painted mask over the canvas as a selection mask; null without one (or for a depth mask). */
+  layerMaskCoverage(layerId) {
     const layer = this.getLayer(layerId);
-    if (!layer?.mask || layer.mask.source) return false;
+    if (!layer?.mask || layer.mask.source) return null;
     const { width, height } = this.naturalSize;
     const ox = layer.type === "pixel" ? layer.offset.x : 0;
     const oy = layer.type === "pixel" ? layer.offset.y : 0;
     const data = readRegion(layer.mask.surface, { x: -ox, y: -oy, width, height });
-    const sel = createSelectionMask(width, height, new Uint8Array(data.buffer, data.byteOffset, data.length));
-    return this.setSelection(invert2 ? invertSelection(sel) : sel, mode);
+    return createSelectionMask(width, height, new Uint8Array(data.buffer, data.byteOffset, data.length));
   }
   // --- Histogram ---
   /**
@@ -9275,6 +9596,17 @@ var ImageEditorController = class {
     s.outputOpacity = 1;
     delete s.legacyOutputBlur;
     s.selection = null;
+    const psdChannels = (result.alphaChannels ?? []).map((c, k) => ({
+      id: `ch_${k + 1}`,
+      name: c.name,
+      mask: createSelectionMask(result.width, result.height, c.data),
+      color: c.color,
+      opacity: c.opacity,
+      indicates: c.indicates,
+      visible: false
+    }));
+    if (psdChannels.length) s.channels = psdChannels;
+    else delete s.channels;
     s.selectedAnnotationId = null;
     s.activeLayerId = defaultActiveLayerId(s.layers);
     s.activeTarget = "pixels";
@@ -9465,7 +9797,14 @@ var ImageEditorController = class {
     if (color.colorMode && this.bitDepth === 32) warnings.push(`${color.colorMode.toUpperCase()} files are written at 16 bits per channel at most; the 32-bit samples were converted (colour above 1 clipped).`);
     const depth = color.colorMode && this.bitDepth === 32 ? 16 : this.bitDepth;
     const mergedDeep = depth === 8 ? void 0 : workingToSamples(compositeDeep(prepared, canvas, sources, depth), depth);
-    const result = exportPsd({ width, height, layers: prepared, merged, mergedDeep, resolution: this.psdResolution, patterns: this.state.patterns, globalLight: this.state.globalLight, depth, ...color });
+    const alphaChannels = this.getChannels().map((c) => ({
+      name: c.name,
+      data: c.mask.width === width && c.mask.height === height ? c.mask.data : resizeSelection(c.mask, width, height).data,
+      color: c.color,
+      opacity: c.opacity,
+      indicates: c.indicates
+    }));
+    const result = exportPsd({ width, height, layers: prepared, merged, mergedDeep, resolution: this.psdResolution, patterns: this.state.patterns, globalLight: this.state.globalLight, depth, alphaChannels, ...color });
     warnings.push(...result.warnings);
     return { bytes: result.bytes, warnings, psb: result.psb, width, height };
   }
@@ -9538,6 +9877,7 @@ var ImageEditorController = class {
     try {
       out = this.serializeState();
       if (this.state.selection?.bounds) out.selection = serializeSelection(this.state.selection);
+      if (this.state.channels?.length) out.channels = serializeChannels(this.state.channels);
     } finally {
       if (root) {
         this.state = current;
@@ -9578,6 +9918,11 @@ var ImageEditorController = class {
     }
     this.state.selection = selection;
     this.dropMismatchedSelection();
+    const problems = [];
+    const channels = deserializeChannels(data.channels, this.naturalSize, problems);
+    if (channels.length) this.state.channels = channels;
+    else delete this.state.channels;
+    if (problems.length) this.lastLoadProblems = [...this.lastLoadProblems, ...problems];
     this.notify();
   }
   /** Problems found by the last `loadJSON` / `initialState` of a v3 document (unreadable layers or assets). */
@@ -10549,7 +10894,7 @@ var DEPTH_MASK_CONTROLS = [
 // src/image-editor/playback.ts
 var IMAGE_PLAYBACK_KIND = "layer";
 var PAINT = /^(paint_stroke|clone_stamp|heal_brush|spot_heal|dodge|burn|sponge|smudge|blur_stroke|sharpen_stroke|history_brush|set_clone_source|set_clone_transform|fill_pixels|clear_pixels|set_paint|set_retouch_options|load_mixer_brush|clean_mixer_brush)$/;
-var SELECT = /^(select_region|select_subject|select_by_color|select_all|deselect|invert_selection|select_rect|select_ellipse|select_polygon|select_line|magic_wand|grow_selection|select_similar|reselect|select_layer_transparency|select_color_range|load_selection_from_image|load_selection_from_mask|set_selection_display|modify_selection|refine_selection|transform_selection|apply_selection_as_mask|layer_via_copy|stroke_selection|content_aware_fill|copy_pixels|cut_pixels|paste_pixels)$/;
+var SELECT = /^(select_region|select_subject|select_by_color|select_all|deselect|invert_selection|select_rect|select_ellipse|select_polygon|select_line|magic_wand|grow_selection|select_similar|reselect|select_layer_transparency|select_color_range|load_selection_from_image|load_selection_from_mask|set_selection_display|modify_selection|refine_selection|transform_selection|apply_selection_as_mask|layer_via_copy|stroke_selection|content_aware_fill|copy_pixels|cut_pixels|paste_pixels|save_selection|load_selection_from_channel|set_channel_properties|duplicate_channel|delete_channel|load_channel_from_image|set_quick_mask)$/;
 var ANNOTATE = /^(add_shape_layer|update_shape|add_shape_component|set_shape_component|remove_shape_component|merge_shape_components|add_text_layer|set_text|set_text_style|set_paragraph_style|set_text_frame|convert_text_to_shape)$/;
 var CROP = /^(set_crop|crop_to_selection|reset_crop|set_rotation|flip_image|transform_layer|warp_layer|flip_layer|offset_layer)$/;
 var ADJUST = /^(set_adjustments|add_adjustment_layer|update_adjustment_layer|remove_adjustment_layer|move_adjustment_layer)$/;
@@ -11458,6 +11803,171 @@ function createImageSelectionTools(controller) {
     annotations: writeAnnotations("Paste pixels"),
     handler: (args) => controller.pastePixels(args.mode ?? "new-layer")
   };
+  const channelIdSchema = { type: "string", minLength: 1, description: "The alpha channel (see list_channels)." };
+  const channelResult = (id) => controller.describeChannels().find((c) => c.id === id);
+  const listChannels = {
+    name: "list_channels",
+    title: "List alpha channels",
+    description: "Lists the alpha channels (saved selections kept with the document): id, name, bounds, percent of the image covered, overlay color, opacity, what the tint indicates and whether it is visible. Also whether Quick Mask mode is on.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { title: "List alpha channels", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: () => ({ channels: controller.describeChannels(), quickMask: controller.quickMaskEditing })
+  };
+  const saveSelectionTool = {
+    name: "save_selection",
+    title: "Save the selection to a channel",
+    description: 'Select \u203A Save Selection: stores the selection in a new alpha channel (name, default "Alpha n"), or with channelId combines it into that channel by mode (replace, add, subtract, intersect). Save any selection that took work, so it can be loaded again with load_selection_from_channel. Fails when nothing is selected. One undo step. Returns the channel.',
+    inputSchema: {
+      type: "object",
+      properties: { channelId: channelIdSchema, name: { type: "string", minLength: 1, description: "Name of a new channel, or a new name for channelId." }, mode: modeSchema },
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Save the selection to a channel"),
+    handler: (args) => {
+      if (!controller.getSelection()) throw new Error("Nothing is selected; select first, then save it.");
+      const c = controller.saveSelection({ channelId: args.channelId, name: args.name, mode: parseSelectionMode(args.mode) });
+      return { channel: channelResult(c.id) };
+    }
+  };
+  const loadChannelTool = {
+    name: "load_selection_from_channel",
+    title: "Load a selection from a channel",
+    description: "Select \u203A Load Selection from an alpha channel (invert for its inverse), combined with the current selection by mode. One undo step. Returns the selection.",
+    inputSchema: {
+      type: "object",
+      properties: { channelId: channelIdSchema, invert: { type: "boolean", description: "Load the inverse (default false)." }, mode: modeSchema },
+      required: ["channelId"],
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Load a selection from a channel", true),
+    handler: (args) => {
+      controller.loadSelectionFromChannel(String(args.channelId), { mode: parseSelectionMode(args.mode), invert: args.invert === true });
+      return summary(controller);
+    }
+  };
+  const channelPropsTool = {
+    name: "set_channel_properties",
+    title: "Change an alpha channel",
+    description: "Renames an alpha channel or changes its overlay: color (#rrggbb), opacity (0..1), indicates (masked: tint the unselected area, or selected) and visible (show the tint on the canvas). Pixels do not change. One undo step. Returns the channel.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channelId: channelIdSchema,
+        name: { type: "string", minLength: 1, description: "New name." },
+        color: { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: "Overlay colour #rrggbb." },
+        opacity: { type: "number", minimum: 0, maximum: 1, description: "Overlay opacity 0..1." },
+        indicates: { type: "string", enum: ["masked", "selected"], description: "Which area the tint covers." },
+        visible: { type: "boolean", description: "Show the channel as a tint on the canvas." }
+      },
+      required: ["channelId"],
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Change an alpha channel", true),
+    handler: (args) => {
+      const { channelId, ...props } = args;
+      const c = controller.setChannelProperties(String(channelId), props);
+      return { channel: channelResult(c.id) };
+    }
+  };
+  const duplicateChannelTool = {
+    name: "duplicate_channel",
+    title: "Duplicate an alpha channel",
+    description: 'Copies an alpha channel (name, default "<name> copy") just after it, to keep a version before changing it. One undo step. Returns the copy.',
+    inputSchema: {
+      type: "object",
+      properties: { channelId: channelIdSchema, name: { type: "string", minLength: 1, description: "Name of the copy." } },
+      required: ["channelId"],
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Duplicate an alpha channel"),
+    handler: (args) => ({ channel: channelResult(controller.duplicateChannel(String(args.channelId), args.name).id) })
+  };
+  const deleteChannelTool = {
+    name: "delete_channel",
+    title: "Delete an alpha channel",
+    description: "Deletes an alpha channel (undo_image brings it back). Returns the remaining channels.",
+    inputSchema: { type: "object", properties: { channelId: channelIdSchema }, required: ["channelId"], additionalProperties: false },
+    annotations: { title: "Delete an alpha channel", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    handler: (args) => {
+      controller.deleteChannel(String(args.channelId));
+      return { channels: controller.describeChannels() };
+    }
+  };
+  const quickMaskTool = {
+    name: "set_quick_mask",
+    title: "Quick Mask mode",
+    description: "Turns Quick Mask mode on or off (Q). On, the selection shows as a red tint and paint_stroke, fill_pixels, clear_pixels, stroke_selection and the retouch tools called without layerId edit the selection itself: white selects, black deselects, grey selects partly, and blur_stroke softens its edge. Each edit is one undo step. Turn it off before painting layers again. Returns the mode and the selection.",
+    inputSchema: {
+      type: "object",
+      properties: { enabled: { type: "boolean", description: "true to enter Quick Mask mode, false to leave it." } },
+      required: ["enabled"],
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Quick Mask mode", true),
+    handler: (args) => {
+      if (typeof args.enabled !== "boolean") throw new Error("enabled must be true or false.");
+      controller.setQuickMaskMode(args.enabled);
+      return { quickMask: controller.quickMaskEditing, selection: summary(controller) };
+    }
+  };
+  const exportMaskTool = {
+    name: "export_mask_image",
+    title: "Export a mask as a PNG",
+    description: "Writes the selection, an alpha channel (channelId) or a layer's painted mask (layerId) as a greyscale PNG: white = selected / revealed. Use it to look at a mask on its own, or to hand it to another tool or service; load_channel_from_image and load_selection_from_image read it back. Give at most one of channelId and layerId (neither = the selection). Changes nothing. Returns the image and its size.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channelId: channelIdSchema,
+        layerId: { type: "string", minLength: 1, description: "A layer whose painted mask to export (see list_layers)." },
+        invert: { type: "boolean", description: "Black = selected instead (default false)." },
+        maxSide: { type: "integer", minimum: 16, maximum: 16384, description: "Longest side in pixels; larger masks are scaled down (default 1024, never scaled up)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Export a mask as a PNG", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: (args) => {
+      if (args.channelId !== void 0 && args.layerId !== void 0) throw new Error("Give channelId or layerId, not both (neither exports the selection).");
+      if (typeof args.layerId === "string" && !controller.getLayer(args.layerId)) throw new Error(`No layer "${args.layerId}". Call list_layers for ids.`);
+      const source = typeof args.channelId === "string" ? { channelId: args.channelId } : typeof args.layerId === "string" ? { layerId: args.layerId } : "selection";
+      const out = controller.exportMaskImage(source, { invert: args.invert === true, maxSide: typeof args.maxSide === "number" ? args.maxSide : 1024 });
+      const what = source === "selection" ? "Selection" : "channelId" in source ? `Channel ${source.channelId}` : `Mask of layer ${source.layerId}`;
+      return {
+        content: [
+          { type: "image", data: out.dataUrl.slice(out.dataUrl.indexOf(",") + 1), mimeType: "image/png" },
+          { type: "text", text: `${what}, ${out.width}\xD7${out.height}` }
+        ],
+        structuredContent: { width: out.width, height: out.height }
+      };
+    }
+  };
+  const loadChannelFromImageTool = {
+    name: "load_channel_from_image",
+    title: "Load a mask image into a new channel",
+    description: "Stores a mask image (an AI segmentation, a matte, a PNG from export_mask_image) in a new alpha channel without touching the selection: white = selected by luminance, or one channel. Any size; it is resampled to the image. Load it as the selection later with load_selection_from_channel. One undo step. Returns the channel.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: { type: "string", minLength: 1, description: "The mask as a data URL (data:image/png;base64,\u2026) or an image URL." },
+        name: { type: "string", minLength: 1, description: 'Channel name (default "Alpha n").' },
+        channel: { type: "string", enum: ["luminance", "alpha", "red", "green", "blue"], description: "What to read as coverage (default luminance; alpha for a cutout PNG)." },
+        threshold: { type: "number", minimum: 0, maximum: 255, description: "Values at or above this are selected, the rest not (default: keep soft values)." },
+        invert: { type: "boolean", description: "Black = selected instead (default false)." }
+      },
+      required: ["image"],
+      additionalProperties: false
+    },
+    annotations: { ...writeAnnotations("Load a mask image into a new channel"), openWorldHint: true },
+    handler: async (args) => {
+      if (typeof args.image !== "string" || !args.image.trim()) throw new Error("image must be a data URL or image URL.");
+      const c = await controller.loadChannelFromImage(args.image, {
+        name: args.name,
+        channel: args.channel ?? "luminance",
+        invert: args.invert === true,
+        threshold: typeof args.threshold === "number" ? Math.min(255, Math.max(0, args.threshold)) : void 0
+      });
+      return { channel: channelResult(c.id) };
+    }
+  };
   return [
     getSelection,
     selectAll,
@@ -11486,7 +11996,16 @@ function createImageSelectionTools(controller) {
     fillTool,
     copyTool,
     cutTool,
-    pasteTool
+    pasteTool,
+    listChannels,
+    saveSelectionTool,
+    loadChannelTool,
+    channelPropsTool,
+    duplicateChannelTool,
+    deleteChannelTool,
+    exportMaskTool,
+    loadChannelFromImageTool,
+    quickMaskTool
   ];
 }
 function createImageSubjectSelectionTool(controller) {
@@ -12907,6 +13426,9 @@ function handlePaintShortcut(controller, e) {
   const set = (b) => controller.setPaintOptions({ brush: b });
   const key = e.key;
   switch (key.toLowerCase()) {
+    case "q":
+      controller.setQuickMaskMode(!controller.quickMaskEditing);
+      return true;
     case "b":
       controller.setTool(e.shiftKey || key === "B" ? "mixer" : "brush");
       return true;
@@ -13046,8 +13568,8 @@ var TARGET = {
   layerId: { type: "string", description: "Layer to paint (default the active layer; see list_layers)." },
   channel: {
     type: "string",
-    enum: ["pixels", "mask", "filter-mask"],
-    description: "pixels (default for a pixel layer), the layer's mask, or a smart object's smart filter mask (filter-mask): black hides, white reveals."
+    enum: ["pixels", "mask", "filter-mask", "quick-mask"],
+    description: "pixels (default for a pixel layer), the layer's mask, or a smart object's smart filter mask (filter-mask): black hides, white reveals. In Quick Mask mode (set_quick_mask), quick-mask (the default when no layerId is given) paints the selection: white selects, black deselects."
   }
 };
 var BRUSH = {
@@ -13435,8 +13957,8 @@ var TARGET2 = {
   layerId: { type: "string", description: "Layer to retouch (default the active layer; see list_layers)." },
   channel: {
     type: "string",
-    enum: ["pixels", "mask", "filter-mask"],
-    description: "pixels (default for a pixel layer), the layer's mask, or a smart object's filter mask. Masks are grey values and sample only themselves."
+    enum: ["pixels", "mask", "filter-mask", "quick-mask"],
+    description: "pixels (default for a pixel layer), the layer's mask, or a smart object's filter mask. Masks are grey values and sample only themselves. In Quick Mask mode (set_quick_mask), quick-mask (the default when no layerId is given) paints the selection: white selects, black deselects."
   }
 };
 var SAMPLE = {
@@ -15538,6 +16060,44 @@ function handleSelectionShortcut(controller, e, onError) {
   if (key === "i" && e.shiftKey) return run(() => controller.invertSelection());
   return false;
 }
+function handleQuickMaskKey(controller, e) {
+  if (e.ctrlKey || e.metaKey || e.altKey || e.key.toLowerCase() !== "q") return false;
+  controller.setQuickMaskMode(!controller.quickMaskEditing);
+  return true;
+}
+
+// src/image-editor/selection/mask-files.ts
+var MASK_FILE_ACCEPT = "image/png,image/jpeg,image/webp,image/gif,image/bmp";
+function blobDataUrl(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error("The file could not be read."));
+    reader.readAsDataURL(file);
+  });
+}
+function maskNameFromFile(file) {
+  const name = file.name;
+  return name ? name.replace(/\.[a-z0-9]{2,4}$/i, "").trim() || void 0 : void 0;
+}
+async function openMaskFile(controller, file) {
+  return controller.loadChannelFromImage(await blobDataUrl(file), { name: maskNameFromFile(file) });
+}
+function maskFileName(name) {
+  const base = name.replace(/\.[a-z0-9]{2,4}$/i, "").replace(/[\\/:*?"<>|]+/g, "-").trim() || "mask";
+  return `${base}.png`;
+}
+function downloadMaskImage(controller, source, name = "mask") {
+  const { dataUrl, width, height } = controller.exportMaskImage(source);
+  const fileName = maskFileName(name);
+  if (typeof document !== "undefined") {
+    const a = document.createElement("a");
+    a.href = dataUrl;
+    a.download = fileName;
+    a.click();
+  }
+  return { fileName, width, height };
+}
 
 // src/image-editor/mosaic-filter.ts
 function resolveMosaicRegionBounds(region, imgWidth, imgHeight) {
@@ -17124,6 +17684,7 @@ export {
   DEFAULT_BLENDER,
   DEFAULT_BRUSH,
   DEFAULT_CANVAS_VIEWPORT,
+  DEFAULT_CHANNEL_COLOR,
   DEFAULT_DEPTH_MASK,
   DEFAULT_FLOW,
   DEFAULT_GLOBAL_LIGHT,
@@ -17199,6 +17760,7 @@ export {
   LayerEffectError,
   LayerOperationError,
   MARCHING_ANTS_STEP_MS,
+  MASK_FILE_ACCEPT,
   MAX_BATCH,
   MAX_BRUSH_SIZE,
   MAX_CANVAS_BACKING_SIDE,
@@ -17268,6 +17830,7 @@ export {
   PatternPlacement,
   PatternTile,
   PsdError,
+  QUICK_MASK_TARGET,
   REFINE_EDGE_CONTROLS,
   RETOUCH_CHOICES,
   RETOUCH_OPTION_CONTROLS,
@@ -17425,6 +17988,7 @@ export {
   canvasToImagePoint,
   caretAt,
   changedTiles,
+  channelThumbnail,
   checkEffectAnimation,
   checkEffectTime,
   checkImageEffectPlace,
@@ -17523,10 +18087,12 @@ export {
   depthMaskAlpha,
   depthOf,
   depthRasterMask,
+  describeChannel,
   describeLayer,
   describeLayerEffects,
   describeSelection,
   describeTransform,
+  deserializeChannels,
   deserializeColorMode,
   deserializeColorProfile,
   deserializeEffects,
@@ -17546,6 +18112,7 @@ export {
   documentProfile,
   dodgeBurn,
   dodgeBurnCurve,
+  downloadMaskImage,
   downloadPsd,
   dpow,
   dragWarpMeshPoint,
@@ -17617,6 +18184,7 @@ export {
   guidePlanes,
   guidedFilterColor,
   handlePaintShortcut,
+  handleQuickMaskKey,
   handleSelectionShortcut,
   hasActiveEffects,
   hasLayersBelow,
@@ -17737,6 +18305,8 @@ export {
   mapLayer,
   mapSubpaths,
   maskBounds,
+  maskFileName,
+  maskNameFromFile,
   maskSummary,
   maskThumbnailClick,
   matrixFromCorners,
@@ -17794,6 +18364,7 @@ export {
   offsetLayer,
   offsetShape,
   offsetSmartObject,
+  openMaskFile,
   openPsdFile,
   packRgba,
   packWetParams,
@@ -17944,6 +18515,7 @@ export {
   selectionToCoverage,
   selectionToPixels,
   selectionValueAt,
+  serializeChannels,
   serializeColorMode,
   serializeColorProfile,
   serializeContents,