@pixerate/editor 0.189.0 → 0.190.0

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

@@ -36,6 +36,7 @@ export * from './layers/ops.cjs';
 export * from './layers/smart.cjs';
 export * from './smart-tools.cjs';
 export * from './layers/shape.cjs';
+export * from './layers/vector-mask.cjs';
 export * from './shape-tools.cjs';
 export * from './layers/text.cjs';
 export * from './layers/text-shapers.cjs';

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

@@ -36,6 +36,7 @@ export * from './layers/ops.js';
 export * from './layers/smart.js';
 export * from './smart-tools.js';
 export * from './layers/shape.js';
+export * from './layers/vector-mask.js';
 export * from './shape-tools.js';
 export * from './layers/text.js';
 export * from './layers/text-shapers.js';

package/dist/image-editor/index.js

@@ -99,6 +99,7 @@ import {
   combineSelections,
   compileAdjustmentLayer,
   componentPath,
+  componentsCoverage,
   compositeDeep,
   computeSelectionBounds,
   contentsBox,
@@ -137,6 +138,7 @@ import {
   distanceTransform,
   documentContents,
   duplicateLayer,
+  effectiveLayerMask,
   encodeDeepSurface,
   encodeRle,
   encodeSelectionRle,
@@ -148,6 +150,7 @@ import {
   filterMaskCoverage,
   flattenPath,
   flipCorners,
+  followLayerMove,
   fullSelection,
   geometryHomography,
   getAnnotationBounds,
@@ -177,6 +180,7 @@ import {
   invertMatrix3,
   invertSelection,
   isActiveFilter,
+  isActiveVectorMask,
   isAdjustmentKind,
   isContentsDecoded,
   isDefaultDepthMask,
@@ -237,6 +241,7 @@ import {
   offsetLayer,
   offsetShape,
   offsetSmartObject,
+  offsetVectorMask,
   parseAdjustmentBlock,
   parseBlend,
   parseLfx2,
@@ -290,6 +295,7 @@ import {
   rerenderText,
   resizeSelection,
   resolveExternalAssets,
+  resolveVectorMasks,
   rgbToGray,
   rgbToHsl,
   runLayerFilters,
@@ -341,6 +347,7 @@ import {
   transformMap,
   transformShapeComponents,
   transformTypeLayer,
+  transformVectorMask,
   transformedBox,
   transformedPoint,
   translateLayer,
@@ -359,6 +366,9 @@ import {
   updateTypeLayer,
   userErrorMessage,
   uvToXy,
+  vectorMaskBounds,
+  vectorMaskCoverage,
+  vectorMaskThumbnail,
   versionedDescriptorBytes,
   vibranceLinear,
   vibrancePixel,
@@ -373,7 +383,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-ZEHTUR7Z.js";
+} from "../chunk-7ZWLDVFH.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -4164,6 +4174,24 @@ var FreeTransformSession = class {
   }
   /** Resamples every part for the current geometry and shows it (or returns it, for commit). */
   resample(final, preview = {}) {
+    const out = this.resampleContent(final, preview);
+    return { ...out, layers: this.moveVectorMask(out.layers) };
+  }
+  /** A linked vector mask follows the layer's content through the same document-space map. */
+  moveVectorMask(layers) {
+    const g = this.geometryValue;
+    if (!this.layerId || this.copyId || !this.moves.includes("pixels") || isIdentityTransform(g)) return layers;
+    const vm = findLayer(layers, this.layerId)?.layer.vectorMask;
+    if (!vm || vm.linked === false) return layers;
+    const warp = hasWarp(g);
+    const f = warp ? transformMap(g) : null;
+    const h = warp ? null : geometryHomography(g);
+    const affine = !warp && h && Math.abs(h[6]) < 1e-12 && Math.abs(h[7]) < 1e-12 && Math.abs(h[8] - 1) < 1e-12 ? [h[0], h[3], h[1], h[4], h[2], h[5]] : void 0;
+    const map = (p) => (f ? f(p) : h ? applyHomography(h, p) : p) ?? p;
+    const moved = transformVectorMask(vm, map, affine);
+    return mapLayer(layers, this.layerId, (l) => ({ ...l, vectorMask: moved }));
+  }
+  resampleContent(final, preview = {}) {
     if (this.smart) return { layers: this.resampleSmart(final, preview), selection: this.startSelection };
     if (this.typeTarget) return { layers: this.resampleType(), selection: this.startSelection };
     const g = this.geometryValue;
@@ -6167,6 +6195,7 @@ var ImageEditorController = class {
       let moved = { ...transformTypeLayer(layer, [1, 0, 0, 1, mx, my]), surface: translateSurface(layer.surface, mx, my) };
       const mask = layer.mask;
       if (mask && mask.linked !== false && !mask.source && (mx || my)) moved = { ...moved, mask: { ...mask, surface: translateSurface(mask.surface, mx, my) } };
+      moved = followLayerMove(moved, mx, my);
       this.commitLayers(mapLayer(this.state.layers, id, () => moved), void 0, commitToHistory);
       const t = moved.transform ?? [1, 0, 0, 1, 0, 0];
       return { offset: { x: Math.round(t[4]), y: Math.round(t[5]) }, bounds: this.getLayerBounds(id) };
@@ -6218,6 +6247,139 @@ var ImageEditorController = class {
       if (this.state.activeLayerId === id) this.state.activeTarget = "pixels";
     });
   }
+  // --- Vector masks ---
+  /** The layer for a vector mask command: not a shape layer (its path is its vector mask), not a depth-masked one. */
+  vectorMaskLayer(id) {
+    const layer = requireLayer(this.state.layers, id).layer;
+    const name = layer.name || id;
+    if (layer.type === "shape") throw new LayerOperationError(`Layer "${name}" is a shape layer, whose path already is its vector mask; change it with set_shape_component, or rasterize the layer first.`);
+    if (layer.mask?.source) throw new LayerOperationError(`Layer "${name}" has a depth mask, which cannot be combined with a vector mask; remove the depth mask first.`);
+    return layer;
+  }
+  requireVectorMask(id) {
+    const layer = this.vectorMaskLayer(id);
+    if (!layer.vectorMask) throw new LayerOperationError(`Layer "${layer.name || id}" has no vector mask; add one with add_vector_mask.`);
+    return { layer, vm: layer.vectorMask };
+  }
+  /** Components from a path spec: `components`, or one `shape` / `subpaths`. */
+  vectorMaskComponents(path) {
+    if (path.components?.length && (path.shape !== void 0 || path.subpaths !== void 0)) throw new LayerOperationError("Give components, or shape / subpaths, not both.");
+    if (path.fillRule !== void 0 && path.fillRule !== "nonzero" && path.fillRule !== "evenodd") throw new LayerOperationError("fillRule must be nonzero or evenodd.");
+    const specs = path.components?.length ? path.components : [path];
+    return specs.map((c, i) => this.componentFrom(c, path.components?.length ? `components[${i}].` : ""));
+  }
+  /**
+   * Layer › Vector Mask: `reveal-all` (an empty path showing everything), `hide-all` (an empty path
+   * hiding everything) or `path` (reveals inside the path given). Replaces an existing vector mask;
+   * the raster mask is kept and both apply. One undo step. Returns the vector mask.
+   */
+  addVectorMask(id, from = "reveal-all", path = {}) {
+    this.vectorMaskLayer(id);
+    let vm;
+    if (from === "path") {
+      vm = { components: this.vectorMaskComponents(path) };
+      if (path.fillRule === "evenodd") vm.fillRule = "evenodd";
+    } else if (from === "reveal-all" || from === "hide-all") {
+      if (path.components?.length || path.shape !== void 0 || path.subpaths !== void 0) throw new LayerOperationError(`A ${from} vector mask starts empty; use from path to give a path.`);
+      vm = { components: [], ...from === "reveal-all" ? { inverted: true } : {} };
+    } else {
+      throw new LayerOperationError(`Unknown vector mask source "${String(from)}". Use reveal-all, hide-all or path.`);
+    }
+    this.commitLayers(mapLayer(this.state.layers, id, (l) => ({ ...l, vectorMask: vm })));
+    return vm;
+  }
+  /** Replaces a vector mask's path (its properties are kept). One undo step. Returns the vector mask. */
+  setVectorMaskPath(id, path) {
+    const { vm } = this.requireVectorMask(id);
+    const next = { ...vm, components: this.vectorMaskComponents(path) };
+    if (path.fillRule === "evenodd") next.fillRule = "evenodd";
+    else if (path.fillRule === "nonzero") delete next.fillRule;
+    this.commitLayers(mapLayer(this.state.layers, id, (l) => ({ ...l, vectorMask: next })));
+    return next;
+  }
+  /** Changes a vector mask's enabled, linked, inverted, density or feather (the path is kept). One undo step. */
+  setVectorMaskProps(id, props) {
+    const { vm } = this.requireVectorMask(id);
+    if (props.density !== void 0 && !(props.density >= 0 && props.density <= 1)) throw new LayerOperationError("density must be from 0 to 1.");
+    if (props.feather !== void 0 && !(props.feather >= 0 && props.feather <= 1e3)) throw new LayerOperationError("feather must be from 0 to 1000 px.");
+    const next = { ...vm };
+    for (const k of ["enabled", "linked", "inverted"]) {
+      if (props[k] === void 0) continue;
+      if (typeof props[k] !== "boolean") throw new LayerOperationError(`${k} must be true or false.`);
+      if (k === "inverted" ? props[k] : !props[k]) next[k] = k === "inverted";
+      else delete next[k];
+    }
+    if (props.density !== void 0) {
+      if (props.density === 1) delete next.density;
+      else next.density = props.density;
+    }
+    if (props.feather !== void 0) {
+      if (props.feather === 0) delete next.feather;
+      else next.feather = props.feather;
+    }
+    this.commitLayers(mapLayer(this.state.layers, id, (l) => ({ ...l, vectorMask: next })));
+    return next;
+  }
+  /** Deletes a layer's vector mask (one undo step). */
+  removeVectorMask(id) {
+    this.requireVectorMask(id);
+    this.commitLayers(
+      mapLayer(this.state.layers, id, (l) => {
+        const next = { ...l };
+        delete next.vectorMask;
+        return next;
+      })
+    );
+  }
+  /**
+   * Layer › Rasterize › Vector Mask: multiplies the path (with its density and feather) into the
+   * layer's raster mask, adding one when there is none, and removes the vector mask. The raster
+   * mask keeps its own properties. One undo step. Returns the raster mask.
+   */
+  rasterizeVectorMask(id) {
+    const { layer } = this.requireVectorMask(id);
+    const { width, height } = this.canvasSize;
+    const raster = layer.mask;
+    const plain3 = { ...layer, vectorMask: { ...layer.vectorMask, enabled: true }, mask: raster ? { surface: raster.surface, defaultValue: raster.defaultValue } : void 0 };
+    const baked = effectiveLayerMask(plain3, width, height);
+    const mask = raster ? { ...raster, surface: baked.surface, defaultValue: baked.defaultValue } : baked;
+    this.commitLayers(
+      mapLayer(this.state.layers, id, (l) => {
+        const next = { ...l, mask };
+        delete next.vectorMask;
+        return next;
+      })
+    );
+    return mask;
+  }
+  /** Load Selection from a vector mask's path (density and feather are not applied), inverted with `invert`. */
+  selectionFromVectorMask(id, mode = "replace", invert2 = false) {
+    const { vm } = this.requireVectorMask(id);
+    const { width, height } = this.naturalSize;
+    const cov = componentsCoverage(vm.components, { x: 0, y: 0, width, height }, vm.fillRule ?? "nonzero", vm.inverted === true !== invert2);
+    const bytes = new Uint8Array(cov.length);
+    for (let i = 0; i < cov.length; i++) bytes[i] = Math.round(Math.min(1, Math.max(0, cov[i])) * 255);
+    return this.setSelection(createSelectionMask(width, height, bytes), mode);
+  }
+  /** A layer's vector mask with its paths (rounded), or `null` without one. */
+  getVectorMask(id) {
+    const layer = requireLayer(this.state.layers, id).layer;
+    const vm = layer.vectorMask;
+    if (!vm) return null;
+    const b = vectorMaskBounds(vm);
+    const r = (n) => Math.round(n * 1e3) / 1e3;
+    return {
+      layerId: id,
+      enabled: vm.enabled !== false,
+      linked: vm.linked !== false,
+      inverted: vm.inverted === true,
+      fillRule: vm.fillRule ?? "nonzero",
+      density: vm.density ?? 1,
+      feather: vm.feather ?? 0,
+      bounds: b ? { x: r(b.x), y: r(b.y), width: r(b.width), height: r(b.height) } : null,
+      components: vm.components.map((c, index) => ({ index, op: c.op, live: c.live ? JSON.parse(JSON.stringify(c.live)) : null, subpaths: roundSubpaths(c.subpaths) }))
+    };
+  }
   /** Changes any layer mask's density, feather, enabled or linked flag (pixels kept). Returns the mask. */
   setLayerMaskProps(id, props, commitToHistory = true) {
     const layer = requireLayer(this.state.layers, id).layer;
@@ -11658,11 +11820,12 @@ function createImageSelectionTools(controller) {
   const loadFromMask = {
     name: "load_selection_from_mask",
     title: "Load a selection from a layer mask",
-    description: "Load Selection from a layer's mask (Ctrl/\u2318-click its mask thumbnail): the mask's pixels become the selection, combined by mode (density and feather are not applied). Use it to reuse a mask on another layer or to edit it as a selection. Fails when the layer has no painted mask. One undoable step. Returns the selection.",
+    description: "Load Selection from a layer's mask (Ctrl/\u2318-click its mask thumbnail): the raster mask's pixels, or with source vector the vector mask's path, become the selection, combined by mode (density and feather are not applied). Use it to reuse a mask on another layer or to edit it as a selection. Fails when the layer has no such mask. One undoable step. Returns the selection.",
     inputSchema: {
       type: "object",
       properties: {
         layerId: { type: "string", minLength: 1, description: "The layer whose mask to load (see list_layers)." },
+        source: { type: "string", enum: ["pixels", "vector"], description: "pixels: the raster (layer) mask (default); vector: the vector mask's path." },
         invert: { type: "boolean", description: "Select what the mask hides instead (default false)." },
         mode: modeSchema
       },
@@ -11674,6 +11837,11 @@ function createImageSelectionTools(controller) {
       const id = String(args.layerId ?? "");
       const layer = controller.getLayer(id);
       if (!layer) throw new Error(`No layer "${id}". Call list_layers for ids.`);
+      if (args.source === "vector") {
+        if (!layer.vectorMask) throw new Error(`Layer "${id}" has no vector mask. Add one with add_vector_mask, or load its pixels mask (source pixels).`);
+        controller.selectionFromVectorMask(id, parseSelectionMode(args.mode), args.invert === true);
+        return summary(controller);
+      }
       if (!layer.mask) throw new Error(`Layer "${id}" has no mask. Add one with add_layer_mask, or pick a layer with a mask.`);
       if (layer.mask.source) throw new Error(`Layer "${id}" has a computed (depth) mask, not a painted one, so it cannot be loaded as a selection.`);
       controller.selectionFromLayerMask(id, parseSelectionMode(args.mode), args.invert === true);
@@ -12540,6 +12708,7 @@ function describeLayer(layer, activeId, boundsOf) {
     clipped: Boolean(layer.clipped),
     locks: layer.locks ? { ...layer.locks } : {},
     mask: maskSummary(layer.mask),
+    vectorMask: layer.vectorMask ? { enabled: layer.vectorMask.enabled !== false, linked: layer.vectorMask.linked !== false, inverted: layer.vectorMask.inverted === true, components: layer.vectorMask.components.length, bounds: vectorMaskBounds(layer.vectorMask) } : null,
     effects: layer.effects ? { enabled: layer.effects.enabled, scale: layer.effects.scale ?? 1, items: layer.effects.items.map((e) => ({ id: e.id, kind: e.kind, enabled: e.enabled })) } : null,
     active: layer.id === activeId
   };
@@ -15726,7 +15895,122 @@ function createImageShapeTools(controller) {
     annotations: { title: "Merge shape components", ...DESTRUCTIVE6 },
     handler: ({ layerId }) => controller.mergeShapeComponents(shapeId(layerId))
   };
-  return [get, add2, update, setComponent, addComponent, removeComponent, merge];
+  const layerArg = (v) => {
+    const id = String(v ?? "");
+    if (!controller.getLayer(id)) throw new Error(`No layer "${id}". Call list_layers for ids.`);
+    return id;
+  };
+  const pathSpec = (args) => {
+    const spec = { ...geometry(args) };
+    if (args.components !== void 0) spec.components = args.components.map(geometry);
+    if (args.fillRule !== void 0) spec.fillRule = args.fillRule;
+    return spec;
+  };
+  const PATH_PROPS = {
+    ...GEOMETRY2,
+    components: {
+      type: "array",
+      minItems: 1,
+      description: "Several components instead of shape / subpaths, bottom first, each with its path operation (combine, subtract, intersect, exclude).",
+      items: { type: "object", description: "One component.", properties: { ...GEOMETRY2, op: OP }, additionalProperties: false }
+    },
+    fillRule: { type: "string", enum: ["nonzero", "evenodd"], description: "Winding rule within a component (default nonzero)." }
+  };
+  const LAYER = { type: "string", minLength: 1, description: "The layer (see list_layers). Not a shape layer: its path already is its vector mask." };
+  const getVectorMask = {
+    name: "get_vector_mask",
+    title: "Read a vector mask",
+    description: "Reads a layer's vector mask: enabled, linked, inverted, fill rule, density, feather, the bounds of its path and its components (op, live shape, subpaths in document pixels). Use it before set_vector_mask_path to edit the path. Returns null when the layer has none.",
+    inputSchema: { type: "object", properties: { layerId: LAYER }, required: ["layerId"], additionalProperties: false },
+    annotations: { title: "Read a vector mask", ...READ10 },
+    handler: ({ layerId }) => ({ vectorMask: controller.getVectorMask(layerArg(layerId)) })
+  };
+  const addVectorMask = {
+    name: "add_vector_mask",
+    title: "Add a vector mask",
+    description: "Layer \u203A Vector Mask: a path that reveals the layer inside it and stays sharp at any size, on top of any raster mask (both apply). from path takes a live shape, free subpaths or components like add_shape_layer; reveal-all and hide-all start with an empty path. Use it for hard-edged geometric or traced cutouts that must stay editable; use add_layer_mask for soft or painted ones. A linked vector mask moves and transforms with the layer. Replaces an existing vector mask. One undo step. Returns the vector mask.",
+    inputSchema: {
+      type: "object",
+      $defs: DEFS2,
+      properties: {
+        layerId: LAYER,
+        from: { type: "string", enum: ["path", "reveal-all", "hide-all"], description: "path (default when a shape, subpaths or components are given), reveal-all or hide-all (an empty path)." },
+        ...PATH_PROPS
+      },
+      required: ["layerId"],
+      additionalProperties: false
+    },
+    annotations: { title: "Add a vector mask", ...WRITE8 },
+    handler: (args) => {
+      const id = layerArg(args.layerId);
+      const spec = pathSpec(args);
+      const hasPath = spec.components?.length || spec.shape !== void 0 || spec.subpaths !== void 0;
+      const from = args.from ?? (hasPath ? "path" : "reveal-all");
+      controller.addVectorMask(id, from, spec);
+      return { vectorMask: controller.getVectorMask(id) };
+    }
+  };
+  const setVectorMaskPath = {
+    name: "set_vector_mask_path",
+    title: "Replace a vector mask path",
+    description: "Replaces the path of a layer's vector mask (shape, subpaths or components, document pixels); enabled, linked, inverted, density and feather are kept. Read the current path with get_vector_mask first to change part of it. One undo step. Returns the vector mask.",
+    inputSchema: { type: "object", $defs: DEFS2, properties: { layerId: LAYER, ...PATH_PROPS }, required: ["layerId"], additionalProperties: false },
+    annotations: { title: "Replace a vector mask path", ...WRITE_IDEMPOTENT5 },
+    handler: (args) => {
+      const id = layerArg(args.layerId);
+      controller.setVectorMaskPath(id, pathSpec(args));
+      return { vectorMask: controller.getVectorMask(id) };
+    }
+  };
+  const setVectorMaskProps = {
+    name: "set_vector_mask_properties",
+    title: "Set vector mask properties",
+    description: "Changes a layer's vector mask without touching its path: enabled (false ignores it), linked (false: it stays put when the layer moves or transforms), inverted (reveal outside the path), density 0..1 and feather in px (soften the edge without losing the path). One undo step. Returns the vector mask.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        layerId: LAYER,
+        enabled: { type: "boolean", description: "false ignores the vector mask but keeps it." },
+        linked: { type: "boolean", description: "false keeps the path in place when the layer moves or transforms." },
+        inverted: { type: "boolean", description: "true reveals outside the path instead." },
+        density: { type: "number", minimum: 0, maximum: 1, description: "Density 0..1 (default 1): at 0.5 the hidden area still shows half." },
+        feather: { type: "number", minimum: 0, maximum: 1e3, description: "Feather \u03C3 in px (default 0)." }
+      },
+      required: ["layerId"],
+      additionalProperties: false
+    },
+    annotations: { title: "Set vector mask properties", ...WRITE_IDEMPOTENT5 },
+    handler: ({ layerId, ...props }) => {
+      const id = layerArg(layerId);
+      controller.setVectorMaskProps(id, props);
+      return { vectorMask: controller.getVectorMask(id) };
+    }
+  };
+  const rasterizeVectorMask = {
+    name: "rasterize_vector_mask",
+    title: "Rasterize a vector mask",
+    description: "Layer \u203A Rasterize \u203A Vector Mask: multiplies the path (with its density and feather) into the layer's raster mask, adding one if needed, and removes the vector mask, so the mask can be painted. The path can no longer be edited (undo_image brings it back). One undo step. Returns the layer's raster mask summary.",
+    inputSchema: { type: "object", properties: { layerId: LAYER }, required: ["layerId"], additionalProperties: false },
+    annotations: { title: "Rasterize a vector mask", ...DESTRUCTIVE6 },
+    handler: ({ layerId }) => {
+      const id = layerArg(layerId);
+      const mask = controller.rasterizeVectorMask(id);
+      return { layerId: id, mask: { defaultValue: mask.defaultValue, density: mask.density ?? 1, feather: mask.feather ?? 0, enabled: mask.enabled !== false } };
+    }
+  };
+  const removeVectorMask = {
+    name: "remove_vector_mask",
+    title: "Delete a vector mask",
+    description: "Deletes a layer's vector mask without applying it (the raster mask, if any, stays). Disable it instead with set_vector_mask_properties enabled false to keep it. One undo step. Returns the layer id.",
+    inputSchema: { type: "object", properties: { layerId: LAYER }, required: ["layerId"], additionalProperties: false },
+    annotations: { title: "Delete a vector mask", ...DESTRUCTIVE6 },
+    handler: ({ layerId }) => {
+      const id = layerArg(layerId);
+      controller.removeVectorMask(id);
+      return { layerId: id, vectorMask: null };
+    }
+  };
+  return [get, add2, update, setComponent, addComponent, removeComponent, merge, getVectorMask, addVectorMask, setVectorMaskPath, setVectorMaskProps, rasterizeVectorMask, removeVectorMask];
 }
 
 // src/image-editor/type-tools.ts
@@ -16393,6 +16677,11 @@ function maskThumbnailClick(controller, layer, e) {
     controller.setActiveLayer(layer.id, "mask");
   }
 }
+function vectorMaskThumbnailClick(controller, layer, e) {
+  if (!layer.vectorMask) return;
+  if (e.ctrlKey || e.metaKey) controller.selectionFromVectorMask(layer.id, selectionModeFromModifiers(e, "replace"));
+  else if (e.shiftKey) controller.setVectorMaskProps(layer.id, { enabled: layer.vectorMask.enabled === false });
+}
 function layerThumbnailClick(controller, layer, e) {
   if (!(e.ctrlKey || e.metaKey)) return false;
   controller.selectLayerTransparency(layer.id, { mode: selectionModeFromModifiers(e, "replace") });
@@ -16491,6 +16780,11 @@ function layerMenu(controller) {
     { action: "delete-mask", label: "Delete Layer Mask", enabled: Boolean(active?.mask) },
     { action: "toggle-mask", label: active?.mask?.enabled === false ? "Enable Layer Mask" : "Disable Layer Mask", enabled: Boolean(active?.mask) },
     { action: "toggle-mask-link", label: active?.mask?.linked === false ? "Link Layer Mask" : "Unlink Layer Mask", enabled: Boolean(active?.mask && !active.mask.source) },
+    { action: "add-vector-mask", label: "Add Vector Mask (Reveal All)", enabled: Boolean(active && active.type !== "shape" && !active.mask?.source) },
+    { action: "add-vector-mask-hide", label: "Add Vector Mask (Hide All)", enabled: Boolean(active && active.type !== "shape" && !active.mask?.source) },
+    { action: "delete-vector-mask", label: "Delete Vector Mask", enabled: Boolean(active?.vectorMask) },
+    { action: "toggle-vector-mask", label: active?.vectorMask?.enabled === false ? "Enable Vector Mask" : "Disable Vector Mask", enabled: Boolean(active?.vectorMask) },
+    { action: "rasterize-vector-mask", label: "Rasterize Vector Mask", enabled: Boolean(active?.vectorMask) },
     { action: "rasterize", label: "Rasterize Layer", enabled: active?.type === "annotation" || active?.type === "smart" || active?.type === "shape" || active?.type === "type" || isPixel && Boolean(active?.type === "pixel" && active.filters?.length) },
     { action: "convert-smart", label: "Convert to Smart Object", enabled: Boolean(active && active.type !== "annotation") },
     { action: "edit-contents", label: "Edit Contents", enabled: active?.type === "smart" },
@@ -16562,6 +16856,19 @@ async function runLayerMenuAction(controller, action) {
       case "toggle-mask-link":
         if (id && active?.mask) controller.setLayerMaskProps(id, { linked: active.mask.linked === false });
         break;
+      case "add-vector-mask":
+      case "add-vector-mask-hide":
+        if (id) controller.addVectorMask(id, action === "add-vector-mask" ? "reveal-all" : "hide-all");
+        break;
+      case "delete-vector-mask":
+        if (id) controller.removeVectorMask(id);
+        break;
+      case "toggle-vector-mask":
+        if (id && active?.vectorMask) controller.setVectorMaskProps(id, { enabled: active.vectorMask.enabled === false });
+        break;
+      case "rasterize-vector-mask":
+        if (id) controller.rasterizeVectorMask(id);
+        break;
       case "rasterize":
         if (id) await controller.rasterizeLayer(id);
         break;
@@ -18154,6 +18461,7 @@ export {
   combineSelections,
   compileAdjustmentLayer,
   componentPath,
+  componentsCoverage,
   compositeDeep,
   compositeSurfaceOver,
   computeHistogram,
@@ -18273,6 +18581,7 @@ export {
   effectLayerTiming,
   effectPixelsToSurface,
   effectReach,
+  effectiveLayerMask,
   effectiveProof,
   effectsFingerprint,
   effectsMargin,
@@ -18309,6 +18618,7 @@ export {
   flattenPath,
   flipCorners,
   flowField,
+  followLayerMove,
   fontOf,
   formatControlValue,
   fullSelection,
@@ -18373,6 +18683,7 @@ export {
   invertMatrix3,
   invertSelection,
   isActiveFilter,
+  isActiveVectorMask,
   isAdjustmentKind,
   isBitDepth,
   isBlendMode,
@@ -18512,6 +18823,7 @@ export {
   offsetLayer,
   offsetShape,
   offsetSmartObject,
+  offsetVectorMask,
   openMaskFile,
   openPsdFile,
   packRgba,
@@ -18632,6 +18944,7 @@ export {
   resolveMosaicRegionBounds,
   resolvePaintGradient,
   resolveProfile,
+  resolveVectorMasks,
   restyleRange,
   retouchFilter,
   reversePaintGradient,
@@ -18761,6 +19074,7 @@ export {
   transformShapeComponents,
   transformSurface,
   transformTypeLayer,
+  transformVectorMask,
   transformedBounds,
   transformedBox,
   transformedPoint,
@@ -18787,6 +19101,10 @@ export {
   validateEffectGradient,
   validateLayerEffect,
   validateLayerEffects,
+  vectorMaskBounds,
+  vectorMaskCoverage,
+  vectorMaskThumbnail,
+  vectorMaskThumbnailClick,
   versionedDescriptorBytes,
   vibranceLinear,
   vibrancePixel,

package/dist/image-editor/layer-tools.d.cts

@@ -6,7 +6,7 @@ import type { CropBox } from './types.cjs';
 export declare function maskSummary(mask: RasterMask | undefined): Record<string, unknown> | null;
 /**
  * A plain description of a layer (and its children) for agents: ids, types, names, document
- * bounds, visibility, opacity, fill, blend, clipping, locks, mask and effects summaries and
+ * bounds, visibility, opacity, fill, blend, clipping, locks, mask, vector mask and effects summaries and
  * whether it is active. `boundsOf` gives a pixel layer's document bounds.
  */
 export declare function describeLayer(layer: ImageLayer, activeId: string | null, boundsOf: (layer: ImageLayer) => CropBox | null): Record<string, unknown>;

package/dist/image-editor/layer-tools.d.ts

@@ -6,7 +6,7 @@ import type { CropBox } from './types.js';
 export declare function maskSummary(mask: RasterMask | undefined): Record<string, unknown> | null;
 /**
  * A plain description of a layer (and its children) for agents: ids, types, names, document
- * bounds, visibility, opacity, fill, blend, clipping, locks, mask and effects summaries and
+ * bounds, visibility, opacity, fill, blend, clipping, locks, mask, vector mask and effects summaries and
  * whether it is active. `boundsOf` gives a pixel layer's document bounds.
  */
 export declare function describeLayer(layer: ImageLayer, activeId: string | null, boundsOf: (layer: ImageLayer) => CropBox | null): Record<string, unknown>;

package/dist/image-editor/layers/compositor.d.cts

@@ -42,6 +42,9 @@ export declare function runLayerFiltersFloat(data: Float32Array, width: number,
 /** The per-tile compositor for image editor layer stacks (see the raster module for the caches). */
 export declare class LayerCompositor extends RasterCompositor<ImageLayer, CompositorSources> {
     constructor(options?: CompositorOptions);
+    composite(layers: readonly ImageLayer[], rect: RasterRect, sources: CompositorSources, options?: CompositeCallOptions): Uint8ClampedArray;
+    compositeTiles(layers: readonly ImageLayer[], rect: RasterRect, sources: CompositorSources, onTile: (tx: number, ty: number, data: Uint8ClampedArray, changed: boolean) => void, options?: CompositeCallOptions): void;
+    tile(layers: readonly ImageLayer[], tx: number, ty: number, sources: CompositorSources): Uint8ClampedArray;
 }
 /**
  * The composite of an image editor stack at 16 or 32 bits (see `raster/deep-compositor`): float

package/dist/image-editor/layers/compositor.d.ts

@@ -42,6 +42,9 @@ export declare function runLayerFiltersFloat(data: Float32Array, width: number,
 /** The per-tile compositor for image editor layer stacks (see the raster module for the caches). */
 export declare class LayerCompositor extends RasterCompositor<ImageLayer, CompositorSources> {
     constructor(options?: CompositorOptions);
+    composite(layers: readonly ImageLayer[], rect: RasterRect, sources: CompositorSources, options?: CompositeCallOptions): Uint8ClampedArray;
+    compositeTiles(layers: readonly ImageLayer[], rect: RasterRect, sources: CompositorSources, onTile: (tx: number, ty: number, data: Uint8ClampedArray, changed: boolean) => void, options?: CompositeCallOptions): void;
+    tile(layers: readonly ImageLayer[], tx: number, ty: number, sources: CompositorSources): Uint8ClampedArray;
 }
 /**
  * The composite of an image editor stack at 16 or 32 bits (see `raster/deep-compositor`): float

package/dist/image-editor/layers/model.d.cts

@@ -28,6 +28,29 @@ export type { LayerLocks };
 export type RasterMask = BaseRasterMask<DepthMaskOptions>;
 export interface LayerBase extends RasterLayerBase {
     mask?: RasterMask;
+    /** A vector mask (Photoshop's): a path that reveals the layer, on top of `mask`. Not on shape layers. */
+    vectorMask?: VectorMask;
+}
+/**
+ * A vector mask: shape components in document pixels (the same paths shape layers use) that
+ * reveal the layer inside them (outside with `inverted`). It stays sharp at any size; the
+ * compositor multiplies it with the layer's raster mask. No components hides everything
+ * (reveals everything when inverted).
+ */
+export interface VectorMask {
+    components: ShapeComponent[];
+    /** How overlapping subpaths fill (default nonzero). */
+    fillRule?: ShapeFillRule;
+    /** Reveal outside the path instead (default false). */
+    inverted?: boolean;
+    /** Disabled masks are kept but ignored (default true). */
+    enabled?: boolean;
+    /** `false`: the path stays put when the layer moves or transforms (default true). */
+    linked?: boolean;
+    /** 0..1 (default 1): at 0.5 the hidden area still shows half. */
+    density?: number;
+    /** Gaussian feather σ in px (default 0). */
+    feather?: number;
 }
 /** The base sliders of the old document-level adjustments, as a filter on one layer. */
 export interface DevelopSettings {

package/dist/image-editor/layers/model.d.ts

@@ -28,6 +28,29 @@ export type { LayerLocks };
 export type RasterMask = BaseRasterMask<DepthMaskOptions>;
 export interface LayerBase extends RasterLayerBase {
     mask?: RasterMask;
+    /** A vector mask (Photoshop's): a path that reveals the layer, on top of `mask`. Not on shape layers. */
+    vectorMask?: VectorMask;
+}
+/**
+ * A vector mask: shape components in document pixels (the same paths shape layers use) that
+ * reveal the layer inside them (outside with `inverted`). It stays sharp at any size; the
+ * compositor multiplies it with the layer's raster mask. No components hides everything
+ * (reveals everything when inverted).
+ */
+export interface VectorMask {
+    components: ShapeComponent[];
+    /** How overlapping subpaths fill (default nonzero). */
+    fillRule?: ShapeFillRule;
+    /** Reveal outside the path instead (default false). */
+    inverted?: boolean;
+    /** Disabled masks are kept but ignored (default true). */
+    enabled?: boolean;
+    /** `false`: the path stays put when the layer moves or transforms (default true). */
+    linked?: boolean;
+    /** 0..1 (default 1): at 0.5 the hidden area still shows half. */
+    density?: number;
+    /** Gaussian feather σ in px (default 0). */
+    feather?: number;
 }
 /** The base sliders of the old document-level adjustments, as a filter on one layer. */
 export interface DevelopSettings {

package/dist/image-editor/layers/panel.d.cts

@@ -18,6 +18,16 @@ export declare function maskThumbnailClick(controller: ImageEditorController, la
     shiftKey?: boolean;
     altKey?: boolean;
 }): void;
+/**
+ * A click on a layer's vector mask thumbnail: Ctrl/⌘-click loads the path as the selection (Shift
+ * adds, Alt subtracts, both intersect) and Shift-click turns the vector mask on or off.
+ */
+export declare function vectorMaskThumbnailClick(controller: ImageEditorController, layer: ImageLayer, e: {
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+}): void;
 /**
  * A click on a layer's pixel thumbnail: Ctrl/⌘-click loads the layer's transparency as the
  * selection (Shift adds, Alt subtracts, both intersect) and returns true; other clicks are left
@@ -57,7 +67,7 @@ export type DropZone = 'above' | 'below' | 'inside';
 export declare function dropZone(fraction: number, isGroup: boolean): DropZone;
 /** The placement for `move_layer` when `dragId` is dropped on row `targetId` in `zone`, or `null` for a no-op. */
 export declare function dropPlacement(layers: readonly ImageLayer[], dragId: string, targetId: string, zone: DropZone): LayerPlacement | null;
-export type LayerMenuAction = 'new-layer' | 'new-group' | 'duplicate' | 'delete' | 'group-selected' | 'ungroup' | 'merge-down' | 'merge-visible' | 'flatten' | 'via-copy' | 'via-cut' | 'add-mask' | 'add-mask-selection' | 'add-mask-hide-selection' | 'add-mask-transparency' | 'select-transparency' | 'apply-mask' | 'delete-mask' | 'toggle-mask' | 'toggle-mask-link' | 'toggle-clip' | 'rasterize' | 'convert-smart' | 'edit-contents' | 'smart-via-copy' | 'add-filter-mask';
+export type LayerMenuAction = 'new-layer' | 'new-group' | 'duplicate' | 'delete' | 'group-selected' | 'ungroup' | 'merge-down' | 'merge-visible' | 'flatten' | 'via-copy' | 'via-cut' | 'add-mask' | 'add-vector-mask' | 'add-vector-mask-hide' | 'delete-vector-mask' | 'toggle-vector-mask' | 'rasterize-vector-mask' | 'add-mask-selection' | 'add-mask-hide-selection' | 'add-mask-transparency' | 'select-transparency' | 'apply-mask' | 'delete-mask' | 'toggle-mask' | 'toggle-mask-link' | 'toggle-clip' | 'rasterize' | 'convert-smart' | 'edit-contents' | 'smart-via-copy' | 'add-filter-mask';
 export interface LayerMenuItem {
     action: LayerMenuAction;
     label: string;