@pixerate/editor 0.205.0 → 0.207.0

package/dist/image-editor/index.js

@@ -4015,10 +4015,10 @@ function edgeWidth(guide, w, h, r) {
   for (let i = 0; i < n; i++) out[i] = (hi[i] - lo[i]) / Math.max(gm[i], 1e-4);
   return out;
 }
-function refineCoverage(guide, m, w, h, params = {}) {
+function refineCoverage(guide, m, w, h, params = {}, band = null) {
   const p = normalizeRefineEdgeParams(params);
   let a = Float32Array.from(m);
-  if (p.radius > 0 && guide) {
+  if ((p.radius > 0 || band) && guide) {
     const n = w * h;
     const boundary = new Uint8Array(n);
     let any = false;
@@ -4033,14 +4033,15 @@ function refineCoverage(guide, m, w, h, params = {}) {
         }
       }
     }
-    if (any) {
+    if (any || band) {
       const dist = distanceTransform(boundary, w, h);
-      const r = gfRadius(p);
+      const r = band ? Math.max(4, gfRadius(p)) : gfRadius(p);
       const q = guidedFilterColor(guide, m, w, h, r);
       const widths = p.smartRadius ? edgeWidth(guide, w, h, r) : null;
       for (let i = 0; i < n; i++) {
         const reff = widths ? Math.min(Math.max(p.radius, 1.5), Math.max(1.5, widths[i])) : p.radius;
-        const wgt = Math.min(1, Math.max(0, reff + 1 - dist[i]));
+        const edge = p.radius > 0 ? Math.min(1, Math.max(0, reff + 1 - dist[i])) : 0;
+        const wgt = band ? Math.max(edge, Math.min(1, Math.max(0, band[i]))) : edge;
         if (wgt > 0) {
           const qi = Math.min(1, Math.max(0, q[i]));
           a[i] = m[i] + (qi - m[i]) * wgt;
@@ -4081,17 +4082,24 @@ function guidePlanes(pixels, win) {
   }
   return [r, g, b];
 }
-function refineSelection(pixels, mask, params = {}) {
+function refineSelection(pixels, mask, params = {}, refineBrush = null) {
   const p = normalizeRefineEdgeParams(params);
   if (pixels && (pixels.width !== mask.width || pixels.height !== mask.height)) {
     throw new Error("Refine Edge needs pixels the size of the selection");
   }
   if (!mask.bounds) return mask;
-  const halo = refineEdgeHalo(p);
-  const x0 = Math.max(0, mask.bounds.x - halo);
-  const y0 = Math.max(0, mask.bounds.y - halo);
-  const x1 = Math.min(mask.width, mask.bounds.x + mask.bounds.width + halo);
-  const y1 = Math.min(mask.height, mask.bounds.y + mask.bounds.height + halo);
+  const brush = refineBrush?.bounds ? refineBrush : null;
+  const halo = refineEdgeHalo(p) + (brush ? 2 * Math.max(4, gfRadius(p)) : 0);
+  const b = brush ? {
+    x: Math.min(mask.bounds.x, brush.bounds.x),
+    y: Math.min(mask.bounds.y, brush.bounds.y),
+    r: Math.max(mask.bounds.x + mask.bounds.width, brush.bounds.x + brush.bounds.width),
+    btm: Math.max(mask.bounds.y + mask.bounds.height, brush.bounds.y + brush.bounds.height)
+  } : { x: mask.bounds.x, y: mask.bounds.y, r: mask.bounds.x + mask.bounds.width, btm: mask.bounds.y + mask.bounds.height };
+  const x0 = Math.max(0, b.x - halo);
+  const y0 = Math.max(0, b.y - halo);
+  const x1 = Math.min(mask.width, b.r + halo);
+  const y1 = Math.min(mask.height, b.btm + halo);
   const ww = x1 - x0;
   const wh = y1 - y0;
   const m = new Float32Array(ww * wh);
@@ -4099,8 +4107,17 @@ function refineSelection(pixels, mask, params = {}) {
     const src = (y0 + y) * mask.width + x0;
     for (let x = 0; x < ww; x++) m[y * ww + x] = mask.data[src + x] / 255;
   }
-  const guide = pixels && p.radius > 0 ? guidePlanes(pixels, { x: x0, y: y0, width: ww, height: wh }) : null;
-  const refined = refineCoverage(guide, m, ww, wh, p);
+  const guide = pixels && (p.radius > 0 || brush) ? guidePlanes(pixels, { x: x0, y: y0, width: ww, height: wh }) : null;
+  let band = null;
+  if (brush) {
+    band = new Float32Array(ww * wh);
+    const bd = brush.data;
+    for (let y = 0; y < wh; y++) {
+      const src = (y0 + y) * mask.width + x0;
+      for (let x = 0; x < ww; x++) band[y * ww + x] = bd[src + x] / 255;
+    }
+  }
+  const refined = refineCoverage(guide, m, ww, wh, p, band);
   const out = new Uint8Array(mask.width * mask.height);
   for (let y = 0; y < wh; y++) {
     const dst = (y0 + y) * mask.width + x0;
@@ -5302,6 +5319,78 @@ function segmentsToSelection(width, height, results) {
   return out;
 }
 
+// src/image-editor/selection/refine-edits.ts
+var REFINE_EDIT_KINDS = ["quick-select", "brush", "refine-brush", "lasso", "object"];
+function brushStrokeMask(width, height, points, size, hardness = 1) {
+  const r = Math.max(0.5, size / 2);
+  const solid = r * Math.min(1, Math.max(0, hardness));
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const p of points) {
+    x0 = Math.min(x0, p.x);
+    y0 = Math.min(y0, p.y);
+    x1 = Math.max(x1, p.x);
+    y1 = Math.max(y1, p.y);
+  }
+  const bx = Math.max(0, Math.floor(x0 - r - 1));
+  const by = Math.max(0, Math.floor(y0 - r - 1));
+  const bw = Math.min(width, Math.ceil(x1 + r + 1)) - bx;
+  const bh = Math.min(height, Math.ceil(y1 + r + 1)) - by;
+  if (!(bw > 0 && bh > 0)) return createSelectionMask(width, height);
+  const out = new Uint8Array(bw * bh);
+  const segs = points.length === 1 ? [[points[0], points[0]]] : points.slice(1).map((p, i) => [points[i], p]);
+  for (let y = 0; y < bh; y++) {
+    for (let x = 0; x < bw; x++) {
+      const px2 = bx + x + 0.5;
+      const py = by + y + 0.5;
+      let d = Infinity;
+      for (const [a, b] of segs) {
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const len2 = dx * dx + dy * dy;
+        const t = len2 > 0 ? Math.min(1, Math.max(0, ((px2 - a.x) * dx + (py - a.y) * dy) / len2)) : 0;
+        d = Math.min(d, Math.hypot(px2 - a.x - t * dx, py - a.y - t * dy));
+      }
+      let v = d <= solid ? 1 : solid >= r ? 0 : 1 - (d - solid) / (r - solid);
+      v = Math.min(v, Math.min(1, Math.max(0, r + 0.5 - d)));
+      out[y * bw + x] = Math.round(Math.max(0, v) * 255);
+    }
+  }
+  return selectionFromRegion(width, height, { x: bx, y: by, width: bw, height: bh }, out);
+}
+function applyRefineEdits(pixels, selection, edits, width, height) {
+  let sel = selection?.bounds ? selection : null;
+  let band = null;
+  for (const e of edits) {
+    if (e.kind === "object") {
+      if (!pixels) throw new Error("Object Selection needs the image pixels.");
+      if (!e.rect === !e.point) throw new Error("An object edit takes rect (a box around the object) or point (on it), not both.");
+      const region2 = selectObjectIn(pixels, e.rect ? { rect: e.rect } : { point: e.point });
+      sel = combineSelections(sel, region2, e.mode ?? "add");
+      continue;
+    }
+    if (!e.points.length) throw new Error(`A ${e.kind} stroke needs at least one point.`);
+    if (e.kind === "lasso") {
+      if (e.points.length < 3) throw new Error("A lasso edit needs at least 3 points.");
+      sel = combineSelections(sel, polygonSelection(width, height, e.points, {}), e.mode ?? "add");
+      continue;
+    }
+    if (e.kind === "refine-brush") {
+      band = combineSelections(band, brushStrokeMask(width, height, e.points, e.size ?? 40), "add");
+      continue;
+    }
+    const mode = e.mode ?? "add";
+    let region;
+    if (e.kind === "quick-select") {
+      if (!pixels) throw new Error("Quick Selection strokes need the image pixels.");
+      region = quickSelectStroke(pixels, e.points, { size: e.size, selection: sel, grow: mode === "add" });
+    } else {
+      region = brushStrokeMask(width, height, e.points, e.size ?? 20, e.hardness ?? 1);
+    }
+    sel = combineSelections(sel, region, mode);
+  }
+  return { selection: sel, refineBrush: band };
+}
+
 // src/image-editor/selection/stroke.ts
 function selectionRing(sel, width, location) {
   const half = location === "center" ? width / 2 : width;
@@ -10332,10 +10421,19 @@ var ImageEditorController = class {
    * - `new-layer-with-mask`: a copy of the layer masked by the selection, the source hidden.
    * `decontaminate` (0..100, new-layer outputs only) replaces the old background's colour in the
    * soft edge with the subject's own (see `decontaminateColors`).
+   *
+   * `edits` are the workspace's strokes, applied first in order (Quick Selection, Brush and
+   * Refine Edge Brush; see `RefineEdit`); with them, an empty selection is a valid start.
+   * `refineMode: 'object'` asks the segmentation provider for the object in the selection's
+   * bounds and refines from its outline, kept to near the selection's edge.
    */
   async refineSelectionTo(params, output = "selection", options = {}) {
-    const sel = this.state.selection;
-    if (!sel?.bounds) throw new Error("Nothing is selected; select first.");
+    const edits = options.edits ?? [];
+    const refineMode = options.refineMode ?? "color";
+    if (!this.state.selection?.bounds && !edits.length) throw new Error("Nothing is selected; select first, or pass edits that paint a selection.");
+    if (refineMode === "object" && !this.segmentation) {
+      throw new Error("Object aware refinement needs a segmentation model (setSegmentationProvider); use refineMode color.");
+    }
     const amount = Math.min(100, Math.max(0, options.decontaminate ?? 0)) / 100;
     const toLayer = output === "new-layer" || output === "new-layer-with-mask";
     if (amount > 0 && !toLayer) throw new Error("Decontaminate colors writes the cleaned colours to a new layer: use output new-layer or new-layer-with-mask.");
@@ -10346,16 +10444,30 @@ var ImageEditorController = class {
       const layer = requireLayer(this.state.layers, layerId).layer;
       if (toLayer && layer.type !== "pixel") throw new LayerOperationError(`Output ${output} needs a pixel layer; "${layerId}" is a ${layer.type} layer.`);
     }
-    const pixels = (params.radius ?? 0) > 0 ? await this.requirePixels(options) : null;
-    const refined = refineSelection(pixels, sel, params);
+    const needsPixels = (params.radius ?? 0) > 0 || edits.some((e) => e.kind !== "brush");
+    const pixels = needsPixels ? await this.requirePixels(options) : null;
+    const { width, height } = this.naturalSize;
+    const edited = applyRefineEdits(pixels, this.state.selection ?? null, edits, width, height);
+    let sel = edited.selection;
+    if (!sel?.bounds) throw new Error("The edits leave nothing selected; paint with mode add first.");
+    if (refineMode === "object") {
+      const b = sel.bounds;
+      const found = await this.modelObject({ rect: b }, options.signal);
+      if (!found) throw new Error("The segmentation model found no object in the selection; use refineMode color.");
+      const near = modifySelection(sel, "expand", Math.max(4, params.radius ?? 8));
+      const clipped = combineSelections(found, near, "intersect");
+      if (!clipped?.bounds) throw new Error("The segmentation model found no object in the selection; use refineMode color.");
+      sel = clipped;
+    }
+    const refined = refineSelection(pixels, sel, params, edited.refineBrush);
     if (!refined.bounds) throw new Error("Refining left nothing selected; use a smaller shiftEdge or contrast.");
     return this.asOneStep(() => {
       this.setSelection(refined);
-      if (output === "selection") return { output };
+      if (output === "selection") return { output, refineMode };
       if (output === "layer-mask") {
         this.addLayerMask(layerId, "selection");
         this.setSelection(null);
-        return { output, layerId };
+        return { output, layerId, refineMode };
       }
       let newLayerId2;
       if (output === "new-layer") newLayerId2 = this.layerViaCopy({ layerId });
@@ -10367,7 +10479,7 @@ var ImageEditorController = class {
       if (amount > 0) this.decontaminateLayer(newLayerId2, layerId, refined, amount, Math.max(4, params.radius ?? 0));
       this.setLayerProperties(layerId, { visible: false });
       this.setSelection(null);
-      return { output, layerId, newLayerId: newLayerId2 };
+      return { output, layerId, newLayerId: newLayerId2, refineMode };
     });
   }
   /**
@@ -13586,7 +13698,7 @@ function createImageSelectionTools(controller) {
   const refine = {
     name: "refine_selection",
     title: "Refine the selection edge",
-    description: "Select and Mask / Refine Edge: snaps the selection edge to the image within radius pixels (edge-aware guided filter), then smooth (0-100), feather (px), contrast (0-100) and shiftEdge (-100..100 %), and puts the result where output says: the selection (default), a layer-mask on layerId (default the active layer; then deselects), a new-layer of its selected pixels, or a new-layer-with-mask (a masked copy); the new-layer outputs hide the source layer. decontaminate (0-100, new-layer outputs only) replaces the old background colour in soft edges (hair, fur) with the subject's own. Use it after loading a coarse AI mask, or to cut a subject out cleanly. One undoable step. Returns the selection and, for layer outputs, layerId and newLayerId.",
+    description: "Select and Mask / Refine Edge: snaps the selection edge to the image within radius pixels (edge-aware guided filter), then smooth (0-100), feather (px), contrast (0-100) and shiftEdge (-100..100 %), and puts the result where output says: the selection (default), a layer-mask on layerId (default the active layer; then deselects), a new-layer of its selected pixels, or a new-layer-with-mask (a masked copy); the new-layer outputs hide the source layer. decontaminate (0-100, new-layer outputs only) replaces the old background colour in soft edges (hair, fur) with the subject's own. Use it after loading a coarse AI mask, or to cut a subject out cleanly. edits are the Select and Mask workspace's strokes, applied first in order: quick-select (grows to the region's edges), brush (paints the selection in or out) and refine-brush (marks hair or fur for the edge to be re-estimated there); with edits, an empty selection is a valid start. refineMode object (needs a host segmentation model) refines from the model's outline of the object. One undoable step. Returns the selection, refineMode and, for layer outputs, layerId and newLayerId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -13602,13 +13714,52 @@ function createImageSelectionTools(controller) {
           description: "Where the result goes (default selection). layer-mask keeps every pixel and is easiest to revise; new-layer-with-mask too, on a copy."
         },
         layerId: { type: "string", description: "The layer for layer outputs (default the active layer; see list_layers). New-layer outputs need a pixel layer." },
-        decontaminate: { type: "number", minimum: 0, maximum: 100, description: "Decontaminate Colors amount 0-100 (default 0), only with output new-layer or new-layer-with-mask." }
+        decontaminate: { type: "number", minimum: 0, maximum: 100, description: "Decontaminate Colors amount 0-100 (default 0), only with output new-layer or new-layer-with-mask." },
+        edits: {
+          type: "array",
+          description: "Strokes applied before refining, in order.",
+          items: {
+            type: "object",
+            properties: {
+              kind: {
+                type: "string",
+                enum: ["quick-select", "brush", "refine-brush", "lasso", "object"],
+                description: "quick-select grows to edges; brush paints directly; refine-brush marks soft detail (hair) for the edge to be re-estimated; lasso adds or removes a polygon; object adds or removes the object in rect or under point."
+              },
+              points: { type: "array", minItems: 1, items: pointSchema, description: "The stroke path (or lasso outline, 3+ points) in natural image pixels; one point is a dab. Not for object." },
+              rect: {
+                type: "object",
+                properties: rectProperties,
+                required: ["x", "y", "width", "height"],
+                additionalProperties: false,
+                description: "object: a box around the object, in natural image pixels."
+              },
+              point: { ...pointSchema, description: "object: a point on the object, in natural image pixels." },
+              size: { type: "number", minimum: 1, maximum: 2500, description: "Brush diameter in natural image pixels (default 30 quick-select, 20 brush, 40 refine-brush)." },
+              mode: { type: "string", enum: ["add", "subtract"], description: "quick-select, brush, lasso and object: add (default) or subtract." },
+              hardness: { type: "number", minimum: 0, maximum: 1, description: "brush: the solid share of the radius, 0..1 (default 1)." }
+            },
+            required: ["kind"],
+            additionalProperties: false
+          }
+        },
+        refineMode: { type: "string", enum: ["color", "object"], description: "color (default): refine from the image colours; object: from a host segmentation model's outline of the object (needs a model)." }
       },
       additionalProperties: false
     },
     annotations: writeAnnotations("Refine the selection edge"),
     handler: async (params) => {
-      if (!controller.getSelection()) throw new Error("Nothing is selected.");
+      const edits = Array.isArray(params.edits) ? params.edits.map((e) => e.kind === "object" ? { ...e } : { ...e, points: (e.points ?? []).map((p) => ({ x: num2(p?.x, NaN), y: num2(p?.y, NaN) })) }) : [];
+      for (const e of edits) {
+        if (e.kind === "object") {
+          if (!e.rect === !e.point) throw new Error("An object edit takes rect (a box around the object) or point (on it).");
+          continue;
+        }
+        if (!e.points.length) throw new Error(`A ${e.kind} edit needs points.`);
+        if (!e.points.every((p) => Number.isFinite(p.x) && Number.isFinite(p.y))) throw new Error("Each edit needs points of { x, y } in natural image pixels.");
+        if (e.kind === "refine-brush" && e.mode !== void 0) throw new Error("refine-brush strokes have no mode; they mark where the edge is re-estimated.");
+      }
+      if (!controller.getSelection() && !edits.length) throw new Error("Nothing is selected.");
       const result = await controller.refineSelectionTo(
         {
           radius: num2(params.radius, 8),
@@ -13619,7 +13770,12 @@ function createImageSelectionTools(controller) {
           shiftEdge: num2(params.shiftEdge, 0)
         },
         params.output ?? "selection",
-        { layerId: typeof params.layerId === "string" ? params.layerId : void 0, decontaminate: num2(params.decontaminate, 0) }
+        {
+          layerId: typeof params.layerId === "string" ? params.layerId : void 0,
+          decontaminate: num2(params.decontaminate, 0),
+          edits,
+          refineMode: params.refineMode === "object" ? "object" : "color"
+        }
       );
       return { ...summary(controller), ...result };
     }
@@ -19000,6 +19156,374 @@ function downloadMaskImage(controller, source, name = "mask") {
   return { fileName, width, height };
 }
 
+// src/image-editor/selection/select-and-mask.ts
+var SELECT_AND_MASK_VIEWS = [
+  { id: "onion-skin", label: "Onion Skin", key: "o", opacity: 0.5 },
+  { id: "marching-ants", label: "Marching Ants", key: "m", opacity: 1 },
+  { id: "overlay", label: "Overlay", key: "v", opacity: 0.5 },
+  { id: "on-black", label: "On Black", key: "a", opacity: 1 },
+  { id: "on-white", label: "On White", key: "t", opacity: 1 },
+  { id: "black-white", label: "Black & White", key: "k", opacity: 1 },
+  { id: "on-layers", label: "On Layers", key: "y", opacity: 1 }
+];
+var SELECT_AND_MASK_TOOLS = [
+  { id: "quick-select", label: "Quick Selection", key: "w" },
+  { id: "refine-brush", label: "Refine Edge Brush", key: "r" },
+  { id: "brush", label: "Brush", key: "b" },
+  { id: "object", label: "Object Selection", key: "q" },
+  { id: "lasso", label: "Lasso", key: "l" },
+  { id: "hand", label: "Hand", key: "h" },
+  { id: "zoom", label: "Zoom", key: "z" }
+];
+var DEFAULT_SELECT_AND_MASK_SETTINGS = {
+  params: { ...DEFAULT_REFINE_EDGE_PARAMS },
+  output: "selection",
+  decontaminate: 0,
+  refineMode: "color",
+  view: "onion-skin",
+  opacity: 0.5,
+  showEdge: false,
+  showOriginal: false,
+  realTime: true,
+  highQuality: false,
+  remember: false,
+  tool: "quick-select",
+  brushSize: 30,
+  brushMode: "add"
+};
+var PREVIEW_SIZE = 1024;
+var remembered = null;
+function scalePixels(pixels, w, h) {
+  if (w === pixels.width && h === pixels.height) return pixels;
+  const { width: W, height: H, data } = pixels;
+  const sum = new Float64Array(w * h * 4);
+  const count = new Float64Array(w * h);
+  for (let y = 0; y < H; y++) {
+    const row = Math.min(h - 1, Math.floor(y * h / H)) * w;
+    for (let x = 0; x < W; x++) {
+      const o = row + Math.min(w - 1, Math.floor(x * w / W));
+      const p = (y * W + x) * 4;
+      for (let c = 0; c < 4; c++) sum[o * 4 + c] += data[p + c];
+      count[o]++;
+    }
+  }
+  const out = new Uint8ClampedArray(w * h * 4);
+  for (let i = 0; i < w * h; i++) for (let c = 0; c < 4; c++) out[i * 4 + c] = sum[i * 4 + c] / (count[i] || 1);
+  return { width: w, height: h, data: out };
+}
+function scaleEdit(edit, s) {
+  const pt = (p) => ({ x: p.x * s, y: p.y * s });
+  if (edit.kind === "object") {
+    return { ...edit, rect: edit.rect && { x: edit.rect.x * s, y: edit.rect.y * s, width: edit.rect.width * s, height: edit.rect.height * s }, point: edit.point && pt(edit.point) };
+  }
+  const scaled = { ...edit, points: edit.points.map(pt) };
+  if ("size" in edit && edit.size !== void 0) scaled.size = Math.max(1, edit.size * s);
+  return scaled;
+}
+function scaleParams(p, s) {
+  return { ...p, radius: p.radius * s, feather: p.feather * s };
+}
+var SelectAndMaskSession = class {
+  constructor(controller) {
+    this.controller = controller;
+    this.base = controller.getSelection();
+    this.settingsValue = remembered ? { ...remembered, params: { ...remembered.params }, showOriginal: false } : { ...DEFAULT_SELECT_AND_MASK_SETTINGS, params: { ...DEFAULT_SELECT_AND_MASK_SETTINGS.params } };
+  }
+  controller;
+  settingsValue;
+  editsList = [];
+  /** The edit being painted, shown in the preview but not yet in `edits`. */
+  live = null;
+  dragStart = null;
+  pixels = null;
+  previewPixels = null;
+  base;
+  previewMask = null;
+  baseMask = null;
+  listeners = /* @__PURE__ */ new Set();
+  /** Why the preview could not be made (no pixels), for the UI. */
+  error = null;
+  /** A note for the UI, such as object aware refinement applying only on OK. */
+  note = null;
+  /** Bumped each time the preview changes, so a UI can redraw. */
+  revision = 0;
+  get settings() {
+    return this.settingsValue;
+  }
+  get edits() {
+    return this.editsList;
+  }
+  /** Reads the image and makes the first preview. Resolves to false when the pixels are unavailable. */
+  async open() {
+    try {
+      this.pixels = await this.controller.getSamplePixels({});
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+    if (!this.pixels) {
+      this.error ??= "The image pixels are not available, so Select and Mask cannot preview.";
+      this.emit();
+      return false;
+    }
+    this.rescale();
+    this.recompute();
+    return true;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit() {
+    this.revision++;
+    for (const l of this.listeners) l();
+  }
+  /** Preview size and the scale from natural pixels to it. */
+  get previewSize() {
+    const p = this.previewPixels;
+    if (!p || !this.pixels) return { width: 0, height: 0, scale: 1 };
+    return { width: p.width, height: p.height, scale: p.width / this.pixels.width };
+  }
+  /** Changes settings; the preview follows. Choosing a view also sets its usual opacity. */
+  update(changes) {
+    const next = { ...this.settingsValue, ...changes, params: { ...this.settingsValue.params, ...changes.params ?? {} } };
+    if (changes.view && changes.view !== this.settingsValue.view && changes.opacity === void 0) {
+      next.opacity = SELECT_AND_MASK_VIEWS.find((v) => v.id === changes.view).opacity;
+    }
+    const rescale = next.highQuality !== this.settingsValue.highQuality;
+    this.settingsValue = next;
+    if (rescale) this.rescale();
+    this.recompute();
+  }
+  rescale() {
+    const px2 = this.pixels;
+    if (!px2) return;
+    const s = this.settingsValue.highQuality ? 1 : Math.min(1, PREVIEW_SIZE / Math.max(px2.width, px2.height));
+    const w = Math.max(1, Math.round(px2.width * s));
+    const h = Math.max(1, Math.round(px2.height * s));
+    this.previewPixels = scalePixels(px2, w, h);
+    this.baseMask = this.base?.bounds ? s === 1 ? this.base : resizeSelection(this.base, w, h) : null;
+  }
+  /** Recomputes the preview mask from the base selection, the strokes and the settings. */
+  recompute() {
+    const px2 = this.previewPixels;
+    if (!px2) return;
+    const { scale } = this.previewSize;
+    const edits = [...this.editsList, ...this.live ? [this.live] : []].map((e) => scaleEdit(e, scale));
+    this.note = this.settingsValue.refineMode === "object" ? "Object aware refinement asks the segmentation model on OK; the preview refines by colour." : null;
+    try {
+      const { selection, refineBrush } = applyRefineEdits(px2, this.baseMask, edits, px2.width, px2.height);
+      this.previewMask = selection?.bounds ? refineSelection(px2, selection, scaleParams(this.settingsValue.params, scale), refineBrush) : null;
+      this.error = null;
+    } catch (err) {
+      this.previewMask = null;
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+    this.emit();
+  }
+  /** Coverage 0..1 of the preview at (x, y) in preview pixels (for tests and hover readouts). */
+  coverageAt(x, y) {
+    const m = this.settingsValue.showOriginal ? this.baseMask : this.previewMask;
+    if (!m) return 0;
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    if (xi < 0 || yi < 0 || xi >= m.width || yi >= m.height) return 0;
+    return m.data[yi * m.width + xi] / 255;
+  }
+  /** The preview drawn in the current view mode: RGBA at {@link previewSize}. */
+  render() {
+    const px2 = this.previewPixels;
+    if (!px2) return new Uint8ClampedArray(0);
+    const { width: w, height: h } = px2;
+    const n = w * h;
+    const s = this.settingsValue;
+    const mask = (s.showOriginal ? this.baseMask : this.previewMask) ?? createSelectionMask(w, h);
+    const m = mask.data;
+    const out = new Uint8ClampedArray(n * 4);
+    const k = Math.min(1, Math.max(0, s.opacity));
+    let edgeBand = null;
+    if (s.showEdge) {
+      edgeBand = new Uint8Array(n);
+      const r = Math.max(1, Math.round(Math.max(s.params.radius, 2) * this.previewSize.scale));
+      for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+          const v = m[y * w + x];
+          if (v <= 3 || v >= 252) continue;
+          for (let j = Math.max(0, y - r); j <= Math.min(h - 1, y + r); j++) edgeBand.fill(1, j * w + Math.max(0, x - r), j * w + Math.min(w, x + r + 1));
+        }
+      }
+    }
+    for (let i = 0; i < n; i++) {
+      const a = m[i] / 255;
+      const p = i * 4;
+      const r = px2.data[p];
+      const g = px2.data[p + 1];
+      const b = px2.data[p + 2];
+      let o;
+      const x = i % w;
+      const y = (i - x) / w;
+      const checker = ((x >> 3) + (y >> 3)) % 2 ? 204 : 255;
+      const hide = (1 - a) * k;
+      switch (s.view) {
+        case "black-white":
+          o = [m[i], m[i], m[i]];
+          break;
+        case "overlay":
+          o = [r + (255 - r) * hide, g * (1 - hide), b * (1 - hide)];
+          break;
+        case "on-black":
+          o = [r * (1 - hide), g * (1 - hide), b * (1 - hide)];
+          break;
+        case "on-white":
+          o = [r + (255 - r) * hide, g + (255 - g) * hide, b + (255 - b) * hide];
+          break;
+        case "marching-ants": {
+          o = [r, g, b];
+          const inside = m[i] >= 128;
+          const edge = x > 0 && m[i - 1] >= 128 !== inside || x + 1 < w && m[i + 1] >= 128 !== inside || y > 0 && m[i - w] >= 128 !== inside || y + 1 < h && m[i + w] >= 128 !== inside;
+          if (edge) {
+            const v = (x + y >> 2) % 2 ? 0 : 255;
+            o = [v, v, v];
+          }
+          break;
+        }
+        default:
+          o = [r + (checker - r) * hide, g + (checker - g) * hide, b + (checker - b) * hide];
+      }
+      if (edgeBand && !edgeBand[i]) o = [o[0] * 0.15, o[1] * 0.15, o[2] * 0.15];
+      out[p] = o[0];
+      out[p + 1] = o[1];
+      out[p + 2] = o[2];
+      out[p + 3] = 255;
+    }
+    return out;
+  }
+  /**
+   * Pointer down at `point` (natural pixels) with the current tool: starts a stroke (Quick
+   * Selection, brushes, lasso) or a box (Object Selection). Alt (or the subtract mode) removes.
+   * Hand and Zoom are the UI's own; they return false here.
+   */
+  begin(point, modifiers = {}) {
+    const s = this.settingsValue;
+    const mode = modifiers.altKey ? s.brushMode === "add" ? "subtract" : "add" : s.brushMode;
+    this.dragStart = point;
+    switch (s.tool) {
+      case "quick-select":
+        this.live = { kind: "quick-select", points: [point], size: s.brushSize, mode };
+        break;
+      case "brush":
+        this.live = { kind: "brush", points: [point], size: s.brushSize, mode };
+        break;
+      case "refine-brush":
+        this.live = { kind: "refine-brush", points: [point], size: s.brushSize };
+        break;
+      case "lasso":
+        this.live = { kind: "lasso", points: [point], mode };
+        break;
+      case "object":
+        this.live = { kind: "object", point, mode };
+        break;
+      default:
+        this.dragStart = null;
+        return false;
+    }
+    if (s.realTime && s.tool !== "lasso" && s.tool !== "object") this.recompute();
+    return true;
+  }
+  /** Pointer move while a stroke is down. */
+  move(point) {
+    const live = this.live;
+    if (!live || !this.dragStart) return;
+    if (live.kind === "object") {
+      const a = this.dragStart;
+      const rect = { x: Math.min(a.x, point.x), y: Math.min(a.y, point.y), width: Math.abs(point.x - a.x), height: Math.abs(point.y - a.y) };
+      this.live = rect.width >= 4 && rect.height >= 4 ? { kind: "object", rect, mode: live.mode } : { kind: "object", point: a, mode: live.mode };
+      return;
+    }
+    const last = live.points[live.points.length - 1];
+    if (Math.hypot(point.x - last.x, point.y - last.y) < 1) return;
+    live.points.push(point);
+    if (this.settingsValue.realTime && live.kind !== "lasso") this.recompute();
+  }
+  /** Pointer up: the stroke becomes an edit (one step of the workspace's own undo). */
+  end() {
+    const live = this.live;
+    this.live = null;
+    this.dragStart = null;
+    if (!live) return;
+    if (live.kind === "lasso" && live.points.length < 3) return;
+    this.editsList.push(live);
+    this.recompute();
+  }
+  /** Removes the last stroke (Ctrl/⌘+Z in the workspace). Returns false when there is none. */
+  undoEdit() {
+    if (!this.editsList.length) return false;
+    this.editsList.pop();
+    this.recompute();
+    return true;
+  }
+  /** Clears the strokes and goes back to the default settings (Reset). */
+  reset() {
+    this.editsList.length = 0;
+    this.settingsValue = { ...DEFAULT_SELECT_AND_MASK_SETTINGS, params: { ...DEFAULT_SELECT_AND_MASK_SETTINGS.params }, tool: this.settingsValue.tool };
+    this.rescale();
+    this.recompute();
+  }
+  /**
+   * Photoshop's keys in the workspace: a view letter, F (next view), X (all views off and on:
+   * Show Original), J (Show Edge), P (Show Original), a tool letter, [ and ] (brush size).
+   * Returns true when the key was used.
+   */
+  handleKey(key) {
+    const k = key.toLowerCase();
+    const view = SELECT_AND_MASK_VIEWS.find((v) => v.key === k);
+    if (view) {
+      this.update({ view: view.id });
+      return true;
+    }
+    const tool = SELECT_AND_MASK_TOOLS.find((t) => t.key === k);
+    if (tool) {
+      this.update({ tool: tool.id });
+      return true;
+    }
+    if (k === "f") {
+      const i = SELECT_AND_MASK_VIEWS.findIndex((v) => v.id === this.settingsValue.view);
+      this.update({ view: SELECT_AND_MASK_VIEWS[(i + 1) % SELECT_AND_MASK_VIEWS.length].id });
+      return true;
+    }
+    if (k === "p" || k === "x") {
+      this.update({ showOriginal: !this.settingsValue.showOriginal });
+      return true;
+    }
+    if (k === "j") {
+      this.update({ showEdge: !this.settingsValue.showEdge });
+      return true;
+    }
+    if (k === "[" || k === "]") {
+      const size = this.settingsValue.brushSize;
+      this.settingsValue = { ...this.settingsValue, brushSize: Math.max(1, Math.round(k === "]" ? size * 1.25 : size / 1.25)) };
+      this.emit();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * OK: applies the strokes and settings to the image as one undo step (the same call an agent
+   * makes) and remembers the settings when asked to.
+   */
+  async commit() {
+    const s = this.settingsValue;
+    remembered = s.remember ? { ...s, params: { ...s.params } } : null;
+    return this.controller.refineSelectionTo(s.params, s.output, {
+      edits: [...this.editsList],
+      decontaminate: s.output === "new-layer" || s.output === "new-layer-with-mask" ? s.decontaminate : 0,
+      refineMode: s.refineMode
+    });
+  }
+};
+function forgetSelectAndMaskSettings() {
+  remembered = null;
+}
+
 // src/image-editor/mosaic-filter.ts
 function resolveMosaicRegionBounds(region, imgWidth, imgHeight) {
   if (imgWidth <= 0 || imgHeight <= 0 || region.width <= 0 || region.height <= 0) {
@@ -20699,6 +21223,7 @@ export {
   DEFAULT_REFINE_EDGE_PARAMS,
   DEFAULT_RETOUCH,
   DEFAULT_SELECTION_TOOL_OPTIONS,
+  DEFAULT_SELECT_AND_MASK_SETTINGS,
   DEFAULT_SHAPE_TOOL_OPTIONS,
   DEFAULT_SMUDGE,
   DEFAULT_TEXT_STYLE,
@@ -20816,6 +21341,7 @@ export {
   PIGMENT_WAVELENGTHS,
   PLANE,
   PLANE_BYTES,
+  PREVIEW_SIZE,
   PROOF_PROFILE_OPTIONS,
   PSD_BLEND_KEYS,
   PSD_FILE_ACCEPT,
@@ -20840,6 +21366,7 @@ export {
   PsdError,
   QUICK_MASK_TARGET,
   REFINE_EDGE_CONTROLS,
+  REFINE_EDIT_KINDS,
   REFINE_OUTPUTS,
   RETOUCH_CHOICES,
   RETOUCH_OPTION_CONTROLS,
@@ -20852,6 +21379,8 @@ export {
   SELECTION_MODE_LABELS,
   SELECTION_MODIFY_OPS,
   SELECTION_TOOLS,
+  SELECT_AND_MASK_TOOLS,
+  SELECT_AND_MASK_VIEWS,
   SET_PLANES,
   SHADOW_AMBIENT,
   SHAPE_KIND_LABELS,
@@ -20865,6 +21394,7 @@ export {
   SRGB_TO_LINEAR,
   STRIP,
   SUPPORTED_ADJUSTMENT_KEYS,
+  SelectAndMaskSession,
   SelectionGesture,
   ShapeDrawGesture,
   SmudgeTip,
@@ -20952,6 +21482,7 @@ export {
   applyParams,
   applyProcess2Adjustments,
   applyProcess2Float,
+  applyRefineEdits,
   applyRegionBlur,
   applyRegionMosaic,
   applyRetouchToTile,
@@ -20984,6 +21515,7 @@ export {
   boxQuad,
   boxToCurvePoint,
   bradfordAdaptation,
+  brushStrokeMask,
   brushstrokeDataUrl,
   brushstrokeKey,
   brushstrokeSamples,
@@ -21184,6 +21716,7 @@ export {
   focusArea,
   followLayerMove,
   fontOf,
+  forgetSelectAndMaskSettings,
   formatControlValue,
   fullSelection,
   gaussianBlur,