@pixerate/editor 0.219.2 → 0.221.0

package/dist/{chunk-F7Z2MKY2.js → chunk-S6KKLFZO.js}

@@ -7,6 +7,7 @@ import {
   decodeSelectionRle,
   decontaminateColors,
   encodeSelectionRle,
+  guidedFilterColor,
   hashMaskContent,
   resizeSelection
 } from "./chunk-ZNA3IQZF.js";
@@ -94,6 +95,8 @@ import {
   spliceRuns,
   starSubpath,
   styleAt,
+  subpathSegment,
+  subpathSegmentCount,
   subpathsToBezier,
   textDecorations,
   textFragmentOutline,
@@ -106,6 +109,7 @@ import {
   bezierPathBounds,
   outlineStroke,
   pathBoolean,
+  segmentPoint,
   strokeOutlineRings,
   transformBezierPath
 } from "./chunk-WEIK3UYB.js";
@@ -1669,9 +1673,9 @@ function getProcess2Plan(adjustments) {
   const luts = [];
   const scale = [0, 0, 0];
   for (let c = 0; c < 3; c++) {
-    let reach = 0;
-    for (let k = 0; k < 3; k++) reach += Math.max(0, m[c * 3 + k]);
-    const headroom = Math.max(1, reach);
+    let reach2 = 0;
+    for (let k = 0; k < 3; k++) reach2 += Math.max(0, m[c * 3 + k]);
+    const headroom = Math.max(1, reach2);
     luts[c] = buildToneLut(contrast, brightness, headroom);
     scale[c] = TONE_LUT_SIZE / headroom;
   }
@@ -2946,12 +2950,224 @@ function annotationOfShape(layer) {
   return out;
 }
 
+// src/image-editor/layers/hybrid-mask.ts
+var VECTOR_MASK_EDGE_DEFAULTS = { radius: 4, inner: 4, outer: 8 };
+var JOIN_SIGMA = 2;
+function vectorMaskSegments(components) {
+  const out = [];
+  components.forEach((c, ci) => c.subpaths.forEach((sp, si) => {
+    for (let k = 0; k < subpathSegmentCount(sp); k++) out.push({ component: ci, subpath: si, segment: k });
+  }));
+  return out;
+}
+function validVectorMaskEdges(edges, components) {
+  if (!edges?.length) return [];
+  return edges.filter((e) => {
+    const sp = components[e.component]?.subpaths[e.subpath];
+    return Boolean(sp) && e.segment >= 0 && e.segment < subpathSegmentCount(sp);
+  });
+}
+function reach(e) {
+  return e.mode === "feather" ? 3 * (e.radius ?? VECTOR_MASK_EDGE_DEFAULTS.radius) : Math.max(e.inner ?? VECTOR_MASK_EDGE_DEFAULTS.inner, e.outer ?? VECTOR_MASK_EDGE_DEFAULTS.outer);
+}
+function hybridVectorMaskCoverage(vm, hard, width, height, guide) {
+  const edges = validVectorMaskEdges(vm.edges, vm.components).filter((e) => e.mode !== "hard");
+  if (!edges.length) return hard;
+  const classKey = (e) => e.mode === "feather" ? `f:${e.radius ?? VECTOR_MASK_EDGE_DEFAULTS.radius}` : `m:${e.inner ?? VECTOR_MASK_EDGE_DEFAULTS.inner}:${e.outer ?? VECTOR_MASK_EDGE_DEFAULTS.outer}`;
+  const classes = [{ key: "hard", edge: null }];
+  const classOfEdge = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const k = classKey(e);
+    if (!classes.some((c) => c.key === k)) classes.push({ key: k, edge: e });
+    classOfEdge.set(`${e.component}:${e.subpath}:${e.segment}`, classes.findIndex((c) => c.key === k));
+  }
+  const maxReach = Math.max(...edges.map(reach)) + 3 * JOIN_SIGMA + 2;
+  const seedX = [];
+  const seedY = [];
+  const seedClass = [];
+  vm.components.forEach(
+    (c, ci) => c.subpaths.forEach((sp, si) => {
+      for (let k = 0; k < subpathSegmentCount(sp); k++) {
+        const seg = subpathSegment(sp, k);
+        let len = 0;
+        for (let i = 1; i < seg.length; i++) len += Math.hypot(seg[i][0] - seg[i - 1][0], seg[i][1] - seg[i - 1][1]);
+        const steps = Math.max(2, Math.ceil(len * 2));
+        const cls2 = classOfEdge.get(`${ci}:${si}:${k}`) ?? 0;
+        for (let s = 0; s <= steps; s++) {
+          const [x, y] = segmentPoint(seg, s / steps);
+          seedX.push(x);
+          seedY.push(y);
+          seedClass.push(cls2);
+        }
+      }
+    })
+  );
+  if (!seedX.length) return hard;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < seedX.length; i++) {
+    if (seedX[i] < minX) minX = seedX[i];
+    if (seedX[i] > maxX) maxX = seedX[i];
+    if (seedY[i] < minY) minY = seedY[i];
+    if (seedY[i] > maxY) maxY = seedY[i];
+  }
+  const x0 = Math.max(0, Math.floor(minX - maxReach));
+  const y0 = Math.max(0, Math.floor(minY - maxReach));
+  const x1 = Math.min(width, Math.ceil(maxX + maxReach) + 1);
+  const y1 = Math.min(height, Math.ceil(maxY + maxReach) + 1);
+  const w = x1 - x0;
+  const h = y1 - y0;
+  if (w < 1 || h < 1) return hard;
+  const n = w * h;
+  const dist = new Float32Array(n).fill(Infinity);
+  const cls = new Int16Array(n);
+  for (let i = 0; i < seedX.length; i++) {
+    const x = Math.round(seedX[i]) - x0;
+    const y = Math.round(seedY[i]) - y0;
+    if (x < 0 || y < 0 || x >= w || y >= h) continue;
+    const k = y * w + x;
+    const d = Math.hypot(seedX[i] - (x + x0), seedY[i] - (y + y0));
+    if (d < dist[k]) {
+      dist[k] = d;
+      cls[k] = seedClass[i];
+    }
+  }
+  const D = Math.SQRT2;
+  const relax = (k, j, step) => {
+    const d = dist[j] + step;
+    if (d < dist[k]) {
+      dist[k] = d;
+      cls[k] = cls[j];
+    }
+  };
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const k = y * w + x;
+      if (x > 0) relax(k, k - 1, 1);
+      if (y > 0) {
+        relax(k, k - w, 1);
+        if (x > 0) relax(k, k - w - 1, D);
+        if (x < w - 1) relax(k, k - w + 1, D);
+      }
+    }
+  }
+  for (let y = h - 1; y >= 0; y--) {
+    for (let x = w - 1; x >= 0; x--) {
+      const k = y * w + x;
+      if (x < w - 1) relax(k, k + 1, 1);
+      if (y < h - 1) {
+        relax(k, k + w, 1);
+        if (x < w - 1) relax(k, k + w + 1, D);
+        if (x > 0) relax(k, k + w - 1, D);
+      }
+    }
+  }
+  const out = Float32Array.from(hard);
+  const pad = maxReach + 3 * JOIN_SIGMA + 2;
+  const T = 128;
+  for (let ty = 0; ty < h; ty += T) {
+    for (let tx = 0; tx < w; tx += T) {
+      const tw = Math.min(T, w - tx);
+      const th = Math.min(T, h - ty);
+      let active = false;
+      for (let y = ty; y < ty + th && !active; y++) for (let x = tx; x < tx + tw; x++) if (dist[y * w + x] <= maxReach) {
+        active = true;
+        break;
+      }
+      if (!active) continue;
+      const px0 = Math.max(0, tx - pad);
+      const py0 = Math.max(0, ty - pad);
+      const px1 = Math.min(w, tx + tw + pad);
+      const py1 = Math.min(h, ty + th + pad);
+      const result = solveTile(px0, py0, px1 - px0, py1 - py0);
+      for (let y = ty; y < ty + th; y++) {
+        for (let x = tx; x < tx + tw; x++) {
+          const k = y * w + x;
+          if (dist[k] > maxReach + 3 * JOIN_SIGMA) continue;
+          const v = result[(y - py0) * (px1 - px0) + (x - px0)];
+          if (!Number.isNaN(v)) out[(y + y0) * width + x + x0] = v;
+        }
+      }
+    }
+  }
+  return out;
+  function solveTile(bx, by, bw, bh) {
+    const m = bw * bh;
+    const at = (x, y) => (by + y) * w + bx + x;
+    const Ht = new Float32Array(m);
+    for (let y = 0; y < bh; y++) for (let x = 0; x < bw; x++) Ht[y * bw + x] = hard[(by + y + y0) * width + bx + x + x0];
+    const total = new Float32Array(m);
+    const blended = new Float32Array(m);
+    let guidePlanes = null;
+    const planes = () => {
+      if (guidePlanes) return guidePlanes;
+      const p = [new Float32Array(m), new Float32Array(m), new Float32Array(m)];
+      for (let y = 0; y < bh; y++) {
+        for (let x = 0; x < bw; x++) {
+          const s = ((by + y + y0) * width + bx + x + x0) * 4;
+          const a = guide[s + 3] / 255;
+          for (let c = 0; c < 3; c++) p[c][y * bw + x] = guide[s + c] / 255 * a;
+        }
+      }
+      return guidePlanes = p;
+    };
+    for (let c = 0; c < classes.length; c++) {
+      let weight = new Float32Array(m);
+      let any = false;
+      for (let y = 0; y < bh; y++) {
+        for (let x = 0; x < bw; x++) {
+          const k = at(x, y);
+          const mine = dist[k] <= maxReach ? cls[k] === c : c === 0;
+          if (mine) {
+            weight[y * bw + x] = 1;
+            any = true;
+          }
+        }
+      }
+      if (!any) continue;
+      weight = gaussianBlur(weight, bw, bh, JOIN_SIGMA, "clamp");
+      const e = classes[c].edge;
+      let cov;
+      if (!e) cov = Ht;
+      else if (e.mode === "feather" || !guide) {
+        const sigma = e.mode === "feather" ? e.radius ?? VECTOR_MASK_EDGE_DEFAULTS.radius : ((e.inner ?? VECTOR_MASK_EDGE_DEFAULTS.inner) + (e.outer ?? VECTOR_MASK_EDGE_DEFAULTS.outer)) / 3;
+        cov = gaussianBlur(Ht, bw, bh, sigma, "clamp");
+      } else {
+        const inner = e.inner ?? VECTOR_MASK_EDGE_DEFAULTS.inner;
+        const outer = e.outer ?? VECTOR_MASK_EDGE_DEFAULTS.outer;
+        const r = Math.max(2, Math.round((inner + outer) / 2));
+        const q2 = guidedFilterColor(planes(), Ht, bw, bh, r);
+        cov = new Float32Array(m);
+        for (let y = 0; y < bh; y++) {
+          for (let x = 0; x < bw; x++) {
+            const i = y * bw + x;
+            const inside = Ht[i] >= 0.5;
+            const d = dist[at(x, y)];
+            const unknown = inside ? d <= inner : d <= outer;
+            cov[i] = unknown ? Math.min(1, Math.max(0, q2[i])) : inside ? 1 : 0;
+          }
+        }
+      }
+      for (let i = 0; i < m; i++) {
+        total[i] += weight[i];
+        blended[i] += weight[i] * cov[i];
+      }
+    }
+    const res = new Float32Array(m);
+    for (let i = 0; i < m; i++) res[i] = total[i] > 0 ? blended[i] / total[i] : NaN;
+    return res;
+  }
+}
+
 // src/image-editor/layers/vector-mask.ts
 function isActiveVectorMask(vm) {
   return Boolean(vm && vm.enabled !== false);
 }
-function vectorMaskCoverage(vm, width, height) {
+function vectorMaskCoverage(vm, width, height, guide = null) {
   let v = componentsCoverage(vm.components, { x: 0, y: 0, width, height }, vm.fillRule ?? "nonzero", vm.inverted === true);
+  if (vm.edges?.length) v = hybridVectorMaskCoverage(vm, v, width, height, guide);
   if ((vm.feather ?? 0) > 0) v = gaussianBlur(v, width, height, vm.feather, "clamp");
   const density = vm.density ?? 1;
   if (density !== 1) for (let i = 0; i < v.length; i++) v[i] = 1 - density * (1 - v[i]);
@@ -2970,12 +3186,18 @@ function rasterCoverage(mask, ox, oy, width, height) {
   return v;
 }
 var layerOffset = (layer) => layer.type === "pixel" ? layer.offset : { x: 0, y: 0 };
-function effectiveLayerMask(layer, width, height) {
+function layerGuide(layer, width, height, surfaceOf) {
+  const surface = surfaceOf?.(layer) ?? layer.surface;
+  if (!surface || surface.channels !== 4) return null;
+  const { x: ox, y: oy } = layerOffset(layer);
+  return readRegion(surface, { x: -ox, y: -oy, width, height });
+}
+function effectiveLayerMask(layer, width, height, surfaceOf) {
   const vm = layer.vectorMask;
   const raster = layer.mask;
   if (!isActiveVectorMask(vm) || raster?.source || width < 1 || height < 1) return raster;
   const { x: ox, y: oy } = layerOffset(layer);
-  const v = vectorMaskCoverage(vm, width, height);
+  const v = vectorMaskCoverage(vm, width, height, vm.edges?.length ? layerGuide(layer, width, height, surfaceOf) : null);
   let outside = outsideValue(vm);
   if (raster && raster.enabled !== false) {
     const r = rasterCoverage(raster, ox, oy, width, height);
@@ -2995,17 +3217,17 @@ function hasVectorMask(layers) {
   }
   return false;
 }
-function resolveVectorMasks(layers, width, height) {
+function resolveVectorMasks(layers, width, height, surfaceOf) {
   if (!hasVectorMask(layers)) return layers;
-  return layers.map((l) => resolveLayer(l, width, height));
+  return layers.map((l) => resolveLayer(l, width, height, surfaceOf));
 }
-function resolveLayer(layer, width, height) {
+function resolveLayer(layer, width, height, surfaceOf) {
   let next = layer;
   if (layer.type === "group" && hasVectorMask(layer.children)) {
     const key2 = `${width}x${height}`;
     const hit2 = resolved.get(layer);
     if (hit2?.key === key2) return hit2.layer;
-    next = { ...layer, children: layer.children.map((c) => resolveLayer(c, width, height)) };
+    next = { ...layer, children: layer.children.map((c) => resolveLayer(c, width, height, surfaceOf)) };
     if (!isActiveVectorMask(layer.vectorMask)) {
       resolved.set(layer, { key: key2, layer: next });
       return next;
@@ -3015,7 +3237,7 @@ function resolveLayer(layer, width, height) {
   const key = `${width}x${height}:v`;
   const hit = resolved.get(layer);
   if (hit?.key === key) return hit.layer;
-  const mask = effectiveLayerMask(layer, width, height);
+  const mask = effectiveLayerMask(layer, width, height, surfaceOf);
   const out = { ...next, mask };
   delete out.vectorMask;
   if (!mask) delete out.mask;
@@ -3560,6 +3782,11 @@ function filterReach(filters) {
   return r;
 }
 var filterSpecCache = /* @__PURE__ */ new WeakMap();
+function guideSurfaces(sources) {
+  const of = sources.surfaceOf;
+  if (!of) return void 0;
+  return (l) => l.type === "pixel" || l.type === "smart" ? of(l) : void 0;
+}
 var maskIds = /* @__PURE__ */ new WeakMap();
 var nextMaskId = 1;
 var edgeSpecCache = /* @__PURE__ */ new WeakMap();
@@ -3633,13 +3860,13 @@ var LayerCompositor = class extends RasterCompositor {
   }
   // Vector masks reach the engine as part of each layer's raster mask (see `resolveVectorMasks`).
   composite(layers, rect, sources, options) {
-    return super.composite(resolveVectorMasks(layers, sources.width, sources.height), rect, sources, options);
+    return super.composite(resolveVectorMasks(layers, sources.width, sources.height, guideSurfaces(sources)), rect, sources, options);
   }
   compositeTiles(layers, rect, sources, onTile, options) {
-    super.compositeTiles(resolveVectorMasks(layers, sources.width, sources.height), rect, sources, onTile, options);
+    super.compositeTiles(resolveVectorMasks(layers, sources.width, sources.height, guideSurfaces(sources)), rect, sources, onTile, options);
   }
   tile(layers, tx, ty, sources) {
-    return super.tile(resolveVectorMasks(layers, sources.width, sources.height), tx, ty, sources);
+    return super.tile(resolveVectorMasks(layers, sources.width, sources.height, guideSurfaces(sources)), tx, ty, sources);
   }
 };
 function compositeDeep(layers, rect, sources, depth) {
@@ -3652,7 +3879,7 @@ function compositeDeep(layers, rect, sources, depth) {
       return { reach: filterReach(filters), apply: (data, width, height, linear) => runLayerFiltersFloat(data, width, height, filters, linear) };
     }
   }, depth);
-  return deep.composite(resolveVectorMasks(layers, sources.width, sources.height), rect, sources);
+  return deep.composite(resolveVectorMasks(layers, sources.width, sources.height, guideSurfaces(sources)), rect, sources);
 }
 
 // src/image-editor/layers/text.ts
@@ -5268,6 +5495,7 @@ function serializeVectorMask(vm) {
   if (vm.linked === false) out.linked = false;
   if (vm.density !== void 0 && vm.density !== 1) out.density = vm.density;
   if (vm.feather) out.feather = vm.feather;
+  if (vm.edges?.length) out.edges = vm.edges.map((e) => ({ ...e }));
   return out;
 }
 function readShapeComponents(stored) {
@@ -5290,6 +5518,19 @@ function readVectorMask(r) {
   if (r.linked === false) vm.linked = false;
   if (typeof r.density === "number" && r.density !== 1) vm.density = num2(r.density, 0, 1, 1);
   if (typeof r.feather === "number" && r.feather > 0) vm.feather = num2(r.feather, 0, 1e3, 0);
+  if (Array.isArray(r.edges)) {
+    const edges = [];
+    for (const raw of r.edges) {
+      const e = raw;
+      const int = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : -1;
+      const at = { component: int(e?.component), subpath: int(e?.subpath), segment: int(e?.segment) };
+      if (at.component < 0 || at.subpath < 0 || at.segment < 0) continue;
+      if (e.mode === "feather") edges.push({ ...at, mode: "feather", radius: num2(e.radius, 0.5, 250, 4) });
+      else if (e.mode === "matte") edges.push({ ...at, mode: "matte", inner: num2(e.inner, 0.5, 200, 4), outer: num2(e.outer, 0.5, 200, 8) });
+    }
+    const valid = validVectorMaskEdges(edges, vm.components);
+    if (valid.length) vm.edges = valid;
+  }
   return vm;
 }
 function serializeMask(mask, hint, ctx) {
@@ -11646,8 +11887,13 @@ export {
   shapeFromAnnotation,
   annotationBlend,
   annotationOfShape,
+  VECTOR_MASK_EDGE_DEFAULTS,
+  vectorMaskSegments,
+  validVectorMaskEdges,
+  hybridVectorMaskCoverage,
   isActiveVectorMask,
   vectorMaskCoverage,
+  layerGuide,
   effectiveLayerMask,
   resolveVectorMasks,
   offsetVectorMask,

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

@@ -1,5 +1,6 @@
 import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState, DocumentOpener } from './types.cjs';
 import { type InspectMaskEdgeOptions, type MaskEdgeReport } from './selection/inspect.cjs';
+import { type SelectionRecipeStep } from './selection/recipe.cjs';
 import { type CompareSelectionsOptions, type SelectionDiff } from './selection/diff.cjs';
 import { type SelectionUncertainty, type SelectionUncertaintyOptions } from './selection/uncertainty.cjs';
 import { type PathToSelectionOptions, type SelectionToPathOptions } from './selection/path.cjs';
@@ -10,6 +11,7 @@ import { type SelectionJob, type SelectionJobResult, type SelectionWorkerFactory
 import type { SelectionProgress } from './selection/segment/work.cjs';
 import type { FocusAreaOptions } from './selection/segment/focus.cjs';
 import type { SkyOptions } from './selection/segment/sky.cjs';
+import { type VectorMaskEdgeMode } from './layers/hybrid-mask.cjs';
 import { RenderOptions } from './renderer.cjs';
 import { type BlendMode } from './blend.cjs';
 import type { ImageHistogram } from './histogram.cjs';
@@ -23,7 +25,7 @@ import { type RefineEdit } from './selection/refine-edits.cjs';
 import { type LayerMaskProps } from './selection/layer-mask.cjs';
 import { type AlphaChannel } from './selection/channels.cjs';
 import type { AdjustmentLayerMask } from './types.cjs';
-import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeComponent, type ShapeFillRule, type VectorMask, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TextOrientation, type TypeLayer, type ImageEffectAnimation } from './layers/model.cjs';
+import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeComponent, type ShapeFillRule, type VectorMask, type VectorMaskEdge, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TextOrientation, type TypeLayer, type ImageEffectAnimation } from './layers/model.cjs';
 import { type TextLayout, type TextShaper } from './layers/text.cjs';
 import type { VectorSubpath } from '../vector/types.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
@@ -345,6 +347,10 @@ export interface VectorMaskInfo {
         live: LiveShape | null;
         subpaths: VectorSubpath[];
     }>;
+    /** Hybrid mask: the segments with a soft edge mode (the rest are hard). */
+    edges: VectorMaskEdge[];
+    /** How many segments the path has (`{ component, subpath, segment }` address each). */
+    segmentCount: number;
 }
 export interface ShapeGeometryInput {
     shape?: LiveShape | Record<string, unknown>;
@@ -740,10 +746,6 @@ export declare function migrateToLayeredState(data: Partial<SerializedImageEdito
 }, size: ImageDimensions): SerializedLayeredImageEditorState;
 export declare const DEFAULT_TRANSFORM: ImageTransform;
 export declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
-/**
- * ImageEditorController manages the complete lifecycle, canvas rendering pipeline,
- * tool interaction states, undo/redo history, serialization, and image export.
- */
 export declare class ImageEditorController {
     private state;
     private renderer;
@@ -1028,6 +1030,8 @@ export declare class ImageEditorController {
     /** Changes whenever the Background's source pixels can have changed. */
     private sourceVersion;
     /** The pixels a pixel layer, smart object or shape composites (the decoded source for the Background). */
+    /** A layer's real pixels for hybrid vector masks' matte guide (the Background's from the source). */
+    private readonly guideSurfaceOf;
     private surfaceOf;
     /**
      * The source image as a surface (cached): host-supplied sample pixels first, then the decoded
@@ -1237,6 +1241,23 @@ export declare class ImageEditorController {
     selectionFromVectorMask(id: string, mode?: SelectionMode, invert?: boolean): boolean;
     /** A layer's vector mask with its paths (rounded), or `null` without one. */
     getVectorMask(id: string): VectorMaskInfo | null;
+    /**
+     * Hybrid mask: a vector mask segment's edge mode. `hard` (the default) is the path's own sharp
+     * edge; `feather` blurs across it by `radius` px (default 4); `matte` solves a corridor from
+     * `inner` px inside to `outer` px outside (defaults 4 and 8) from the layer's colours, for hair
+     * and fur. Modes blend where they meet. One undo step. Returns the vector mask's info.
+     */
+    setVectorMaskEdge(id: string, at: {
+        component: number;
+        subpath: number;
+        segment: number;
+    }, mode: VectorMaskEdgeMode, options?: {
+        radius?: number;
+        inner?: number;
+        outer?: number;
+    }, commitToHistory?: boolean): VectorMaskInfo;
+    /** A layer's vector mask over the canvas as a selection mask, hybrid edges, feather and density included. */
+    private vectorMaskSelection;
     /** Changes any layer mask's density, feather, enabled or linked flag (pixels kept). Returns the mask. */
     setLayerMaskProps(id: string, props: LayerMaskProps, commitToHistory?: boolean): RasterMask;
     /**
@@ -1778,6 +1799,32 @@ export declare class ImageEditorController {
      * Returns false when nothing changed.
      */
     setSelection(mask: SelectionMask | null, mode?: SelectionMode): boolean;
+    /** The recipe step of the selection command now running, taken by `setSelection`. */
+    private pendingStep;
+    /** Runs a selection command whose change `step` describes, so the selection's recipe records it. */
+    private withRecipeStep;
+    /** The selection's recipe as agents and panels read it (empty and not live when frozen or empty). */
+    getSelectionRecipe(): {
+        live: boolean;
+        steps: Array<{
+            index: number;
+        } & SelectionRecipeStep>;
+    };
+    private requireRecipe;
+    /**
+     * Replaces the selection's recipe with `steps` (checked first) and the selection with what they
+     * make, from nothing. One undo step; nothing changes on an error. Returns the recipe.
+     */
+    setSelectionRecipe(steps: readonly unknown[]): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Changes step `index` of the selection's recipe (fields given replace its own; `op` replaces it whole) and replays. One undo step. */
+    editSelectionStep(index: number, changes: Record<string, unknown>): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Inserts a step at `index` (0..length; length appends) and replays. One undo step. */
+    insertSelectionStep(index: number, step: unknown): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Removes step `index` and replays (the last step cannot go: deselect instead). One undo step. */
+    removeSelectionStep(index: number): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Drops the selection's recipe, keeping the selection as it is (a plain bitmap). One undo step. */
+    freezeSelection(): boolean;
+    private recipeIndex;
     /**
      * Shows `mask` in place of the selection while a gesture runs (Quick Selection as the brush
      * moves; `null` shows nothing selected), or with `undefined` stops. View state only: no undo

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

@@ -1,5 +1,6 @@
 import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState, DocumentOpener } from './types.js';
 import { type InspectMaskEdgeOptions, type MaskEdgeReport } from './selection/inspect.js';
+import { type SelectionRecipeStep } from './selection/recipe.js';
 import { type CompareSelectionsOptions, type SelectionDiff } from './selection/diff.js';
 import { type SelectionUncertainty, type SelectionUncertaintyOptions } from './selection/uncertainty.js';
 import { type PathToSelectionOptions, type SelectionToPathOptions } from './selection/path.js';
@@ -10,6 +11,7 @@ import { type SelectionJob, type SelectionJobResult, type SelectionWorkerFactory
 import type { SelectionProgress } from './selection/segment/work.js';
 import type { FocusAreaOptions } from './selection/segment/focus.js';
 import type { SkyOptions } from './selection/segment/sky.js';
+import { type VectorMaskEdgeMode } from './layers/hybrid-mask.js';
 import { RenderOptions } from './renderer.js';
 import { type BlendMode } from './blend.js';
 import type { ImageHistogram } from './histogram.js';
@@ -23,7 +25,7 @@ import { type RefineEdit } from './selection/refine-edits.js';
 import { type LayerMaskProps } from './selection/layer-mask.js';
 import { type AlphaChannel } from './selection/channels.js';
 import type { AdjustmentLayerMask } from './types.js';
-import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeComponent, type ShapeFillRule, type VectorMask, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TextOrientation, type TypeLayer, type ImageEffectAnimation } from './layers/model.js';
+import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeComponent, type ShapeFillRule, type VectorMask, type VectorMaskEdge, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TextOrientation, type TypeLayer, type ImageEffectAnimation } from './layers/model.js';
 import { type TextLayout, type TextShaper } from './layers/text.js';
 import type { VectorSubpath } from '../vector/types.js';
 import { EffectsSlot } from '../effects/helpers.js';
@@ -345,6 +347,10 @@ export interface VectorMaskInfo {
         live: LiveShape | null;
         subpaths: VectorSubpath[];
     }>;
+    /** Hybrid mask: the segments with a soft edge mode (the rest are hard). */
+    edges: VectorMaskEdge[];
+    /** How many segments the path has (`{ component, subpath, segment }` address each). */
+    segmentCount: number;
 }
 export interface ShapeGeometryInput {
     shape?: LiveShape | Record<string, unknown>;
@@ -740,10 +746,6 @@ export declare function migrateToLayeredState(data: Partial<SerializedImageEdito
 }, size: ImageDimensions): SerializedLayeredImageEditorState;
 export declare const DEFAULT_TRANSFORM: ImageTransform;
 export declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
-/**
- * ImageEditorController manages the complete lifecycle, canvas rendering pipeline,
- * tool interaction states, undo/redo history, serialization, and image export.
- */
 export declare class ImageEditorController {
     private state;
     private renderer;
@@ -1028,6 +1030,8 @@ export declare class ImageEditorController {
     /** Changes whenever the Background's source pixels can have changed. */
     private sourceVersion;
     /** The pixels a pixel layer, smart object or shape composites (the decoded source for the Background). */
+    /** A layer's real pixels for hybrid vector masks' matte guide (the Background's from the source). */
+    private readonly guideSurfaceOf;
     private surfaceOf;
     /**
      * The source image as a surface (cached): host-supplied sample pixels first, then the decoded
@@ -1237,6 +1241,23 @@ export declare class ImageEditorController {
     selectionFromVectorMask(id: string, mode?: SelectionMode, invert?: boolean): boolean;
     /** A layer's vector mask with its paths (rounded), or `null` without one. */
     getVectorMask(id: string): VectorMaskInfo | null;
+    /**
+     * Hybrid mask: a vector mask segment's edge mode. `hard` (the default) is the path's own sharp
+     * edge; `feather` blurs across it by `radius` px (default 4); `matte` solves a corridor from
+     * `inner` px inside to `outer` px outside (defaults 4 and 8) from the layer's colours, for hair
+     * and fur. Modes blend where they meet. One undo step. Returns the vector mask's info.
+     */
+    setVectorMaskEdge(id: string, at: {
+        component: number;
+        subpath: number;
+        segment: number;
+    }, mode: VectorMaskEdgeMode, options?: {
+        radius?: number;
+        inner?: number;
+        outer?: number;
+    }, commitToHistory?: boolean): VectorMaskInfo;
+    /** A layer's vector mask over the canvas as a selection mask, hybrid edges, feather and density included. */
+    private vectorMaskSelection;
     /** Changes any layer mask's density, feather, enabled or linked flag (pixels kept). Returns the mask. */
     setLayerMaskProps(id: string, props: LayerMaskProps, commitToHistory?: boolean): RasterMask;
     /**
@@ -1778,6 +1799,32 @@ export declare class ImageEditorController {
      * Returns false when nothing changed.
      */
     setSelection(mask: SelectionMask | null, mode?: SelectionMode): boolean;
+    /** The recipe step of the selection command now running, taken by `setSelection`. */
+    private pendingStep;
+    /** Runs a selection command whose change `step` describes, so the selection's recipe records it. */
+    private withRecipeStep;
+    /** The selection's recipe as agents and panels read it (empty and not live when frozen or empty). */
+    getSelectionRecipe(): {
+        live: boolean;
+        steps: Array<{
+            index: number;
+        } & SelectionRecipeStep>;
+    };
+    private requireRecipe;
+    /**
+     * Replaces the selection's recipe with `steps` (checked first) and the selection with what they
+     * make, from nothing. One undo step; nothing changes on an error. Returns the recipe.
+     */
+    setSelectionRecipe(steps: readonly unknown[]): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Changes step `index` of the selection's recipe (fields given replace its own; `op` replaces it whole) and replays. One undo step. */
+    editSelectionStep(index: number, changes: Record<string, unknown>): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Inserts a step at `index` (0..length; length appends) and replays. One undo step. */
+    insertSelectionStep(index: number, step: unknown): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Removes step `index` and replays (the last step cannot go: deselect instead). One undo step. */
+    removeSelectionStep(index: number): Promise<ReturnType<ImageEditorController['getSelectionRecipe']>>;
+    /** Drops the selection's recipe, keeping the selection as it is (a plain bitmap). One undo step. */
+    freezeSelection(): boolean;
+    private recipeIndex;
     /**
      * Shows `mask` in place of the selection while a gesture runs (Quick Selection as the brush
      * moves; `null` shows nothing selected), or with `undefined` stops. View state only: no undo