@pixerate/editor 0.185.0 → 0.186.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 };
@@ -8158,10 +8286,160 @@ 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;
+    }
+    const channel = {
+      id: this.newChannelId(),
+      name: options.name?.trim() || `Alpha ${channels.length + 1}`,
+      mask: sized,
+      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;
@@ -9275,6 +9553,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 +9754,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 +9834,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 +9875,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 +10851,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|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 +11760,113 @@ 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) };
+    }
+  };
   return [
     getSelection,
     selectAll,
@@ -11486,7 +11895,14 @@ function createImageSelectionTools(controller) {
     fillTool,
     copyTool,
     cutTool,
-    pasteTool
+    pasteTool,
+    listChannels,
+    saveSelectionTool,
+    loadChannelTool,
+    channelPropsTool,
+    duplicateChannelTool,
+    deleteChannelTool,
+    quickMaskTool
   ];
 }
 function createImageSubjectSelectionTool(controller) {
@@ -12907,6 +13323,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 +13465,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 +13854,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 +15957,11 @@ 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/mosaic-filter.ts
 function resolveMosaicRegionBounds(region, imgWidth, imgHeight) {
@@ -17124,6 +17548,7 @@ export {
   DEFAULT_BLENDER,
   DEFAULT_BRUSH,
   DEFAULT_CANVAS_VIEWPORT,
+  DEFAULT_CHANNEL_COLOR,
   DEFAULT_DEPTH_MASK,
   DEFAULT_FLOW,
   DEFAULT_GLOBAL_LIGHT,
@@ -17268,6 +17693,7 @@ export {
   PatternPlacement,
   PatternTile,
   PsdError,
+  QUICK_MASK_TARGET,
   REFINE_EDGE_CONTROLS,
   RETOUCH_CHOICES,
   RETOUCH_OPTION_CONTROLS,
@@ -17425,6 +17851,7 @@ export {
   canvasToImagePoint,
   caretAt,
   changedTiles,
+  channelThumbnail,
   checkEffectAnimation,
   checkEffectTime,
   checkImageEffectPlace,
@@ -17523,10 +17950,12 @@ export {
   depthMaskAlpha,
   depthOf,
   depthRasterMask,
+  describeChannel,
   describeLayer,
   describeLayerEffects,
   describeSelection,
   describeTransform,
+  deserializeChannels,
   deserializeColorMode,
   deserializeColorProfile,
   deserializeEffects,
@@ -17617,6 +18046,7 @@ export {
   guidePlanes,
   guidedFilterColor,
   handlePaintShortcut,
+  handleQuickMaskKey,
   handleSelectionShortcut,
   hasActiveEffects,
   hasLayersBelow,
@@ -17944,6 +18374,7 @@ export {
   selectionToCoverage,
   selectionToPixels,
   selectionValueAt,
+  serializeChannels,
   serializeColorMode,
   serializeColorProfile,
   serializeContents,