@pixerate/editor 0.186.0 → 0.188.0

package/dist/image-editor/index.js

@@ -298,6 +298,8 @@ import {
   selectionArea,
   selectionFromCoverage,
   selectionFromPixels,
+  selectionFromRegion,
+  selectionFromTiles,
   selectionToCoverage,
   selectionToPixels,
   selectionValueAt,
@@ -370,7 +372,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-FW7N64XK.js";
+} from "../chunk-IGMNJM2H.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -2835,8 +2837,33 @@ var TypeToolGesture = class {
 
 // src/image-editor/selection/shapes.ts
 function polygonCoverage(points, width, height, antiAlias = true) {
+  const { box, coverage } = polygonCoverageBox(points, width, height, antiAlias);
+  if (!box || box.width === width && box.height === height) return box ? coverage : new Float32Array(width * height);
   const m = new Float32Array(width * height);
-  if (points.length < 3 || width <= 0 || height <= 0) return m;
+  for (let y = 0; y < box.height; y++) m.set(coverage.subarray(y * box.width, (y + 1) * box.width), (box.y + y) * width + box.x);
+  return m;
+}
+function polygonCoverageBox(points, width, height, antiAlias = true) {
+  const none = { box: null, coverage: new Float32Array(0) };
+  if (points.length < 3 || width <= 0 || height <= 0) return none;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const p of points) {
+    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) continue;
+    minX = Math.min(minX, p.x);
+    minY = Math.min(minY, p.y);
+    maxX = Math.max(maxX, p.x);
+    maxY = Math.max(maxY, p.y);
+  }
+  const bx0 = Math.max(0, Math.floor(minX));
+  const by0 = Math.max(0, Math.floor(minY));
+  const bx1 = Math.min(width, Math.ceil(maxX));
+  const by1 = Math.min(height, Math.ceil(maxY));
+  if (!(bx1 > bx0 && by1 > by0)) return none;
+  const bw = bx1 - bx0;
+  const m = new Float32Array(bw * (by1 - by0));
   const sub2 = antiAlias ? 4 : 1;
   const edges = [];
   for (let i = 0; i < points.length; i++) {
@@ -2850,8 +2877,8 @@ function polygonCoverage(points, width, height, antiAlias = true) {
   let next = 0;
   let active = [];
   const xs = [];
-  for (let py = 0; py < height; py++) {
-    const row = py * width;
+  for (let py = by0; py < by1; py++) {
+    const row = (py - by0) * bw - bx0;
     for (let s = 0; s < sub2; s++) {
       const y = py + (s + 0.5) / sub2;
       while (next < edges.length && edges[next].top <= y) active.push(edges[next++]);
@@ -2881,15 +2908,14 @@ function polygonCoverage(points, width, height, antiAlias = true) {
     }
   }
   for (let i = 0; i < m.length; i++) if (m[i] > 1) m[i] = 1;
-  return m;
+  return { box: { x: bx0, y: by0, width: bw, height: by1 - by0 }, coverage: m };
 }
-function toMask(width, height, coverage) {
+function polygonSelection(width, height, points, options = {}) {
+  const { box, coverage } = polygonCoverageBox(points, width, height, options.antiAlias ?? true);
+  if (!box) return createSelectionMask(width, height);
   const out = new Uint8Array(coverage.length);
   for (let i = 0; i < out.length; i++) out[i] = coverageToByte(coverage[i]);
-  return createSelectionMask(width, height, out);
-}
-function polygonSelection(width, height, points, options = {}) {
-  return toMask(width, height, polygonCoverage(points, width, height, options.antiAlias ?? true));
+  return selectionFromRegion(width, height, box, out);
 }
 function normalizeRect(rect) {
   const x = rect.width < 0 ? rect.x + rect.width : rect.x;
@@ -3531,9 +3557,7 @@ function selectionRing(sel, width, location) {
 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;
+  const percent = Math.round(selectionArea(mask) / Math.max(1, mask.width * mask.height) * 1e4) / 100;
   return { ...rest, bounds: mask.bounds, percent };
 }
 function serializeChannels(channels) {
@@ -4144,8 +4168,7 @@ var FreeTransformSession = class {
       const result = part.base ? compositeSurfaceOver(part.base, moved) : moved;
       if (part.what === "selection") {
         const { width, height } = this.host.canvas();
-        const data = new Uint8Array(readRegion(result, { x: 0, y: 0, width, height }).buffer);
-        const next = createSelectionMask(width, height, data);
+        const next = selectionFromTiles(width, height, result);
         selection = next.bounds ? next : null;
       } else if (part.what === "pixels") {
         layers = mapLayer(layers, targetId, (l) => {
@@ -5471,14 +5494,18 @@ var ImageEditorController = class {
     this.trimHistoryBytes();
   }
   /**
-   * Bytes of pixel tiles held only by undo / redo steps (not by the current state). The oldest
-   * undo steps are dropped while it exceeds `maxHistoryBytes`.
+   * Bytes of pixel, selection and channel tiles held only by undo / redo steps (not by the
+   * current state). The oldest undo steps are dropped while it exceeds `maxHistoryBytes`.
    */
   get historyBytes() {
     const live = /* @__PURE__ */ new Set();
     collectStateTiles(this.state.layers, live);
+    collectSelectionTiles(this.state.selection, this.state.channels, live);
     const held = /* @__PURE__ */ new Set();
-    for (const e of [...this.undoStack, ...this.redoStack]) collectStateTiles(e.layers, held);
+    for (const e of [...this.undoStack, ...this.redoStack]) {
+      collectStateTiles(e.layers, held);
+      collectSelectionTiles(e.selection, e.channels, held);
+    }
     let n = 0;
     for (const t of held) if (!live.has(t)) n += t.data.byteLength;
     return n;
@@ -7376,7 +7403,7 @@ 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.state.selection = this.selectionFromSurface(surface);
       this.notify();
       return;
     }
@@ -8220,6 +8247,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;
@@ -8337,10 +8397,15 @@ var ImageEditorController = class {
       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: options.name?.trim() || `Alpha ${channels.length + 1}`,
-      mask: sized,
+      name: name?.trim() || `Alpha ${channels.length + 1}`,
+      mask,
       color: DEFAULT_CHANNEL_COLOR,
       opacity: 0.5,
       indicates: "masked",
@@ -8416,35 +8481,18 @@ var ImageEditorController = class {
     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);
+    return (sel.width === width && sel.height === height ? sel : resizeSelection(sel, width, height)).surface;
   }
-  /** The selection a painted Quick Mask surface stands for (`rects` changed since `base`). */
-  selectionFromSurface(surface, base = null, rects) {
+  /** The selection a painted Quick Mask surface stands for (it shares the surface's tiles). */
+  selectionFromSurface(surface) {
     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));
+    return normalizeSelection(selectionFromTiles(width, height, surface));
   }
   // --- Layer masks ---
   maskFromSelection(sel, props = {}) {
     const { width, height } = this.naturalSize;
     const sized = sel.width === width && sel.height === height ? sel : resizeSelection(sel, width, height);
-    const mask = { surface: surfaceFromPixels({ width, height, data: sized.data }, 1, 0, 0, 0), defaultValue: 0 };
+    const mask = { surface: sized.surface, defaultValue: 0 };
     return withMaskProps(mask, props);
   }
   /**
@@ -8486,14 +8534,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 ---
   /**
@@ -10111,6 +10164,10 @@ function isOpaqueInside(surface, width, height) {
   }
   return true;
 }
+function collectSelectionTiles(selection, channels, into) {
+  if (selection) collectTiles(selection.surface, into);
+  for (const c of channels ?? []) collectTiles(c.mask.surface, into);
+}
 function collectStateTiles(layers, into) {
   for (const l of flattenLayers(layers)) {
     if (l.type === "pixel" && l.source !== "document") collectTiles(l.surface, into);
@@ -10851,7 +10908,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|save_selection|load_selection_from_channel|set_channel_properties|duplicate_channel|delete_channel|set_quick_mask)$/;
+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)$/;
@@ -11020,9 +11077,7 @@ var REFINE_EDGE_CONTROLS = [
 ];
 function describeSelection(mask) {
   if (!mask || !mask.bounds) return "No selection";
-  let sum = 0;
-  for (let i = 0; i < mask.data.length; i++) sum += mask.data[i];
-  const pct2 = sum / 255 / mask.data.length * 100;
+  const pct2 = selectionArea(mask) / (mask.width * mask.height) * 100;
   const shown = pct2 >= 10 ? Math.round(pct2) : Math.round(pct2 * 10) / 10;
   return `${mask.bounds.width} \xD7 ${mask.bounds.height} px selected (${shown}% of the image)`;
 }
@@ -11867,6 +11922,64 @@ function createImageSelectionTools(controller) {
       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,
@@ -11902,6 +12015,8 @@ function createImageSelectionTools(controller) {
     channelPropsTool,
     duplicateChannelTool,
     deleteChannelTool,
+    exportMaskTool,
+    loadChannelFromImageTool,
     quickMaskTool
   ];
 }
@@ -15963,6 +16078,39 @@ function handleQuickMaskKey(controller, e) {
   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) {
   if (imgWidth <= 0 || imgHeight <= 0 || region.width <= 0 || region.height <= 0) {
@@ -17624,6 +17772,7 @@ export {
   LayerEffectError,
   LayerOperationError,
   MARCHING_ANTS_STEP_MS,
+  MASK_FILE_ACCEPT,
   MAX_BATCH,
   MAX_BRUSH_SIZE,
   MAX_CANVAS_BACKING_SIDE,
@@ -17975,6 +18124,7 @@ export {
   documentProfile,
   dodgeBurn,
   dodgeBurnCurve,
+  downloadMaskImage,
   downloadPsd,
   dpow,
   dragWarpMeshPoint,
@@ -18167,6 +18317,8 @@ export {
   mapLayer,
   mapSubpaths,
   maskBounds,
+  maskFileName,
+  maskNameFromFile,
   maskSummary,
   maskThumbnailClick,
   matrixFromCorners,
@@ -18224,6 +18376,7 @@ export {
   offsetLayer,
   offsetShape,
   offsetSmartObject,
+  openMaskFile,
   openPsdFile,
   packRgba,
   packWetParams,
@@ -18269,6 +18422,7 @@ export {
   pointerStrokeSample,
   pointerStrokeSamples,
   polygonCoverage,
+  polygonCoverageBox,
   polygonSelection,
   posterizeValue,
   presetWarp,
@@ -18368,6 +18522,8 @@ export {
   selectionArea,
   selectionFromCoverage,
   selectionFromPixels,
+  selectionFromRegion,
+  selectionFromTiles,
   selectionModeFromModifiers,
   selectionOutline,
   selectionRing,

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

@@ -10,3 +10,4 @@ export * from './gesture.cjs';
 export * from './segmentation.cjs';
 export * from './stroke.cjs';
 export * from './channels.cjs';
+export * from './mask-files.cjs';

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

@@ -10,3 +10,4 @@ export * from './gesture.js';
 export * from './segmentation.js';
 export * from './stroke.js';
 export * from './channels.js';
+export * from './mask-files.js';

package/dist/image-editor/selection/mask-files.d.cts

@@ -0,0 +1,20 @@
+/** Framework-free helpers behind the Import and Export PNG buttons of the React and Svelte Channels panels. */
+import type { ImageEditorController, MaskImageSource } from '../controller.cjs';
+import type { AlphaChannel } from './channels.cjs';
+/** Types the mask file pickers accept. */
+export declare const MASK_FILE_ACCEPT = "image/png,image/jpeg,image/webp,image/gif,image/bmp";
+/** A channel name from a file name: without its extension, or `Alpha n`. */
+export declare function maskNameFromFile(file: Blob): string | undefined;
+/** Reads a picked mask image (white = selected) into a new alpha channel named after the file (one undo step). */
+export declare function openMaskFile(controller: ImageEditorController, file: Blob): Promise<AlphaChannel>;
+/** A file name for an exported mask: `name` with a `.png` extension. */
+export declare function maskFileName(name: string): string;
+/**
+ * Writes the selection, a channel or a layer mask as a full-size greyscale PNG and offers it as a
+ * download (in a browser). Returns the file name and size.
+ */
+export declare function downloadMaskImage(controller: ImageEditorController, source: MaskImageSource, name?: string): {
+    fileName: string;
+    width: number;
+    height: number;
+};

package/dist/image-editor/selection/mask-files.d.ts

@@ -0,0 +1,20 @@
+/** Framework-free helpers behind the Import and Export PNG buttons of the React and Svelte Channels panels. */
+import type { ImageEditorController, MaskImageSource } from '../controller.js';
+import type { AlphaChannel } from './channels.js';
+/** Types the mask file pickers accept. */
+export declare const MASK_FILE_ACCEPT = "image/png,image/jpeg,image/webp,image/gif,image/bmp";
+/** A channel name from a file name: without its extension, or `Alpha n`. */
+export declare function maskNameFromFile(file: Blob): string | undefined;
+/** Reads a picked mask image (white = selected) into a new alpha channel named after the file (one undo step). */
+export declare function openMaskFile(controller: ImageEditorController, file: Blob): Promise<AlphaChannel>;
+/** A file name for an exported mask: `name` with a `.png` extension. */
+export declare function maskFileName(name: string): string;
+/**
+ * Writes the selection, a channel or a layer mask as a full-size greyscale PNG and offers it as a
+ * download (in a browser). Returns the file name and size.
+ */
+export declare function downloadMaskImage(controller: ImageEditorController, source: MaskImageSource, name?: string): {
+    fileName: string;
+    width: number;
+    height: number;
+};

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

@@ -1,11 +1,17 @@
 import type { CropBox } from '../types.cjs';
+import { TiledSurface } from '../../raster/surface.cjs';
 /**
  * A selection: one 8-bit coverage value per image pixel (0 = not selected, 255 = fully
  * selected), row-major over the whole source image in natural pixels — the same space as the
  * crop box and annotations. Soft values are partial selection (feathered or anti-aliased edges).
  *
+ * The coverage is stored as 256 × 256 tiles (`surface`, one byte per pixel, missing tiles are 0
+ * and every pixel outside the image is 0), so an empty or fully selected area costs nothing and
+ * masks share the tiles an operation did not change. `data` is the same coverage as one array,
+ * built on first read and cached for the few masks read most recently.
+ *
  * Treat a mask as immutable: every operation returns a new one, so history entries can share
- * them without copying.
+ * them without copying. Never write to `data`.
  */
 export interface SelectionMask {
     readonly width: number;
@@ -13,6 +19,8 @@ export interface SelectionMask {
     readonly data: Uint8Array;
     /** Bounding box of the non-zero coverage, or `null` when nothing is selected. */
     readonly bounds: CropBox | null;
+    /** The coverage as tiles (1 channel, default 0), shared with other masks where equal. */
+    readonly surface: TiledSurface;
 }
 /** How a new selection combines with the current one. */
 export type SelectionMode = 'replace' | 'add' | 'subtract' | 'intersect';
@@ -35,8 +43,19 @@ export interface SerializedSelection {
 }
 /** Bounding box of non-zero bytes. */
 export declare function computeSelectionBounds(width: number, height: number, data: ArrayLike<number>): CropBox | null;
+/**
+ * A selection over `width × height` from a 1-channel tiled surface in image space (Quick Mask
+ * paint, a mask): its tiles are shared, and coverage outside the image is dropped. A surface
+ * whose default is not 0 is read out instead.
+ */
+export declare function selectionFromTiles(width: number, height: number, surface: TiledSurface): SelectionMask;
 /** Wraps coverage bytes (taken over, not copied) as a selection, computing its bounds. */
 export declare function createSelectionMask(width: number, height: number, data?: Uint8Array): SelectionMask;
+/**
+ * A selection that is `data` (`rect.width × rect.height` coverage bytes) inside `rect` and
+ * nothing elsewhere, without allocating the whole image. `rect` must lie inside the image.
+ */
+export declare function selectionFromRegion(width: number, height: number, rect: CropBox, data: ArrayLike<number>): SelectionMask;
 /** Select › All. */
 export declare function fullSelection(width: number, height: number): SelectionMask;
 export declare function isSelectionEmpty(mask: SelectionMask | null | undefined): boolean;

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

@@ -1,11 +1,17 @@
 import type { CropBox } from '../types.js';
+import { TiledSurface } from '../../raster/surface.js';
 /**
  * A selection: one 8-bit coverage value per image pixel (0 = not selected, 255 = fully
  * selected), row-major over the whole source image in natural pixels — the same space as the
  * crop box and annotations. Soft values are partial selection (feathered or anti-aliased edges).
  *
+ * The coverage is stored as 256 × 256 tiles (`surface`, one byte per pixel, missing tiles are 0
+ * and every pixel outside the image is 0), so an empty or fully selected area costs nothing and
+ * masks share the tiles an operation did not change. `data` is the same coverage as one array,
+ * built on first read and cached for the few masks read most recently.
+ *
  * Treat a mask as immutable: every operation returns a new one, so history entries can share
- * them without copying.
+ * them without copying. Never write to `data`.
  */
 export interface SelectionMask {
     readonly width: number;
@@ -13,6 +19,8 @@ export interface SelectionMask {
     readonly data: Uint8Array;
     /** Bounding box of the non-zero coverage, or `null` when nothing is selected. */
     readonly bounds: CropBox | null;
+    /** The coverage as tiles (1 channel, default 0), shared with other masks where equal. */
+    readonly surface: TiledSurface;
 }
 /** How a new selection combines with the current one. */
 export type SelectionMode = 'replace' | 'add' | 'subtract' | 'intersect';
@@ -35,8 +43,19 @@ export interface SerializedSelection {
 }
 /** Bounding box of non-zero bytes. */
 export declare function computeSelectionBounds(width: number, height: number, data: ArrayLike<number>): CropBox | null;
+/**
+ * A selection over `width × height` from a 1-channel tiled surface in image space (Quick Mask
+ * paint, a mask): its tiles are shared, and coverage outside the image is dropped. A surface
+ * whose default is not 0 is read out instead.
+ */
+export declare function selectionFromTiles(width: number, height: number, surface: TiledSurface): SelectionMask;
 /** Wraps coverage bytes (taken over, not copied) as a selection, computing its bounds. */
 export declare function createSelectionMask(width: number, height: number, data?: Uint8Array): SelectionMask;
+/**
+ * A selection that is `data` (`rect.width × rect.height` coverage bytes) inside `rect` and
+ * nothing elsewhere, without allocating the whole image. `rect` must lie inside the image.
+ */
+export declare function selectionFromRegion(width: number, height: number, rect: CropBox, data: ArrayLike<number>): SelectionMask;
 /** Select › All. */
 export declare function fullSelection(width: number, height: number): SelectionMask;
 export declare function isSelectionEmpty(mask: SelectionMask | null | undefined): boolean;

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

@@ -11,6 +11,14 @@ export interface ShapeSelectionOptions {
  * their top), so the cost is about pixels + edges × rows they span.
  */
 export declare function polygonCoverage(points: readonly ImagePoint[], width: number, height: number, antiAlias?: boolean): Float32Array;
+/**
+ * {@link polygonCoverage} over just the polygon's bounding box (clipped to the image): `coverage`
+ * is `box.width × box.height`; `box` is `null` when the polygon covers no pixel row or column.
+ */
+export declare function polygonCoverageBox(points: readonly ImagePoint[], width: number, height: number, antiAlias?: boolean): {
+    box: CropBox | null;
+    coverage: Float32Array;
+};
 /** Lasso / polygonal lasso: an even-odd polygon in natural image pixels. */
 export declare function polygonSelection(width: number, height: number, points: readonly ImagePoint[], options?: ShapeSelectionOptions): SelectionMask;
 /** Normalises a rectangle with a negative width or height. */

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

@@ -11,6 +11,14 @@ export interface ShapeSelectionOptions {
  * their top), so the cost is about pixels + edges × rows they span.
  */
 export declare function polygonCoverage(points: readonly ImagePoint[], width: number, height: number, antiAlias?: boolean): Float32Array;
+/**
+ * {@link polygonCoverage} over just the polygon's bounding box (clipped to the image): `coverage`
+ * is `box.width × box.height`; `box` is `null` when the polygon covers no pixel row or column.
+ */
+export declare function polygonCoverageBox(points: readonly ImagePoint[], width: number, height: number, antiAlias?: boolean): {
+    box: CropBox | null;
+    coverage: Float32Array;
+};
 /** Lasso / polygonal lasso: an even-odd polygon in natural image pixels. */
 export declare function polygonSelection(width: number, height: number, points: readonly ImagePoint[], options?: ShapeSelectionOptions): SelectionMask;
 /** Normalises a rectangle with a negative width or height. */

package/dist/image-editor/selection/tool-options.d.cts

@@ -1,4 +1,4 @@
-import type { SelectionMask, SelectionMode } from './mask.cjs';
+import { type SelectionMask, type SelectionMode } from './mask.cjs';
 import type { ColorDistance, ColorRangePreset } from './wand.cjs';
 import type { RefineEdgeParams } from './refine.cjs';
 /** Selection tools of the image editor UI. */

package/dist/image-editor/selection/tool-options.d.ts

@@ -1,4 +1,4 @@
-import type { SelectionMask, SelectionMode } from './mask.js';
+import { type SelectionMask, type SelectionMode } from './mask.js';
 import type { ColorDistance, ColorRangePreset } from './wand.js';
 import type { RefineEdgeParams } from './refine.js';
 /** Selection tools of the image editor UI. */