@pixerate/editor 0.106.0 → 0.108.0

package/dist/vector/index.js

@@ -32,6 +32,7 @@ import {
   VECTOR_GRADIENT_MIN_STOPS,
   VECTOR_GRADIENT_SPREADS,
   VECTOR_GRADIENT_TYPES,
+  VECTOR_MASK_TYPES,
   VECTOR_MERGE_MODES,
   VECTOR_PATHFINDER_OPERATIONS,
   VECTOR_PRESSURE_NOMINAL,
@@ -77,6 +78,9 @@ import {
   effectPathVertexCount,
   effectiveStrokeAlign,
   ellipseSubpath,
+  eraseFromFill,
+  eraseFromOutline,
+  eraserRegion,
   evaluateVectorPathKeyframes,
   expandVectorAppearance,
   expandVectorAppearances,
@@ -122,6 +126,10 @@ import {
   isVectorFilterType,
   isVectorGradient,
   isVectorLiveBoolean,
+  isVectorMaskActive,
+  isVectorMaskGroup,
+  isVectorMaskType,
+  knifePath,
   lineSubpath,
   locateVectorNode,
   mapBezierPath,
@@ -154,6 +162,7 @@ import {
   periodicVectorGradientStops,
   pinVectorGradient,
   polygonSubpath,
+  polylineBounds,
   pressureWidthProfile,
   puckerBloatPaths,
   rectSubpath,
@@ -177,6 +186,7 @@ import {
   sanitizeVectorFills,
   sanitizeVectorFilters,
   sanitizeVectorGradient,
+  sanitizeVectorMask,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
   sanitizeWidthProfile,
@@ -184,8 +194,10 @@ import {
   setSubpathCorners,
   setVectorGradientVector,
   setWidthPoint,
+  simplifyPolyline,
   sortedVectorGradientStops,
   spanVectorGradientStops,
+  splitIntoFaces,
   starSubpath,
   strokePositionPoint,
   strokeWidthProfileOf,
@@ -213,6 +225,7 @@ import {
   vectorBlendModeCss,
   vectorBlendModeFromCss,
   vectorBoxMatrix,
+  vectorChildAppearanceShapes,
   vectorCornerAt,
   vectorCorners,
   vectorCornersAttribute,
@@ -243,6 +256,19 @@ import {
   vectorGradientTAt,
   vectorGradientUnitsMatrix,
   vectorLiveBooleanSteps,
+  vectorMaskContains,
+  vectorMaskContentBounds,
+  vectorMaskContents,
+  vectorMaskOwner,
+  vectorMaskRegion,
+  vectorMaskRegionPath,
+  vectorMaskRegionShapes,
+  vectorMaskRenderData,
+  vectorMaskSource,
+  vectorMaskSummary,
+  vectorMaskedGeometry,
+  vectorMaskedLocalBounds,
+  vectorMaskedShapes,
   vectorMeshFromOutline,
   vectorMeshOutline,
   vectorNodeBounds,
@@ -284,7 +310,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-63EFQCT5.js";
+} from "../chunk-HUQ7EHVI.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -294,20 +320,14 @@ import {
   distanceToBezierPath,
   fitCubicWithTangents,
   fitCubics,
-  normalizeBezierPath,
-  outlineStroke,
   pathBoolean,
   pathToContours,
-  pointInBezierPath,
-  segmentBounds,
   segmentDerivative,
   segmentIntersections,
   segmentNearest,
   segmentPoint,
   segmentTangent,
-  subSegment,
-  transformBezierPath,
-  windingNumber
+  transformBezierPath
 } from "../chunk-YCSFS3GK.js";
 import {
   IDENTITY_MATRIX,
@@ -408,14 +428,14 @@ function vectorGradientBarPosition(a, p) {
   return { offset: (d.x * v.x + d.y * v.y) / l2, across: d.x * a.normal.x + d.y * a.normal.y };
 }
 function hitVectorGradientAnnotator(a, p) {
-  const near2 = (q, r) => !!q && Math.hypot(q.x - p.x, q.y - p.y) <= r;
-  for (let i = a.stops.length - 1; i >= 0; i--) if (near2(a.stops[i], STOP_HIT)) return { kind: "stop", index: a.stops[i].index };
-  for (const m of a.midpoints) if (near2(m, MIDPOINT_HIT)) return { kind: "midpoint", index: m.index };
+  const near = (q, r) => !!q && Math.hypot(q.x - p.x, q.y - p.y) <= r;
+  for (let i = a.stops.length - 1; i >= 0; i--) if (near(a.stops[i], STOP_HIT)) return { kind: "stop", index: a.stops[i].index };
+  for (const m of a.midpoints) if (near(m, MIDPOINT_HIT)) return { kind: "midpoint", index: m.index };
   const centred = isCentredVectorGradient(a.gradient.type);
-  if (near2(a.end, HANDLE_HIT)) return { kind: "handle", handle: centred ? "radius" : "end" };
-  if (a.focal && near2(a.focal, HANDLE_HIT) && !near2(a.start, 1)) return { kind: "handle", handle: "focal" };
-  if (near2(a.start, HANDLE_HIT)) return { kind: "handle", handle: "start" };
-  if (near2(a.aspect, HANDLE_HIT)) return { kind: "handle", handle: "aspect" };
+  if (near(a.end, HANDLE_HIT)) return { kind: "handle", handle: centred ? "radius" : "end" };
+  if (a.focal && near(a.focal, HANDLE_HIT) && !near(a.start, 1)) return { kind: "handle", handle: "focal" };
+  if (near(a.start, HANDLE_HIT)) return { kind: "handle", handle: "start" };
+  if (near(a.aspect, HANDLE_HIT)) return { kind: "handle", handle: "aspect" };
   const { offset, across } = vectorGradientBarPosition(a, p);
   if (offset >= 0 && offset <= 1 && across >= -BAR_HIT && across <= VECTOR_GRADIENT_STOP_GAP + STOP_HIT) return { kind: "bar", offset };
   return null;
@@ -955,6 +975,10 @@ var VectorSnapTargets = class _VectorSnapTargets {
     const visit = (list, parent) => {
       for (const stored of list) {
         if (exclude.has(stored.id) || stored.visible === false) continue;
+        if (isVectorMaskActive(stored) && !contains(stored, exclude)) {
+          visit(vectorAppearanceNodes(stored), multiplyMatrices(nodeMatrix(stored), parent));
+          continue;
+        }
         const n = contains(stored, exclude) ? stored : expandVectorAppearance(stored);
         const m = multiplyMatrices(nodeMatrix(n), parent);
         if (n.type === "group") {
@@ -1025,14 +1049,14 @@ var VectorSnapTargets = class _VectorSnapTargets {
     }
     const point = this.nearestPoint(p, tol);
     if (point) return at(point.p, point.kind);
-    const near2 = this.segmentsNear(p, tol);
-    const crossing = this.crossing(near2, p, tol);
+    const near = this.segmentsNear(p, tol);
+    const crossing = this.crossing(near, p, tol);
     if (crossing) return at(crossing, "intersect");
     if (leave && leave.curves !== false) {
-      const foot = this.curvePoint(near2, leave.at, p, tol);
+      const foot = this.curvePoint(near, leave.at, p, tol);
       if (foot) return at(foot.point, foot.kind, [line("construction", leave.at, foot.point)]);
     }
-    const on = this.onSegment(near2);
+    const on = this.onSegment(near);
     if (on) return at(on, "path");
     if (leave?.angles?.length) {
       const c = construction(leave, p, tol);
@@ -1115,12 +1139,12 @@ var VectorSnapTargets = class _VectorSnapTargets {
     }
     return out.sort((a, b) => a.distance - b.distance);
   }
-  onSegment(near2) {
-    return near2.length ? toVec(segmentPoint(near2[0].seg, near2[0].t)) : null;
+  onSegment(near) {
+    return near.length ? toVec(segmentPoint(near[0].seg, near[0].t)) : null;
   }
   /** Where two of the target segments near `p` cross, the crossing nearest `p` within `tol`. */
-  crossing(near2, p, tol) {
-    const list = near2.slice(0, CROSSING_PAIRS);
+  crossing(near, p, tol) {
+    const list = near.slice(0, CROSSING_PAIRS);
     let best = null;
     let bestD = Infinity;
     for (let i = 0; i < list.length; i++) {
@@ -1142,9 +1166,9 @@ var VectorSnapTargets = class _VectorSnapTargets {
    * (within `tol` of it): roots of `(B(t) − base) · B′(t)` and `(B(t) − base) × B′(t)`
    * bracketed by sign changes of samples and narrowed by bisection.
    */
-  curvePoint(near2, base, p, tol) {
+  curvePoint(near, base, p, tol) {
     let best = null;
-    for (const { seg } of near2) {
+    for (const { seg } of near) {
       for (const kind of ["perpendicular", "tangent"]) {
         if (kind === "tangent" && seg.length === 2) continue;
         for (const q of solveOnSegment(seg, base, kind === "perpendicular" ? dotCondition : crossCondition)) {
@@ -1886,346 +1910,6 @@ function removeRedundantPoints(sp, tolerance) {
   return segsToSubpath(segs, sp.closed, types) ?? { anchors: sp.anchors.map(cloneAnchor), closed: sp.closed };
 }
 
-// src/vector/pathCut.ts
-var loopArea = (l) => contourSignedArea(l.segs);
-function loopSample(l) {
-  const k = l.chord.findIndex((c) => !c);
-  return segmentPoint(l.segs[k >= 0 ? k : 0], 0.5);
-}
-var contains2 = (l, p) => windingNumber([l.segs], p) !== 0;
-function groupFaces(loops) {
-  const usable2 = loops.filter((l) => l.segs.length && Math.abs(loopArea(l)) > 1e-12);
-  if (!usable2.length) return [];
-  const largest = usable2.reduce((a, b) => Math.abs(loopArea(b)) > Math.abs(loopArea(a)) ? b : a);
-  const sign = Math.sign(loopArea(largest));
-  const outers = usable2.filter((l) => Math.sign(loopArea(l)) === sign).sort((a, b) => Math.abs(loopArea(a)) - Math.abs(loopArea(b)));
-  const faces = new Map(outers.map((o) => [o, { loops: [o] }]));
-  for (const hole of usable2.filter((l) => Math.sign(loopArea(l)) !== sign)) {
-    const p = loopSample(hole);
-    const parent = outers.find((o) => Math.abs(loopArea(o)) > Math.abs(loopArea(hole)) && contains2(o, p));
-    if (parent) faces.get(parent).loops.push(hole);
-  }
-  return outers.reverse().map((o) => faces.get(o));
-}
-function faceToPath(face) {
-  return contoursToPath(face.loops.map((l) => ({ segments: l.segs, closed: true })));
-}
-function facesOf(path, fillRule) {
-  const normalized = normalizeBezierPath(path, fillRule);
-  const loops = pathToContours(normalized).map((c) => {
-    const segs = closeContour(c, true).map((s) => s.slice());
-    return { segs, chord: segs.map(() => false) };
-  });
-  return groupFaces(loops);
-}
-function splitIntoFaces(path, fillRule = "nonzero") {
-  return facesOf(path, fillRule).map(faceToPath);
-}
-function rootsInUnit(a, b, c, d, scale) {
-  const f = (t) => ((a * t + b) * t + c) * t + d;
-  const tol = 1e-12 * Math.max(1, scale);
-  const cuts = [0];
-  const qa = 3 * a;
-  const qb = 2 * b;
-  if (Math.abs(qa) > 1e-18) {
-    const disc = qb * qb - 4 * qa * c;
-    if (disc >= 0) {
-      const r = Math.sqrt(disc);
-      for (const t of [(-qb - r) / (2 * qa), (-qb + r) / (2 * qa)].sort((x, y) => x - y)) if (t > 0 && t < 1) cuts.push(t);
-    }
-  } else if (Math.abs(qb) > 1e-18) {
-    const t = -c / qb;
-    if (t > 0 && t < 1) cuts.push(t);
-  }
-  cuts.push(1);
-  const roots = [];
-  const push = (t) => {
-    if (!roots.some((r) => Math.abs(r - t) < 1e-9)) roots.push(t);
-  };
-  for (let i = 0; i < cuts.length - 1; i++) {
-    let lo = cuts[i];
-    let hi = cuts[i + 1];
-    let flo = f(lo);
-    const fhi = f(hi);
-    if (Math.abs(flo) <= tol) push(lo);
-    if (Math.abs(fhi) <= tol) push(hi);
-    if (flo * fhi >= 0) continue;
-    for (let k = 0; k < 80; k++) {
-      const m = (lo + hi) / 2;
-      const fm = f(m);
-      if (fm === 0) {
-        lo = hi = m;
-        break;
-      }
-      if (fm * flo < 0) hi = m;
-      else {
-        lo = m;
-        flo = fm;
-      }
-    }
-    push((lo + hi) / 2);
-  }
-  return roots.sort((x, y) => x - y);
-}
-function lineHits(p, q, seg) {
-  const dx = q[0] - p[0];
-  const dy = q[1] - p[1];
-  const len2 = dx * dx + dy * dy;
-  if (len2 < 1e-24) return [];
-  const h = (pt) => (pt[0] - p[0]) * -dy + (pt[1] - p[1]) * dx;
-  let coeffs;
-  if (seg.length === 2) coeffs = [0, 0, h(seg[1]) - h(seg[0]), h(seg[0])];
-  else {
-    const [h0, h1, h2, h3] = seg.map(h);
-    coeffs = [-h0 + 3 * h1 - 3 * h2 + h3, 3 * h0 - 6 * h1 + 3 * h2, -3 * h0 + 3 * h1, h0];
-  }
-  if (coeffs.every((c) => Math.abs(c) < 1e-12 * Math.max(1, len2))) return [];
-  const scale = Math.sqrt(len2) * Math.max(1, ...seg.map((pt) => Math.abs(pt[0]) + Math.abs(pt[1])));
-  const out = [];
-  for (const t of rootsInUnit(...coeffs, scale)) {
-    const point = segmentPoint(seg, t);
-    const s = ((point[0] - p[0]) * dx + (point[1] - p[1]) * dy) / len2;
-    if (s >= -1e-9 && s <= 1 + 1e-9) out.push({ s: Math.min(1, Math.max(0, s)), t, point });
-  }
-  return out;
-}
-var near = (a, b, eps) => Math.abs(a[0] - b[0]) <= eps && Math.abs(a[1] - b[1]) <= eps;
-var degenerate = (seg, eps) => seg.every((p) => near(p, seg[0], eps));
-function arc(l, a, b, eps) {
-  const n = l.segs.length;
-  const segs = [];
-  const chord = [];
-  const push = (k, t0, t1) => {
-    const piece = t0 <= 0 && t1 >= 1 ? l.segs[k].slice() : subSegment(l.segs[k], t0, t1);
-    if (!degenerate(piece, eps)) {
-      segs.push(piece);
-      chord.push(l.chord[k]);
-    }
-  };
-  if (a.seg === b.seg && b.t >= a.t + 1e-12) {
-    push(a.seg, a.t, b.t);
-    return { segs, chord };
-  }
-  push(a.seg, a.t, 1);
-  for (let k = (a.seg + 1) % n; k !== b.seg; k = (k + 1) % n) push(k, 0, 1);
-  push(b.seg, 0, b.t);
-  return { segs, chord };
-}
-function polySegs(points, eps) {
-  const out = [];
-  for (let i = 1; i < points.length; i++) if (!near(points[i - 1], points[i], eps)) out.push([points[i - 1], points[i]]);
-  return out;
-}
-function knifePath(path, fillRule, knife) {
-  const pts = knife.filter((p) => Number.isFinite(p[0]) && Number.isFinite(p[1]));
-  if (pts.length < 2) return null;
-  let faces = facesOf(path, fillRule);
-  if (!faces.length) return null;
-  const b = bezierPathBounds(path);
-  const size = b ? Math.max(b.maxX - b.minX, b.maxY - b.minY, 1) : 1;
-  const eps = size * 1e-9;
-  let cursor = -Infinity;
-  let cuts = 0;
-  for (let guard = 0; guard < 512; guard++) {
-    let best = null;
-    faces.forEach((face2, fi2) => {
-      const hits = [];
-      for (let m = 0; m < pts.length - 1; m++) {
-        if (m + 1 < cursor - 1e-9) continue;
-        const kb = { minX: Math.min(pts[m][0], pts[m + 1][0]), maxX: Math.max(pts[m][0], pts[m + 1][0]), minY: Math.min(pts[m][1], pts[m + 1][1]), maxY: Math.max(pts[m][1], pts[m + 1][1]) };
-        face2.loops.forEach(
-          (l, li) => l.segs.forEach((seg, si) => {
-            const sb = segmentBounds(seg);
-            if (sb.maxX < kb.minX - eps || sb.minX > kb.maxX + eps || sb.maxY < kb.minY - eps || sb.minY > kb.maxY + eps) return;
-            for (const h of lineHits(pts[m], pts[m + 1], seg)) {
-              const s = m + h.s;
-              if (s >= cursor - 1e-9) hits.push({ s, loop: li, seg: si, t: h.t, point: h.point });
-            }
-          })
-        );
-      }
-      hits.sort((x, y) => x.s - y.s);
-      const unique = hits.filter((h, i) => i === 0 || h.s - hits[i - 1].s > 1e-9 || !near(h.point, hits[i - 1].point, eps * 10));
-      const inside = (s) => {
-        const m = Math.min(pts.length - 2, Math.floor(s));
-        const u = s - m;
-        const q = [pts[m][0] + (pts[m + 1][0] - pts[m][0]) * u, pts[m][1] + (pts[m + 1][1] - pts[m][1]) * u];
-        return windingNumber(face2.loops.map((l) => l.segs), q) !== 0;
-      };
-      for (let i = 0; i < unique.length - 1; i++) {
-        const from2 = unique[i];
-        const to2 = unique[i + 1];
-        if (near(from2.point, to2.point, eps * 10) || !inside((from2.s + to2.s) / 2)) continue;
-        if (!best || from2.s < best.from.s) best = { face: fi2, from: from2, to: to2 };
-        break;
-      }
-    });
-    if (!best) break;
-    const { face: fi, from, to } = best;
-    const face = faces[fi];
-    const corners2 = [from.point];
-    for (let m = Math.floor(from.s) + 1; m <= to.s - 1e-12 && m < pts.length; m++) if (m > from.s) corners2.push(pts[m]);
-    corners2.push(to.point);
-    const forward = polySegs(corners2, eps);
-    const back = polySegs(corners2.slice().reverse(), eps);
-    const la = face.loops[from.loop];
-    const loops = face.loops.filter((_, i) => i !== from.loop && i !== to.loop);
-    if (from.loop === to.loop) {
-      const ab = arc(la, from, to, eps);
-      const ba = arc(la, to, from, eps);
-      loops.push(
-        { segs: [...ab.segs, ...back], chord: [...ab.chord, ...back.map(() => true)] },
-        { segs: [...ba.segs, ...forward], chord: [...ba.chord, ...forward.map(() => true)] }
-      );
-    } else {
-      const lb = face.loops[to.loop];
-      const roundA = arc(la, from, from, eps);
-      const roundB = arc(lb, to, to, eps);
-      loops.push({
-        segs: [...roundA.segs, ...forward, ...roundB.segs, ...back],
-        chord: [...roundA.chord, ...forward.map(() => true), ...roundB.chord, ...back.map(() => true)]
-      });
-    }
-    faces = [...faces.slice(0, fi), ...groupFaces(loops), ...faces.slice(fi + 1)];
-    cursor = to.s;
-    cuts++;
-  }
-  return cuts ? faces.map(faceToPath) : null;
-}
-function eraserRegion(points, width) {
-  const pts = points.filter((p) => Number.isFinite(p[0]) && Number.isFinite(p[1]));
-  const r = width / 2;
-  if (!pts.length || !(r > 0)) return [];
-  const moved = pts.some((p) => !near(p, pts[0], 1e-9));
-  if (!moved) {
-    const [cx, cy] = pts[0];
-    const k = r * 0.5522847498307936;
-    return [
-      { type: "M", x: cx, y: cy - r },
-      { type: "C", x1: cx + k, y1: cy - r, x2: cx + r, y2: cy - k, x: cx + r, y: cy },
-      { type: "C", x1: cx + r, y1: cy + k, x2: cx + k, y2: cy + r, x: cx, y: cy + r },
-      { type: "C", x1: cx - k, y1: cy + r, x2: cx - r, y2: cy + k, x: cx - r, y: cy },
-      { type: "C", x1: cx - r, y1: cy - k, x2: cx - k, y2: cy - r, x: cx, y: cy - r },
-      { type: "Z" }
-    ];
-  }
-  const line2 = [{ type: "M", x: pts[0][0], y: pts[0][1] }, ...pts.slice(1).map((p) => ({ type: "L", x: p[0], y: p[1] }))];
-  return outlineStroke(line2, { width, cap: "round", join: "round" });
-}
-function eraseFromFill(path, fillRule, region) {
-  const overlap = pathBoolean("intersection", [{ path, fillRule }, { path: region }]).path;
-  if (!pathToContours(overlap).some((c) => Math.abs(contourSignedArea(closeContour(c, true))) > 1e-9)) return null;
-  const rest = pathBoolean("difference", [{ path, fillRule }, { path: region }]).path;
-  return splitIntoFaces(rest);
-}
-function eraseFromOutline(sp, region) {
-  const regionSegs = pathToContours(region).flatMap((c) => closeContour(c, true));
-  if (!regionSegs.length) return null;
-  const rb = bezierPathBounds(region);
-  const count = subpathSegmentCount(sp);
-  if (!rb || count === 0) return null;
-  const removed = (p) => pointInBezierPath(region, p, "nonzero");
-  const runs = [];
-  let cur = [];
-  let any = false;
-  for (let i = 0; i < count; i++) {
-    const seg = subpathSegment(sp, i);
-    const sb = segmentBounds(seg);
-    const ts = [0, 1];
-    if (!(sb.maxX < rb.minX || sb.minX > rb.maxX || sb.maxY < rb.minY || sb.minY > rb.maxY)) {
-      for (const r of regionSegs) {
-        const b = segmentBounds(r);
-        if (b.maxX < sb.minX || b.minX > sb.maxX || b.maxY < sb.minY || b.minY > sb.maxY) continue;
-        for (const hit of segmentIntersections(seg, r)) if (hit.ta > 1e-9 && hit.ta < 1 - 1e-9) ts.push(hit.ta);
-      }
-    }
-    ts.sort((a, b) => a - b);
-    for (let k = 0; k < ts.length - 1; k++) {
-      const t0 = ts[k];
-      const t1 = ts[k + 1];
-      if (t1 - t0 < 1e-9) continue;
-      if (removed(segmentPoint(seg, (t0 + t1) / 2))) {
-        any = true;
-        if (cur.length) runs.push(cur);
-        cur = [];
-      } else cur.push({ seg: i, t0, t1 });
-    }
-  }
-  if (cur.length) runs.push(cur);
-  if (!any) return null;
-  if (sp.closed && runs.length >= 2) {
-    const first = runs[0][0];
-    const lastRun = runs[runs.length - 1];
-    const last = lastRun[lastRun.length - 1];
-    if (first.seg === 0 && first.t0 === 0 && last.seg === count - 1 && last.t1 === 1) lastRun.push(...runs.shift());
-  }
-  const out = [];
-  for (const run of runs) {
-    const anchors = [];
-    for (const { seg, t0, t1 } of run) {
-      const c = subSegment(subpathSegment(sp, seg), t0, t1);
-      const line2 = c.length === 2;
-      const start = c[0];
-      const end = c[c.length - 1];
-      if (!anchors.length) anchors.push({ x: start[0], y: start[1] });
-      if (!line2) anchors[anchors.length - 1].out = { x: c[1][0], y: c[1][1] };
-      const next = { x: end[0], y: end[1] };
-      if (!line2) next.in = { x: c[2][0], y: c[2][1] };
-      anchors.push(next);
-    }
-    if (anchors.length < 2) continue;
-    for (const a of anchors) {
-      const type = inferAnchorType(a);
-      if (type !== "corner") a.type = type;
-    }
-    out.push({ anchors, closed: false });
-  }
-  return out;
-}
-function polylineBounds(points, pad = 0) {
-  if (!points.length) return null;
-  let minX = Infinity;
-  let minY = Infinity;
-  let maxX = -Infinity;
-  let maxY = -Infinity;
-  for (const [x, y] of points) {
-    minX = Math.min(minX, x);
-    minY = Math.min(minY, y);
-    maxX = Math.max(maxX, x);
-    maxY = Math.max(maxY, y);
-  }
-  return { x: minX - pad, y: minY - pad, width: maxX - minX + 2 * pad, height: maxY - minY + 2 * pad };
-}
-function simplifyPolyline(points, tolerance) {
-  const n = points.length;
-  if (n < 3) return points.slice();
-  const keep = new Array(n).fill(false);
-  keep[0] = keep[n - 1] = true;
-  const stack = [[0, n - 1]];
-  while (stack.length) {
-    const [a, b] = stack.pop();
-    const [ax, ay] = points[a];
-    const dx = points[b][0] - ax;
-    const dy = points[b][1] - ay;
-    const len = Math.hypot(dx, dy);
-    let far = -1;
-    let farD = 0;
-    for (let i = a + 1; i < b; i++) {
-      const [px, py] = points[i];
-      const d = len < 1e-12 ? Math.hypot(px - ax, py - ay) : Math.abs((px - ax) * dy - (py - ay) * dx) / len;
-      if (d > farD) {
-        farD = d;
-        far = i;
-      }
-    }
-    if (far >= 0 && farD > tolerance) {
-      keep[far] = true;
-      stack.push([a, far], [far, b]);
-    }
-  }
-  return points.filter((_, i) => keep[i]);
-}
-
 // src/vector/ink.ts
 var LazyMouse = class {
   /** `length` is the string length in the units of the points (0 turns smoothing off). */
@@ -2457,7 +2141,7 @@ function vectorPathEntries(doc, roots, options = {}) {
   const out = [];
   const visit = (stored, parent, inside) => {
     if (stored.visible === false || stored.locked && !options.locked) return;
-    const node = options.expand === false ? stored : expandVectorAppearance(stored);
+    const node = options.expand === false ? stored : expandVectorAppearance(vectorMaskedGeometry(stored));
     const picked = inside || roots === null || roots.includes(node.id);
     if (node.type === "group") {
       const m = multiplyMatrices(nodeMatrix(node), parent);
@@ -4538,7 +4222,7 @@ var VectorEditorController = class {
     const drop = new Set(ids.filter((id) => this.getNode(id)));
     if (!drop.size) return { ok: false, message: "Nothing to delete." };
     this.change(options.label ?? "Delete", () => {
-      this.setDoc(mapTree(this.doc.nodes, (n) => drop.has(n.id) ? null : n));
+      this.setDoc(mapTree(this.doc.nodes, (n) => drop.has(n.id) ? null : isVectorMaskGroup(n) && drop.has(n.children[0].id) ? { ...n, mask: null } : n));
       this.selection = this.selection.filter((id) => !drop.has(id) && this.getNode(id));
       this.anchors = this.anchors.filter((r) => getAnchor(this.doc, r));
       if (this.editingId && !this.getNode(this.editingId)) this.editingId = null;
@@ -5197,7 +4881,7 @@ var VectorEditorController = class {
   /** Whether stored node `rootId` holds `id` as drawn (`id` may be an expanded path inside it). */
   holds(rootId, id) {
     const n = this.getNode(rootId);
-    return !!n && (!!findVectorNode([n], id) || !!findVectorNode([expandVectorAppearance(n)], id));
+    return !!n && (!!findVectorNode([n], id) || !!findVectorNode([expandVectorAppearance(n)], id) || !!findVectorNode([vectorMaskedGeometry(n)], id));
   }
   liveBooleanOp(op, roots) {
     const nodes = roots.map((id2) => this.getNode(id2));
@@ -5394,6 +5078,153 @@ var VectorEditorController = class {
     });
     return id;
   }
+  // -------------------------------------------------------------------------
+  // Masks
+  // -------------------------------------------------------------------------
+  /**
+   * Make Clipping Mask (`clip`) / Make Opacity Mask (`alpha`, `luminance`): groups the selected (or
+   * given) objects into a mask group whose mask is the topmost of them (or `maskId`), moved to the
+   * bottom of the group. They must be two or more, unlocked, with one parent. One undo step.
+   * Returns the group's id, or why it could not.
+   */
+  makeMask(type, options = {}) {
+    if (!isVectorMaskType(type)) return { ok: false, message: `Unknown mask type "${type}": use clip, alpha or luminance.` };
+    const ids = [...new Set(options.ids ?? this.selectedRoots())];
+    if (ids.length < 2) return { ok: false, message: "Select at least two objects: the topmost becomes the mask, the ones below show through it." };
+    for (const id2 of ids) {
+      const n = this.getNode(id2);
+      if (!n) return { ok: false, message: `There is no node "${id2}".` };
+      if (n.locked) return { ok: false, message: `"${id2}" is locked; unlock it first.` };
+      if (n.blendStep) return { ok: false, message: `"${id2}" is a blend step; select its blend instead.` };
+    }
+    const locs = ids.map((id2) => locateVectorNode(this.doc.nodes, id2));
+    const parent = locs[0].parent?.id ?? null;
+    if (locs.some((l) => (l.parent?.id ?? null) !== parent)) return { ok: false, message: "The objects must share a parent (group them, or pick objects at one level)." };
+    const order = ids.slice().sort((a, b) => locs[ids.indexOf(a)].index - locs[ids.indexOf(b)].index);
+    const maskId = options.maskId ?? order[order.length - 1];
+    if (!order.includes(maskId)) return { ok: false, message: `The mask "${maskId}" must be one of the objects (${order.map((id2) => `"${id2}"`).join(", ")}).` };
+    const id = this.newId();
+    const mask = options.invert ? { type, invert: true } : { type };
+    this.change(type === "clip" ? "Make Clipping Mask" : "Make Opacity Mask", () => {
+      const set = new Set(order);
+      const regroup = (list) => {
+        const members = order.map((m) => list.find((n) => n.id === m));
+        const top = Math.max(...members.map((m) => list.indexOf(m)));
+        const children = [members.find((m) => m.id === maskId), ...members.filter((m) => m.id !== maskId)];
+        const out = [];
+        list.forEach((n, i) => {
+          if (i === top) out.push({ id, type: "group", name: options.name ?? (type === "clip" ? "Clip Group" : "Opacity Mask"), mask, children });
+          if (!set.has(n.id)) out.push(n);
+        });
+        return out;
+      };
+      if (parent === null) this.setDoc(regroup(this.doc.nodes));
+      else this.setDoc(mapTree(this.doc.nodes, (n) => n.id === parent && n.type === "group" ? { ...n, children: regroup(n.children) } : n));
+      this.selection = [id];
+      this.anchors = [];
+      this.editingId = null;
+    });
+    return { ok: true, id };
+  }
+  /** Mask groups among `ids` (default: the selection), or holding one of them directly. */
+  maskTargets(ids) {
+    const out = /* @__PURE__ */ new Map();
+    for (const id of ids ?? this.selection) {
+      const n = this.getNode(id);
+      if (isVectorMaskGroup(n)) out.set(n.id, n);
+      else {
+        const parent = locateVectorNode(this.doc.nodes, id)?.parent;
+        if (isVectorMaskGroup(parent)) out.set(parent.id, parent);
+      }
+    }
+    return [...out.values()];
+  }
+  /**
+   * Release: the selected (or given) mask groups stop masking. The mask goes back on top of the
+   * contents, drawn as itself again. A group with appearance of its own (filters, a blend mode,
+   * path effects) stays a plain group; otherwise it is replaced by its children. One undo step.
+   * Returns the released nodes' ids (the mask last).
+   */
+  releaseMask(options = {}) {
+    const groups = this.maskTargets(options.ids);
+    if (!groups.length) return [];
+    const released = [];
+    this.change("Release Mask", () => {
+      for (const g of groups) {
+        const [mask, ...contents] = g.children;
+        const children = [...contents, mask];
+        released.push(...children.map((c) => c.id));
+        const { mask: _m, ...rest } = g;
+        const keep = !!(g.filters?.length || g.blendMode && g.blendMode !== "normal" || g.effects?.length);
+        if (keep) {
+          this.replaceNode(g.id, { ...rest, children });
+          continue;
+        }
+        const m = nodeMatrix(g);
+        const opacity = g.opacity;
+        const flat = children.map((c) => g.transform ? transformVectorNode(c, m) : c).map((c) => opacity !== void 0 && opacity < 1 ? { ...c, opacity: (c.opacity ?? 1) * opacity } : c);
+        this.setDoc(spliceTree(this.doc.nodes, g.id, flat));
+      }
+      this.selection = released;
+      this.anchors = [];
+      this.editingId = null;
+    });
+    return released;
+  }
+  /**
+   * Changes the type or inversion of the selected (or given) mask groups, or turns their masks off
+   * (`enabled: false` hides the mask, so the contents draw whole) and on. One undo step.
+   */
+  setMaskOptions(patch, options = {}) {
+    if (patch.type !== void 0 && !isVectorMaskType(patch.type)) return { ok: false, message: `Unknown mask type "${patch.type}": use clip, alpha or luminance.` };
+    if (patch.invert !== void 0 && typeof patch.invert !== "boolean") return { ok: false, message: "invert must be true or false." };
+    if (patch.enabled !== void 0 && typeof patch.enabled !== "boolean") return { ok: false, message: "enabled must be true or false." };
+    const groups = this.maskTargets(options.ids);
+    if (!groups.length) return { ok: false, message: "Select a mask group (made with Make Clipping Mask or Make Opacity Mask)." };
+    const set = new Set(groups.map((g) => g.id));
+    this.change("Mask Options", () => {
+      this.setDoc(
+        mapTree(this.doc.nodes, (n) => {
+          if (!set.has(n.id) || !isVectorMaskGroup(n)) return n;
+          const type = patch.type ?? n.mask.type;
+          const invert = patch.invert ?? !!n.mask.invert;
+          const [source, ...rest] = n.children;
+          const shown = patch.enabled === void 0 || patch.enabled === (source.visible !== false) ? source : patch.enabled ? (({ visible: _v, ...r }) => r)(source) : { ...source, visible: false };
+          return { ...n, mask: invert ? { type, invert } : { type }, ...shown !== source ? { children: [shown, ...rest] } : {} };
+        })
+      );
+    });
+    return { ok: true };
+  }
+  /**
+   * Edit Mask: selects the mask of the selected (or given) mask group, or of the group holding the
+   * selection. A path mask opens in the direct tool for anchor editing (`editPath: false` keeps the
+   * tool). Returns the mask's id, or null.
+   */
+  editMask(options = {}) {
+    const group = this.maskTargets(options.id ? [options.id] : void 0)[0];
+    if (!group) return null;
+    const mask = group.children[0];
+    this.selection = [mask.id];
+    this.anchors = [];
+    this.editingId = null;
+    if (mask.type === "path" && options.editPath !== false && !mask.locked) {
+      this.tool = "direct";
+      this.editingId = mask.id;
+    }
+    this.notify();
+    return mask.id;
+  }
+  /** Edit Contents: selects what the selected (or given) mask group masks. Returns their ids. */
+  editMaskContents(options = {}) {
+    const group = this.maskTargets(options.id ? [options.id] : void 0)[0];
+    if (!group) return [];
+    this.selection = group.children.slice(1).map((c) => c.id);
+    this.anchors = [];
+    this.editingId = null;
+    this.notify();
+    return [...this.selection];
+  }
   /** Sets the options new blends get (spacing, steps, distance, orientation, morph). */
   setBlendDefaults(patch) {
     this.blendDefaults = { ...this.blendDefaults, ...blendOptionsOf(patch) };
@@ -6018,11 +5849,11 @@ var VectorEditorController = class {
     if (!hit) return null;
     const sp = node.subpaths[hit.subpath];
     const n = sp.anchors.length;
-    const near2 = [hit.segment, (hit.segment + 1) % n].find((i) => Math.hypot(sp.anchors[i].x - hit.point.x, sp.anchors[i].y - hit.point.y) <= this.tolerance());
-    if (!sp.closed && n > 1 && (near2 === 0 || near2 === n - 1) && !(hit.t > 1e-6 && hit.t < 1 - 1e-6)) return null;
+    const near = [hit.segment, (hit.segment + 1) % n].find((i) => Math.hypot(sp.anchors[i].x - hit.point.x, sp.anchors[i].y - hit.point.y) <= this.tolerance());
+    if (!sp.closed && n > 1 && (near === 0 || near === n - 1) && !(hit.t > 1e-6 && hit.t < 1 - 1e-6)) return null;
     let ids = null;
     this.change("Cut Path", () => {
-      ids = this.applyCuts(node, (s, i) => i !== hit.subpath ? null : near2 !== void 0 ? cutSubpathAt(s, [near2]) : splitSubpathAt(s, hit.segment, hit.t));
+      ids = this.applyCuts(node, (s, i) => i !== hit.subpath ? null : near !== void 0 ? cutSubpathAt(s, [near]) : splitSubpathAt(s, hit.segment, hit.t));
       if (ids) {
         this.selection = ids;
         this.anchors = [];
@@ -6306,7 +6137,7 @@ var VectorEditorController = class {
         const n = list[i];
         if (n.visible === false || n.locked) continue;
         if (n.type === "group") {
-          if (hasOwnVectorAppearance(n) && !entered.has(n.id) && !hitTestVectorNode(n, p, tol, parent, { entered })) continue;
+          if ((hasOwnVectorAppearance(n) || isVectorMaskActive(n)) && !entered.has(n.id) && !hitTestVectorNode(n, p, tol, parent, { entered })) continue;
           const found = search(n.children, multiplyMatrices(nodeMatrix(n), parent));
           if (found) return found;
         } else if (hitTestVectorNode(n, p, tol, parent, { entered })) return n;
@@ -6428,24 +6259,24 @@ var VectorEditorController = class {
       if (!g) return;
       const m = this.worldOf(n.id);
       const local = applyMatrix(invertMatrix(m), p);
-      const near2 = nearestStrokePosition(g.line, [local.x, local.y]);
-      if (!near2) return;
+      const near = nearestStrokePosition(g.line, [local.x, local.y]);
+      if (!near) return;
       const profile = strokeWidthProfileOf(n);
-      const w = widthProfileAt(profile, near2.t);
-      const reach = Math.max(near2.side === "left" ? w.left : w.right, 0) * g.unit + tol;
-      if (near2.distance > reach || near2.distance > widthProfileMaxScale(profile) * g.unit + tol) return;
-      if (best && near2.distance >= best.distance) return;
-      const nx = near2.tangent[1];
-      const ny = -near2.tangent[0];
-      const [cx, cy] = near2.point;
+      const w = widthProfileAt(profile, near.t);
+      const reach = Math.max(near.side === "left" ? w.left : w.right, 0) * g.unit + tol;
+      if (near.distance > reach || near.distance > widthProfileMaxScale(profile) * g.unit + tol) return;
+      if (best && near.distance >= best.distance) return;
+      const nx = near.tangent[1];
+      const ny = -near.tangent[0];
+      const [cx, cy] = near.point;
       best = {
         nodeId: n.id,
-        subpath: near2.contour,
-        t: near2.t,
+        subpath: near.contour,
+        t: near.t,
         point: applyMatrix(m, { x: cx, y: cy }),
         left: applyMatrix(m, { x: cx + nx * w.left * g.unit, y: cy + ny * w.left * g.unit }),
         right: applyMatrix(m, { x: cx - nx * w.right * g.unit, y: cy - ny * w.right * g.unit }),
-        distance: near2.distance
+        distance: near.distance
       };
     });
     if (!best) return null;
@@ -6494,13 +6325,13 @@ var VectorEditorController = class {
       } else if (mode === "copy" || !selected) this.widthPoints = [ref];
       if (mode !== "copy") group = this.widthPoints.filter((r) => r.index !== ref.index).map((r) => r.index);
     } else {
-      const near2 = nearestStrokePosition(g.line, [local.x, local.y]);
-      const inserted = insertWidthPoint(strokeWidthProfileOf(node), near2.t);
+      const near = nearestStrokePosition(g.line, [local.x, local.y]);
+      const inserted = insertWidthPoint(strokeWidthProfileOf(node), near.t);
       profile = inserted.points;
-      subpath = near2.contour;
-      t = near2.t;
+      subpath = near.contour;
+      t = near.t;
       ref = { nodeId: node.id, index: inserted.index, subpath };
-      if (input.alt) side = near2.side;
+      if (input.alt) side = near.side;
       this.widthPoints = [ref];
     }
     const at = strokePositionPoint(g.line, subpath, t);
@@ -7095,9 +6926,9 @@ var VectorEditorController = class {
         let index = drag.source;
         if (drag.mode !== "width") {
           const g = vectorStrokeWidthGeometry(node);
-          const near2 = g ? nearestStrokePosition(g.line, [local.x, local.y], drag.ref.subpath) : null;
-          if (!g || !near2) return;
-          const t = drag.group.length ? near2.t : this.snapWidthT(drag, node, g.line, near2.t, drag.source);
+          const near = g ? nearestStrokePosition(g.line, [local.x, local.y], drag.ref.subpath) : null;
+          if (!g || !near) return;
+          const t = drag.group.length ? near.t : this.snapWidthT(drag, node, g.line, near.t, drag.source);
           if (drag.mode === "copy") {
             ({ points: profile, index } = insertWidthPoint(drag.profile, t, { left: src.left, right: src.right }, { step: true }));
           } else if (drag.group.length) {
@@ -7456,6 +7287,10 @@ var VectorEditorController = class {
           return true;
         case "j":
           return input.alt ? this.averageAnchors("both").ok : this.joinPaths().ok;
+        // Make Clipping Mask; with Alt, Release (Option-7 types ¶ on a Mac).
+        case "7":
+        case "\xB6":
+          return input.alt || key === "\xB6" ? this.releaseMask().length > 0 : this.makeMask("clip").ok;
         case "]":
           this.arrange(input.alt ? "front" : "forward");
           return true;
@@ -7663,13 +7498,17 @@ function renderNode(stored, defs, filters, idPrefix) {
   if (stored.visible === false) return null;
   const node = expandVectorAppearance(stored);
   if (node.type === "group") {
-    const children = node.children.map((c) => renderNode(c, defs, filters, idPrefix)).filter((c) => !!c);
+    const finish2 = nodeFinish(node, filters, idPrefix);
+    const masked = isVectorMaskGroup(node) ? renderMask(node, defs, filters, idPrefix) : null;
+    const list = isVectorMaskGroup(node) ? node.children.slice(1) : node.children;
+    const children = list.map((c) => renderNode(c, defs, filters, idPrefix)).filter((c) => !!c);
     return {
       kind: "group",
       id: node.id,
       ...node.transform ? { transform: fmtMatrix(node.transform) } : {},
       opacity: node.opacity ?? 1,
-      ...nodeFinish(node, filters, idPrefix),
+      ...finish2,
+      ...masked ? { mask: masked } : {},
       children
     };
   }
@@ -7711,6 +7550,16 @@ function renderNode(stored, defs, filters, idPrefix) {
     ...lineStyle(node)
   };
 }
+function renderMask(group, defs, filters, idPrefix) {
+  if (!isVectorMaskActive(group)) return null;
+  const data = vectorMaskRenderData(group, `${idPrefix}mask-${group.id}`, `${idPrefix}mask-filter-${group.id}`);
+  if (!data) return null;
+  const { invertFilter, ...mask } = data;
+  if (invertFilter) filters.push(invertFilter);
+  if (mask.type === "clip") return mask;
+  const source = renderNode(group.children[0], defs, filters, idPrefix);
+  return { ...mask, nodes: source ? [source] : [] };
+}
 function getVectorSceneRenderData(state, options = {}) {
   const defs = [];
   const filters = [];
@@ -7737,7 +7586,7 @@ function screenOutline(state, node, entered) {
 function outlinePaths(node, parent, entered) {
   if (node.type === "path") return [vectorPathWorldBezier(node, parent, { effects: false })];
   const m = multiplyMatrices(nodeMatrix(node), parent);
-  if (hasOwnVectorAppearance(node) && !entered.has(node.id)) return [transformBezierPath(vectorAppearanceOutline(node), m)];
+  if ((hasOwnVectorAppearance(node) || isVectorMaskActive(node)) && !entered.has(node.id)) return [transformBezierPath(vectorAppearanceOutline(node), m)];
   return node.children.filter((c) => c.visible !== false).flatMap((c) => outlinePaths(c, m, entered));
 }
 function getVectorEnteredGroups(state) {
@@ -7901,7 +7750,35 @@ function getVectorOverlayRenderData(state) {
   }
   const envelope = state.tool === "envelope" ? envelopeOverlay(state) : null;
   if (state.tool === "envelope" && !envelope && !it) status = "Select an object with an envelope to edit its mesh";
-  return { outlines, selectionBox, distort, anchors, handles, marquee, penPreview, artboard, guides, status, toolStroke, pencilString, cutPoint, cornerWidgets, widthPoints, widthSpot, builder, blend, gradient, envelope };
+  return { outlines, selectionBox, distort, anchors, handles, marquee, penPreview, artboard, guides, status, toolStroke, pencilString, cutPoint, cornerWidgets, widthPoints, widthSpot, builder, blend, gradient, envelope, masks: maskOverlay(state) };
+}
+function maskOverlay(state) {
+  const ids = state.editingId ? [...state.selection, state.editingId] : state.selection;
+  if (!ids.length) return [];
+  const want = new Set(ids);
+  const v = state.viewport;
+  const view = [v.zoom, 0, 0, v.zoom, v.x, v.y];
+  const out = [];
+  const visit = (list, parent) => {
+    let any = false;
+    for (const n of list) {
+      if (n.type !== "group") {
+        if (want.has(n.id)) any = true;
+        continue;
+      }
+      const m = multiplyMatrices(nodeMatrix(n), parent);
+      const inside = visit(n.children, m);
+      const hit = want.has(n.id) || inside;
+      if (hit) any = true;
+      if (!hit || !isVectorMaskGroup(n)) continue;
+      const summary = vectorMaskSummary(n);
+      const d = outlinePaths(n.children[0], m, /* @__PURE__ */ new Set()).map((path) => bezierPathToSvg(transformBezierPath(path, view), { precision: 2 })).join(" ");
+      out.push({ id: n.id, maskId: summary.maskId, d, type: summary.type, invert: summary.invert, enabled: summary.enabled, editing: want.has(summary.maskId) });
+    }
+    return any;
+  };
+  visit(state.document.nodes, IDENTITY_MATRIX);
+  return out;
 }
 function envelopeOverlay(state) {
   const target = getVectorEnvelopeTarget(state.document, state.selection);
@@ -8069,7 +7946,10 @@ var VECTOR_OVERLAY_THEME = {
   builderErase: "#ef4444",
   builderEraseFill: "rgba(239, 68, 68, 0.22)",
   /** Opacity of the hatch lines over Shape Builder faces (drawn in the face's outline colour). */
-  builderHatchOpacity: 0.6
+  builderHatchOpacity: 0.6,
+  /** Mask indicators: the outline of a selected mask group's mask (dashed; solid while the mask is selected). */
+  mask: "#8b5cf6",
+  maskDash: "5 3"
 };
 function vectorDiamondPath(x, y, r = VECTOR_OVERLAY_THEME.widthPointSize) {
   return `M${fmt2(x)} ${fmt2(y - r)}L${fmt2(x + r)} ${fmt2(y)}L${fmt2(x)} ${fmt2(y + r)}L${fmt2(x - r)} ${fmt2(y)}Z`;
@@ -8318,6 +8198,32 @@ function getVectorAppearancePanel(state) {
   };
 }
 var VECTOR_BLEND_MODE_MENU = VECTOR_BLEND_MODES.map((mode) => ({ mode, label: VECTOR_BLEND_MODE_LABELS[mode] }));
+var VECTOR_MASK_TYPE_LABELS = { clip: "Clip", alpha: "Alpha", luminance: "Luminance" };
+var VECTOR_MASK_TYPE_OPTIONS = [
+  { value: "clip", label: "Clip", title: "Clipping mask: the contents show inside the mask's outline" },
+  { value: "luminance", label: "Luminance", title: "Opacity mask by brightness: white shows, black hides" },
+  { value: "alpha", label: "Alpha", title: "Opacity mask by opacity: opaque shows, transparent hides" }
+];
+function getVectorMaskPanel(state) {
+  const doc = state.document;
+  if (!state.selection.length) return null;
+  const locs = state.selection.map((id) => locateVectorNode(doc.nodes, id));
+  let makeHint = null;
+  if (state.selection.length < 2) makeHint = "Select two or more objects: the topmost becomes the mask.";
+  else if (locs.some((l) => !l)) makeHint = "Select objects in the document.";
+  else if (locs.some((l) => l.list[l.index].locked || l.list[l.index].blendStep)) makeHint = "Unlock the selected objects first.";
+  else if (locs.some((l) => (l.parent?.id ?? null) !== (locs[0].parent?.id ?? null))) makeHint = "Select objects at one level (sharing a parent).";
+  let group = null;
+  const first = locs[0];
+  const node = first ? first.list[first.index] : null;
+  const owner = isVectorMaskGroup(node) ? node : isVectorMaskGroup(first?.parent) ? first.parent : null;
+  if (owner && state.selection.every((id) => id === owner.id || owner.children.some((c) => c.id === id))) {
+    const summary = vectorMaskSummary(owner);
+    const editing = state.selection.includes(owner.id) ? "group" : state.selection.includes(summary.maskId) ? "mask" : "contents";
+    group = { ...summary, id: owner.id, ...owner.name ? { name: owner.name } : {}, editing };
+  }
+  return { canMake: makeHint === null, makeHint, group };
+}
 
 // src/vector/commands.ts
 var EFFECT_PARAMS_DESCRIPTION = "Effect parameters (missing ones keep their value or default). trim: start, end (percent), offset (degrees), mode simultaneous|individual. roundCorners: radius. puckerBloat: amount (\u2212100\u2026100). twist: angle, center {x, y} (offset from the middle). zigzag: size, ridges, smooth. wiggle: size, detail, smooth, speed, correlation, phase, seed, time (seconds). offset: amount, join miter|round|bevel, miterLimit, copies, copyOffset. merge: mode merge|add|subtract|intersect|exclude. repeater: copies (fractions fade the last), offset, position {x, y}, anchor {x, y} (offset from the middle), rotation, scale {x, y} (percent), startOpacity, endOpacity (percent), composite below|above. envelope: style (a warp preset: arc|arcLower|arcUpper|arch|bulge|shellLower|shellUpper|flag|wave|fish|rise|fisheye|inflate|squeeze|twist, or mesh), bend, horizontal, vertical (percent, \u2212100\u2026100), orientation horizontal|vertical, rows, columns, mesh { us, vs, points } (node space; prefer vector.envelope).";
@@ -8504,7 +8410,8 @@ function createVectorCommands(controller, options = {}) {
           ...n.type === "path" && Array.isArray(n.fills) ? { fills: n.fills } : {},
           ...n.type === "path" && Array.isArray(n.strokes) ? { strokes: n.strokes } : {},
           ...n.blendMode && n.blendMode !== "normal" ? { blendMode: n.blendMode } : {},
-          ...n.filters?.length ? { filters: n.filters } : {}
+          ...n.filters?.length ? { filters: n.filters } : {},
+          ...isVectorMaskGroup(n) ? { mask: vectorMaskSummary(n) } : {}
         });
         if (n.type === "group") visit(n.children, depth + 1);
       }
@@ -8652,6 +8559,105 @@ function createVectorCommands(controller, options = {}) {
     const node = controller.getNode(nodeId) ?? fail(`There is no node "${nodeId}".`);
     return node.filters?.find((f) => f.id === filterId) ?? fail(`Node "${nodeId}" has no filter "${filterId}"; it has ${(node.filters ?? []).map((f) => `"${f.id}" (${f.type})`).join(", ") || "none"}.`);
   };
+  const maskResult = (id) => ({ id, mask: vectorMaskSummary(controller.getNode(id)) ?? fail(`"${id}" is not a mask group.`) });
+  const maskInputs = (params) => {
+    const list2 = [...new Set(ids(params))];
+    if (list2.length < 2) fail(`Masking needs at least two objects (the mask and what it masks); got ${list2.length}. Pass ids, or select more.`);
+    for (const id of list2) if (controller.getNode(id).locked) fail(`"${id}" is locked; ask the user to unlock it, or leave it out of ids.`);
+    if (params?.maskId !== void 0 && !list2.includes(params.maskId)) fail(`maskId "${params.maskId}" must be one of ids (${list2.map((id) => `"${id}"`).join(", ")}).`);
+    return list2;
+  };
+  const maskTargets = (params) => {
+    const list2 = ids(params);
+    const groups = list2.map((id) => controller.getNode(id)).filter((n) => isVectorMaskGroup(n));
+    if (!groups.length) fail(`None of ${list2.map((id) => `"${id}"`).join(", ")} is a mask group. Mask groups have a \`mask\` in vector.list; make one with vector.makeClippingMask or vector.makeOpacityMask.`);
+    return groups.map((g) => g.id);
+  };
+  const MASK_INPUT = {
+    ids: { ...IDS, description: "The objects to mask with, two or more sharing a parent (default: the selection). The topmost becomes the mask unless maskId says otherwise." },
+    maskId: { type: "string", description: "Which of ids is the mask (default: the topmost)." },
+    invert: { type: "boolean", description: "Show the contents only where the mask hides them (default false)." }
+  };
+  const maskCommands = () => [
+    {
+      ...base,
+      id: `${prefix}makeClippingMask`,
+      label: "Make Clipping Mask",
+      keywords: ["mask", "clip", "clipping", "clip path", "crop", "inside"],
+      shortcut: "Mod+7",
+      description: "Groups objects into a clipping mask group: the mask (the topmost object, or maskId) moves to the bottom of the new group and the others show only inside its outline (its paint is not drawn; every path in it counts, by its fill rule). Hit-testing, bounds, snapping and booleans use the clipped result. One undo step. Returns { id, mask: { type, invert, maskId, contents, enabled } }.",
+      params: { type: "object", properties: MASK_INPUT, additionalProperties: false },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const list2 = maskInputs(params);
+        const r = controller.makeMask("clip", { ids: list2, ...params?.maskId ? { maskId: params.maskId } : {}, invert: params?.invert });
+        if (!r.ok) fail(r.message);
+        return maskResult(r.id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}makeOpacityMask`,
+      label: "Make Opacity Mask",
+      keywords: ["mask", "opacity mask", "alpha", "luminance", "fade", "gradient mask", "soft mask"],
+      description: "Groups objects into an opacity mask group: the mask (the topmost object, or maskId) moves to the bottom of the new group and hides the others where it is dark (luminance: white shows, black hides) or transparent (alpha). A gradient mask fades the contents. One undo step. Returns { id, mask: { type, invert, maskId, contents, enabled } }.",
+      params: {
+        type: "object",
+        properties: { ...MASK_INPUT, type: { type: "string", enum: ["luminance", "alpha"], description: "luminance (by brightness, the default) or alpha (by opacity)." } },
+        additionalProperties: false
+      },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const list2 = maskInputs(params);
+        const r = controller.makeMask(params?.type ?? "luminance", { ids: list2, ...params?.maskId ? { maskId: params.maskId } : {}, invert: params?.invert });
+        if (!r.ok) fail(r.message);
+        return maskResult(r.id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setMaskOptions`,
+      label: "Mask Options\u2026",
+      keywords: ["mask", "clip", "invert", "alpha", "luminance", "opacity mask"],
+      description: "Changes how mask groups mask: `type` clip (by outline), alpha or luminance, `invert`, and `enabled` (false hides the mask so the contents draw whole; true shows it again). Pass at least one. One undo step. Returns { groups: [{ id, mask }] }.",
+      params: {
+        type: "object",
+        properties: {
+          ids: { ...IDS, description: "Mask group ids (default: the selection)." },
+          type: { type: "string", enum: ["clip", "alpha", "luminance"], description: "clip (the mask's outline), alpha (its opacity) or luminance (its brightness)." },
+          invert: { type: "boolean", description: "true: show the contents where the mask hides them." },
+          enabled: { type: "boolean", description: "false: turn the mask off (it is hidden and the contents draw whole); true: on again." }
+        },
+        additionalProperties: false
+      },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        if (params?.type === void 0 && params?.invert === void 0 && params?.enabled === void 0) fail("Pass at least one of type, invert, enabled.");
+        const groups = maskTargets(params);
+        const patch = { ...params?.type ? { type: params.type } : {}, ...params?.invert !== void 0 ? { invert: params.invert } : {}, ...params?.enabled !== void 0 ? { enabled: params.enabled } : {} };
+        check(controller.setMaskOptions(patch, { ids: groups }));
+        return { groups: groups.map(maskResult) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}releaseMask`,
+      label: "Release Mask",
+      keywords: ["mask", "clip", "release", "unmask", "remove mask"],
+      shortcut: "Mod+Alt+7",
+      description: "Releases mask groups: the mask goes back on top of the contents and draws as itself again; the group is replaced by its children unless it has filters, a blend mode or path effects (then it stays a plain group). One undo step. Returns { ids } of the released objects (the mask last).",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Mask group ids (default: the selection)." } }, additionalProperties: false },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const groups = maskTargets(params);
+        return { ids: controller.releaseMask({ ids: groups }) };
+      }
+    }
+  ];
   const appearanceCommands = () => [
     {
       ...base,
@@ -8888,6 +8894,7 @@ function createVectorCommands(controller, options = {}) {
       }
     },
     ...appearanceCommands(),
+    ...maskCommands(),
     {
       ...base,
       id: `${prefix}setCorners`,
@@ -9709,6 +9716,9 @@ export {
   VECTOR_GRADIENT_TYPES,
   VECTOR_GRADIENT_TYPE_LABELS,
   VECTOR_INK_MAX_CORNERS,
+  VECTOR_MASK_TYPES,
+  VECTOR_MASK_TYPE_LABELS,
+  VECTOR_MASK_TYPE_OPTIONS,
   VECTOR_MERGE_MODES,
   VECTOR_OVERLAY_THEME,
   VECTOR_PATHFINDER_ACTIONS,
@@ -9814,6 +9824,7 @@ export {
   getVectorEnvelopeTarget,
   getVectorGradientAnnotator,
   getVectorGradientEditor,
+  getVectorMaskPanel,
   getVectorOverlayRenderData,
   getVectorSceneRenderData,
   getVectorSelectionBoxGeometry,
@@ -9860,6 +9871,9 @@ export {
   isVectorFilterType,
   isVectorGradient,
   isVectorLiveBoolean,
+  isVectorMaskActive,
+  isVectorMaskGroup,
+  isVectorMaskType,
   isVectorTextTarget,
   joinSubpaths,
   knifePath,
@@ -9937,6 +9951,7 @@ export {
   sanitizeVectorFills,
   sanitizeVectorFilters,
   sanitizeVectorGradient,
+  sanitizeVectorMask,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
   sanitizeWidthProfile,
@@ -9997,6 +10012,7 @@ export {
   vectorBoxCorners,
   vectorBoxMatrix,
   vectorBuilderErasedEdges,
+  vectorChildAppearanceShapes,
   vectorCornerAt,
   vectorCorners,
   vectorCornersAttribute,
@@ -10036,6 +10052,19 @@ export {
   identityWarpMesh as vectorIdentityMesh,
   vectorInkShapeName,
   vectorLiveBooleanSteps,
+  vectorMaskContains,
+  vectorMaskContentBounds,
+  vectorMaskContents,
+  vectorMaskOwner,
+  vectorMaskRegion,
+  vectorMaskRegionPath,
+  vectorMaskRegionShapes,
+  vectorMaskRenderData,
+  vectorMaskSource,
+  vectorMaskSummary,
+  vectorMaskedGeometry,
+  vectorMaskedLocalBounds,
+  vectorMaskedShapes,
   warpMeshColumns as vectorMeshColumns,
   warpMeshControlBounds as vectorMeshControlBounds,
   warpMeshEditPoints as vectorMeshEditPoints,