@pixerate/editor 0.117.0 → 0.119.0

package/dist/vector/index.js

@@ -40,7 +40,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-T2P5TIZ6.js";
+} from "../chunk-TDQDMBUR.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -83,6 +83,8 @@ import {
   VECTOR_STROKE_GRADIENT_MODES,
   VECTOR_STROKE_SETTING_KEYS,
   VECTOR_SYMBOL_MAX_DEPTH,
+  VECTOR_SYMMETRY_MODES,
+  VECTOR_SYMMETRY_MODE_LABELS,
   VECTOR_TEXT_ALIGNS,
   VECTOR_TOOLS,
   VECTOR_TRANSFORM_HANDLES,
@@ -200,6 +202,7 @@ import {
   isVectorMaskType,
   isVectorMeshGradient,
   isVectorShadedPaint,
+  isVectorSymmetryGroup,
   knifePath,
   layoutVectorText,
   lineSubpath,
@@ -284,6 +287,7 @@ import {
   sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
+  sanitizeVectorSymmetry,
   sanitizeVectorTextFields,
   sanitizeVectorTextFrame,
   sanitizeWidthProfile,
@@ -316,6 +320,7 @@ import {
   transformVectorNode,
   transformVectorPaint,
   transformVectorShadedPaint,
+  transformVectorSymmetry,
   translateAnchor,
   translateMatrix,
   trimIntervals,
@@ -429,6 +434,9 @@ import {
   vectorStrokes,
   vectorSymbolUses,
   vectorSymbolsUsedIn,
+  vectorSymmetryAxes,
+  vectorSymmetryDrawn,
+  vectorSymmetryMatrices,
   vectorTargetPaint,
   vectorTextBoxOutline,
   vectorTextCaret,
@@ -467,7 +475,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-7LNZAWSJ.js";
+} from "../chunk-CSHEI3YT.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -2167,7 +2175,24 @@ function renderText(node, defs, filters, idPrefix) {
     spans
   };
 }
+var renderCache = /* @__PURE__ */ new WeakMap();
 function renderNode(stored, defs, filters, idPrefix) {
+  const gen = vectorTextShaperGeneration();
+  let byPrefix = renderCache.get(stored);
+  const hit = byPrefix?.get(idPrefix);
+  if (hit && hit.gen === gen) {
+    defs.push(...hit.defs);
+    filters.push(...hit.filters);
+    return hit.node;
+  }
+  const d0 = defs.length;
+  const f0 = filters.length;
+  const node = renderNodeFresh(stored, defs, filters, idPrefix);
+  if (!byPrefix) renderCache.set(stored, byPrefix = /* @__PURE__ */ new Map());
+  byPrefix.set(idPrefix, { gen, node, defs: defs.slice(d0), filters: filters.slice(f0) });
+  return node;
+}
+function renderNodeFresh(stored, defs, filters, idPrefix) {
   if (stored.visible === false) return null;
   if (stored.type === "text" && !vectorTextHasOutlines()) return renderText(stored, defs, filters, idPrefix);
   const node = expandVectorAppearance(stored);
@@ -2234,13 +2259,64 @@ function renderMask(group, defs, filters, idPrefix) {
   const source = renderNode(group.children[0], defs, filters, idPrefix);
   return { ...mask, nodes: source ? [source] : [] };
 }
+var collapsedCache = /* @__PURE__ */ new WeakMap();
+function collapsedNode(node, box, prefix) {
+  let byPrefix = collapsedCache.get(node);
+  if (byPrefix?.has(prefix)) return byPrefix.get(prefix);
+  let fill = null;
+  const look = (n2) => {
+    if (fill || n2.visible === false) return;
+    if (n2.type === "path" || n2.type === "text") {
+      const f = n2.fill;
+      if (typeof f === "string" && f !== "none") fill = f;
+      else if (isVectorGradient(f)) fill = f.stops[0]?.color ?? null;
+    } else if (n2.type === "group") n2.children.forEach(look);
+    else if (n2.type === "instance") (n2.art ?? []).forEach(look);
+  };
+  look(node);
+  const out = fill ? { kind: "path", id: node.id, d: `M${fmt2(box.minX)} ${fmt2(box.minY)}H${fmt2(box.maxX)}V${fmt2(box.maxY)}H${fmt2(box.minX)}Z`, fill, stroke: "none", strokeWidth: 0, fillRule: "nonzero", opacity: node.opacity ?? 1 } : null;
+  if (!byPrefix) collapsedCache.set(node, byPrefix = /* @__PURE__ */ new Map());
+  byPrefix.set(prefix, out);
+  return out;
+}
 function getVectorSceneRenderData(state, options = {}) {
   const defs = [];
   const filters = [];
   const prefix = options.idPrefix ?? "ve-";
-  const nodes = state.document.nodes.map((n2) => renderNode(n2, defs, filters, prefix)).filter((n2) => !!n2);
   const v = state.viewport;
+  const all = state.document.nodes;
+  const stats = { nodes: all.length, culled: 0, collapsed: 0 };
+  let nodes;
+  const size = options.viewportSize;
+  if (size && size.width > 0 && size.height > 0 && v.zoom > 0) {
+    const z = v.zoom;
+    const pad = 2 / z;
+    const view = { minX: -v.x / z - pad, minY: -v.y / z - pad, maxX: (size.width - v.x) / z + pad, maxY: (size.height - v.y) / z + pad };
+    const lod = options.lod ?? 2;
+    const near = vectorNodesNear(all, { x: view.minX, y: view.minY, width: view.maxX - view.minX, height: view.maxY - view.minY });
+    stats.culled = all.length - near.length;
+    nodes = [];
+    for (const i of near) {
+      const n2 = all[i];
+      const box = vectorNodePaintBox(n2);
+      if (box && (box.maxX < view.minX || box.minX > view.maxX || box.maxY < view.minY || box.minY > view.maxY)) {
+        stats.culled++;
+        continue;
+      }
+      if (box && lod > 0 && n2.type !== "path" && n2.visible !== false && Math.max(box.maxX - box.minX, box.maxY - box.minY) * z < lod) {
+        const c = collapsedNode(n2, box, prefix);
+        if (c) {
+          stats.collapsed++;
+          nodes.push(c);
+          continue;
+        }
+      }
+      const r = renderNode(n2, defs, filters, prefix);
+      if (r) nodes.push(r);
+    }
+  } else nodes = all.map((n2) => renderNode(n2, defs, filters, prefix)).filter((n2) => !!n2);
   return {
+    stats,
     transform: `translate(${fmt2(v.x)} ${fmt2(v.y)}) scale(${v.zoom})`,
     width: state.document.width,
     height: state.document.height,
@@ -2303,6 +2379,46 @@ function shadingOverlay(state) {
   }
   return out;
 }
+function symmetryOverlay(state) {
+  const ids = /* @__PURE__ */ new Set([...state.selection, ...state.symmetryTarget ? [state.symmetryTarget] : []]);
+  const out = [];
+  for (const id of ids) {
+    const n2 = findVectorNode(state.document.nodes, id);
+    if (!isVectorSymmetryGroup(n2)) continue;
+    const world = vectorWorldMatrix(state.document.nodes, id);
+    if (!world) continue;
+    const inv = invertMatrix(world);
+    const corners2 = [
+      { x: 0, y: 0 },
+      { x: state.document.width, y: 0 },
+      { x: 0, y: state.document.height },
+      { x: state.document.width, y: state.document.height }
+    ].map((p) => applyMatrix(inv, p));
+    const { transform: _t, ...own } = n2;
+    const b = unionBoxes([vectorNodeBounds(own), boundsFromCorners(corners2)]);
+    if (!b) continue;
+    const pad = Math.max(b.width, b.height) * 0.05;
+    const lines = vectorSymmetryAxes(n2.symmetry, { x: b.x - pad, y: b.y - pad, width: b.width + 2 * pad, height: b.height + 2 * pad }).map(([a, c]) => {
+      const p = toScreen(state, applyMatrix(world, a));
+      const q = toScreen(state, applyMatrix(world, c));
+      return { x1: p.x, y1: p.y, x2: q.x, y2: q.y };
+    });
+    out.push({ nodeId: id, drawing: state.symmetryTarget === id, lines });
+  }
+  return out;
+}
+function unionBoxes(list) {
+  const ok = list.filter((b) => !!b);
+  if (!ok.length) return null;
+  const x = Math.min(...ok.map((b) => b.x));
+  const y = Math.min(...ok.map((b) => b.y));
+  return { x, y, width: Math.max(...ok.map((b) => b.x + b.width)) - x, height: Math.max(...ok.map((b) => b.y + b.height)) - y };
+}
+function boundsFromCorners(pts) {
+  const xs = pts.map((p) => p.x);
+  const ys = pts.map((p) => p.y);
+  return { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+}
 function connectorSiteOverlay(state) {
   if (state.tool !== "connector" || !state.pointer) return [];
   const drawing = state.interaction?.type === "draw" && state.interaction.tool === "connector" ? state.interaction.nodeId : void 0;
@@ -2575,6 +2691,7 @@ function getVectorOverlayRenderData(state) {
     frames: frameLabels(state),
     connectorSites: connectorSiteOverlay(state),
     shading: shadingOverlay(state),
+    symmetry: symmetryOverlay(state),
     trackingPoints: (state.trackingPoints ?? []).map((p) => toScreen(state, p)),
     typedEntry: state.typedEntry ? { text: state.typedEntry, ...state.pointer ? toScreen(state, state.pointer) : { x: 0, y: 0 } } : null
   };
@@ -3595,9 +3712,9 @@ function nodeGroup(node, notes) {
   if (node.filters?.length) notes.push(`${label(node)}: filters (shadows, glows, blurs) are not part of Lottie (left out).`);
   const m = nodeMatrix(node);
   let items = [];
-  const live = (node.effects ?? []).some((e) => e.enabled !== false && (e.type === "wiggle" || e.type === "envelope"));
-  if (node.type === "text" || node.type === "instance" || live || isVectorMaskGroup(node) || isVectorFrame(node)) {
-    if (live) notes.push(`${label(node)}: wiggle and envelope effects have no Lottie equivalent (exported as drawn).`);
+  const live = (node.effects ?? []).some((e) => e.enabled !== false && (e.type === "wiggle" || e.type === "envelope" || e.type === "contour"));
+  if (node.type === "text" || node.type === "instance" || live || isVectorMaskGroup(node) || isVectorFrame(node) || isVectorSymmetryGroup(node)) {
+    if (live) notes.push(`${label(node)}: wiggle, envelope and contour effects have no Lottie equivalent (exported as drawn).`);
     if (isVectorMaskGroup(node) && node.mask?.type !== "clip") notes.push(`${label(node)}: opacity masks are not exported (the contents are drawn whole).`);
     const drawn = isVectorFrame(node) ? vectorFrameDrawn(node) : node;
     const shapes = isVectorMaskGroup(drawn) && drawn.mask?.type === "clip" ? vectorAppearanceShapes({ ...drawn, transform: void 0 }) : null;
@@ -6831,6 +6948,7 @@ var VectorEditorController = class _VectorEditorController {
       trackingPoints: this.trackingPoints,
       typedEntry: this.typed,
       shadingPoint: this.getShadingSelection(),
+      symmetryTarget: this.symmetryTarget && this.doc.nodes.some((n2) => n2.id === this.symmetryTarget) ? this.symmetryTarget : null,
       canUndo: h.canUndo,
       canRedo: h.canRedo,
       undoLabel: h.undoName,
@@ -9134,6 +9252,155 @@ var VectorEditorController = class _VectorEditorController {
     return { ok: true, id };
   }
   // -----------------------------------------------------------------------------------------
+  // Live symmetry groups
+  /** The symmetry group new pen, pencil, shape and text art goes into (see `enterSymmetry`), or null. */
+  symmetryTarget = null;
+  /** The symmetry group drawn art goes into, while it is entered and still a top-level, unturned symmetry group. */
+  drawingTarget() {
+    const id = this.symmetryTarget;
+    if (!id) return null;
+    const n2 = this.doc.nodes.find((x) => x.id === id);
+    if (!isVectorSymmetryGroup(n2) || n2.transform || n2.locked) {
+      this.symmetryTarget = null;
+      return null;
+    }
+    return n2;
+  }
+  /** Adds a node a drawing tool makes: into the entered symmetry group, else on top. */
+  addDrawn(node) {
+    const target = this.tool === "frame" || this.tool === "connector" ? null : this.drawingTarget();
+    if (!target) return this.setDoc([...this.doc.nodes, node]);
+    this.setDoc(this.doc.nodes.map((n2) => n2.id === target.id && n2.type === "group" ? { ...n2, children: [...n2.children, node] } : n2));
+  }
+  /**
+   * Make Symmetry: puts objects that share a parent (default: the selection) into a live symmetry
+   * group that draws them with their mirrored or rotated copies, the axes through `center`
+   * (default: the objects' centre, or the artboard's when there are none, making an empty group to
+   * draw into). One undo step; selects the group (and enters it when empty). Returns its id.
+   */
+  makeSymmetry(input, options = {}) {
+    const symmetry = sanitizeVectorSymmetry({ ...input, center: input.center ?? { x: 0, y: 0 } });
+    if (!symmetry) return { ok: false, message: `Unknown symmetry "${input.mode}": use ${VECTOR_SYMMETRY_MODES.join(", ")}.` };
+    if (input.copies !== void 0 && !(input.copies >= 2 && input.copies <= 64)) return { ok: false, message: "copies must be from 2 to 64." };
+    const ids = [...new Set(options.ids ?? this.selectedRoots())];
+    for (const id2 of ids) {
+      const n2 = this.getNode(id2);
+      if (!n2) return { ok: false, message: `There is no node "${id2}".` };
+      if (n2.locked) return { ok: false, message: `"${id2}" is locked; unlock it first.` };
+    }
+    const locs = ids.map((id2) => locateVectorNode(this.doc.nodes, id2));
+    const parent = locs[0]?.parent ?? null;
+    if (locs.some((l) => (l.parent?.id ?? null) !== (parent?.id ?? null))) return { ok: false, message: "The objects must share a parent (pick objects at one level)." };
+    const b = unionBounds(ids.map((id2) => vectorNodeBounds(this.getNode(id2))));
+    const center = input.center ?? (b ? { x: b.x + b.width / 2, y: b.y + b.height / 2 } : { x: this.doc.width / 2, y: this.doc.height / 2 });
+    const id = this.newId();
+    const group = { id, type: "group", name: input.name ?? "Symmetry", symmetry: { ...symmetry, center }, children: [] };
+    const order = ids.slice().sort((a, c) => locs[ids.indexOf(a)].index - locs[ids.indexOf(c)].index);
+    const set = new Set(order);
+    this.change("Make Symmetry", () => {
+      if (!order.length) this.setDoc([...this.doc.nodes, group]);
+      else {
+        const regroup = (list) => {
+          const members = order.map((m) => list.find((n2) => n2.id === m));
+          const top = Math.max(...members.map((m) => list.indexOf(m)));
+          const out = [];
+          list.forEach((n2, i) => {
+            if (i === top) out.push({ ...group, children: members });
+            if (!set.has(n2.id)) out.push(n2);
+          });
+          return out;
+        };
+        if (!parent) this.setDoc(regroup(this.doc.nodes));
+        else this.setDoc(mapTree(this.doc.nodes, (n2) => n2.id === parent.id && n2.type === "group" ? { ...n2, children: regroup(n2.children) } : n2));
+      }
+      this.selection = [id];
+      this.anchors = [];
+      this.editingId = null;
+      if (!order.length && !parent) this.symmetryTarget = id;
+    });
+    return { ok: true, id };
+  }
+  /** Symmetry groups among `ids` (default: the selection, or the group holding it). */
+  symmetryTargets(ids) {
+    const out = /* @__PURE__ */ new Map();
+    for (const id of ids ?? this.selection) {
+      const n2 = this.getNode(id);
+      if (isVectorSymmetryGroup(n2)) out.set(n2.id, n2);
+      else if (!ids) {
+        const p = locateVectorNode(this.doc.nodes, id)?.parent;
+        if (isVectorSymmetryGroup(p)) out.set(p.id, p);
+      }
+    }
+    return [...out.values()];
+  }
+  /** Changes symmetry groups (default: the selected one, or the one holding the selection): mode, centre (the group's space), rotation, radial copies and mirroring. One undo step (merged while `merge` is the same key). */
+  setSymmetry(patch, options = {}) {
+    if (options.ids) {
+      for (const id of options.ids) if (!isVectorSymmetryGroup(this.getNode(id))) return { ok: false, message: `"${id}" is not a symmetry group (make one with vector.makeSymmetry).` };
+    }
+    const groups = this.symmetryTargets(options.ids);
+    if (!groups.length) return { ok: false, message: "Select a symmetry group (or something in one)." };
+    if (patch.mode !== void 0 && !VECTOR_SYMMETRY_MODES.includes(patch.mode)) return { ok: false, message: `Unknown symmetry "${patch.mode}": use ${VECTOR_SYMMETRY_MODES.join(", ")}.` };
+    if (patch.copies !== void 0 && !(patch.copies >= 2 && patch.copies <= 64)) return { ok: false, message: "copies must be from 2 to 64." };
+    const next = new Map(groups.map((g) => [g.id, sanitizeVectorSymmetry({ ...g.symmetry, ...patch })]));
+    if ([...next.values()].some((v) => !v)) return { ok: false, message: "center must be { x, y } numbers." };
+    this.change(
+      "Symmetry",
+      () => {
+        this.setDoc(mapTree(this.doc.nodes, (n2) => next.has(n2.id) && n2.type === "group" ? { ...n2, symmetry: next.get(n2.id) } : n2));
+      },
+      options.merge
+    );
+    return { ok: true };
+  }
+  /**
+   * Release Symmetry: the groups stop repeating their children. With `expand`, the copies become
+   * real objects in the group (new ids); otherwise they go. One undo step. Returns the ids of the
+   * objects added by expanding.
+   */
+  releaseSymmetry(options = {}) {
+    const groups = this.symmetryTargets(options.ids);
+    if (!groups.length) return { ok: false, message: "Select a symmetry group (or something in one)." };
+    const added = [];
+    const next = /* @__PURE__ */ new Map();
+    for (const g of groups) {
+      const { symmetry: _s, ...rest } = g;
+      if (!options.expand) {
+        next.set(g.id, rest);
+        continue;
+      }
+      const drawn = vectorSymmetryDrawn(g);
+      const fresh = (n2) => {
+        const id = this.newId();
+        added.push(id);
+        const { locked: _l, ...plain2 } = n2;
+        return plain2.type === "group" ? { ...plain2, id, children: plain2.children.map(fresh) } : { ...plain2, id };
+      };
+      next.set(g.id, { ...rest, children: [...g.children, ...drawn.children.slice(g.children.length).map(fresh)] });
+    }
+    this.change(options.expand ? "Expand Symmetry" : "Release Symmetry", () => {
+      this.setDoc(mapTree(this.doc.nodes, (n2) => next.get(n2.id) ?? n2));
+      if (this.symmetryTarget && next.has(this.symmetryTarget)) this.symmetryTarget = null;
+    });
+    return { ok: true, ids: added.filter((id) => !!this.getNode(id)) };
+  }
+  /** Enters a top-level symmetry group: new pen, pencil, shape and text art goes into it (mirrored as it is drawn) until `exitSymmetry` or Escape. */
+  enterSymmetry(id) {
+    const n2 = this.doc.nodes.find((x) => x.id === id);
+    if (!isVectorSymmetryGroup(n2)) return { ok: false, message: `"${id}" is not a top-level symmetry group.` };
+    if (n2.transform) return { ok: false, message: "Drawing into a turned symmetry group is not supported; draw beside it and move the art in." };
+    this.symmetryTarget = id;
+    this.selection = [id];
+    this.notify();
+    return { ok: true };
+  }
+  /** Stops drawing into the entered symmetry group. */
+  exitSymmetry() {
+    if (!this.symmetryTarget) return;
+    this.symmetryTarget = null;
+    this.notify();
+  }
+  // -----------------------------------------------------------------------------------------
   // PDF
   /**
    * The document as a vector PDF (see `vectorDocumentToPdf`): one page of the artboard, or a page
@@ -11605,7 +11872,7 @@ var VectorEditorController = class _VectorEditorController {
     }
     const pt2 = this.snapDrawn(p, null, input, () => this.drawingTargets(null));
     const node = { id: this.newId(), type: "path", name: "Path", ...this.styleFor(true), subpaths: [{ anchors: [{ x: pt2.x, y: pt2.y }], closed: false }] };
-    this.setDoc([...this.doc.nodes, node]);
+    this.addDrawn(node);
     this.pen = { nodeId: node.id, subpath: 0 };
     this.selection = [node.id];
     this.editingId = node.id;
@@ -11626,7 +11893,7 @@ var VectorEditorController = class _VectorEditorController {
       strokeLinejoin: this.defaults.strokeLinejoin ?? "round",
       subpaths: [{ anchors: [{ x: p.x, y: p.y }], closed: false }]
     };
-    this.setDoc([...this.doc.nodes, node]);
+    this.addDrawn(node);
     const lazy = new LazyMouse(this.editing.pencilSmoothing * VECTOR_PENCIL_STRING_PX / this.viewport.zoom);
     lazy.push([p.x, p.y]);
     const mode = this.editing.pencilPressure;
@@ -11644,7 +11911,7 @@ var VectorEditorController = class _VectorEditorController {
     const kind = this.tool === "frame" ? "rect" : this.tool;
     const node = this.createShapeNode({ kind, x: start.x, y: start.y, width: 0, height: 0 });
     if (this.tool === "frame") Object.assign(node, { fill: "#ffffff", stroke: "#a3a3a3", strokeWidth: 1 / this.viewport.zoom });
-    this.setDoc([...this.doc.nodes, node]);
+    this.addDrawn(node);
     this.drag = { kind: "shape", tool: this.tool, start, nodeId: node.id, before, targets };
     this.interaction = { type: "draw", tool: this.tool, nodeId: node.id, bounds: { x: start.x, y: start.y, width: 0, height: 0 } };
     this.notify(true);
@@ -12787,7 +13054,7 @@ var VectorEditorController = class _VectorEditorController {
     this.endTextEdit();
     const before = this.snapshot();
     if (replace) this.setDoc(mapTree(this.doc.nodes, (n2) => n2.id === replace ? node : n2));
-    else this.setDoc([...this.doc.nodes, node]);
+    else this.addDrawn(node);
     this.selection = [node.id];
     this.anchors = [];
     this.textEdit = { nodeId: node.id, anchor: 0, focus: 0, before, key: `text-edit:${node.id}:${++this.textEditCount}`, created: true };
@@ -13341,6 +13608,7 @@ var VectorEditorController = class _VectorEditorController {
       case "Escape":
         if (this.drag) this.cancelDrag();
         else if (this.trackingPoints.length) this.clearTracking();
+        else if (this.symmetryTarget && !this.pen) this.exitSymmetry();
         else if (this.widthEdit) this.closeWidthPointEdit();
         else if (this.tool === "width" && this.widthPoints.length) {
           this.widthPoints = [];
@@ -13534,11 +13802,12 @@ function pencilPressureProfile(points, pressures) {
 }
 
 // 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).";
+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. contour: direction inside|outside|center, steps, offset, fillColor / strokeColor (end colours, null keeps the colour), acceleration (\u2212100\u2026100), join. 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).";
 var fail = (message) => {
   throw new Error(message);
 };
 var IDS = { type: "array", items: { type: "string" }, description: "Node ids (default: the selection)." };
+var PARENT_ID = { type: "string", description: "A group to add into, on top of its children (default: the document). Coordinates are the group's own space (the document's for an unturned top-level group)." };
 var ANCHORS = {
   type: "array",
   items: {
@@ -13678,6 +13947,11 @@ function createVectorCommands(controller, options = {}) {
   const prefix = options.prefix ?? "vector.";
   const group = options.group ?? "Vector";
   const base = { group, ...options.scope ? { scope: options.scope } : {} };
+  const parentOf = (parentId) => {
+    if (parentId === void 0) return {};
+    if (controller.getNode(parentId)?.type !== "group") fail(`"${parentId}" is not a group to add into.`);
+    return { parentId };
+  };
   const hasSelection = () => controller.getState().selection.length ? true : "Nothing is selected.";
   const ids = (params) => {
     const list2 = params?.ids ?? controller.getState().selection;
@@ -13724,7 +13998,8 @@ function createVectorCommands(controller, options = {}) {
           ...isVectorMaskGroup(n2) ? { mask: vectorMaskSummary(n2) } : {},
           ...isVectorFrame(n2) ? { frameRect: n2.frame } : {},
           ...n2.resizing ? { resizing: n2.resizing } : {},
-          ...n2.type === "path" && n2.connector ? { connector: n2.connector } : {}
+          ...n2.type === "path" && n2.connector ? { connector: n2.connector } : {},
+          ...n2.type === "group" && n2.symmetry ? { symmetry: n2.symmetry } : {}
         });
         if (n2.type === "group") visit(n2.children, depth + 1);
       }
@@ -14605,6 +14880,89 @@ function createVectorCommands(controller, options = {}) {
       issues: state.constraintIssues
     };
   };
+  const SYMMETRY_PROPS = {
+    mode: { type: "string", enum: VECTOR_SYMMETRY_MODES, description: "vertical (mirror left / right), horizontal (top / bottom), dual (four quarters), diagonal, or radial (turns round the centre)." },
+    center: { type: "object", properties: { x: { type: "number", description: "Document units (the group's space)." }, y: { type: "number", description: "Document units (the group's space)." } }, required: ["x", "y"], additionalProperties: false, description: "Where the axes cross." },
+    rotation: { type: "number", description: "Turn of the axes, degrees clockwise (default 0)." },
+    copies: { type: "integer", minimum: 2, maximum: 64, description: "Radial: how many turns round the circle (default 6)." },
+    mirror: { type: "boolean", description: "Radial: mirror each turn too, like a kaleidoscope (default false)." }
+  };
+  const symmetryResult = (id) => {
+    const n2 = controller.getNode(id);
+    return n2?.type === "group" && n2.symmetry ? { id, symmetry: n2.symmetry, children: n2.children.map((c) => c.id) } : fail(`"${id}" is not a symmetry group.`);
+  };
+  const symmetryCommands = () => [
+    {
+      ...base,
+      id: `${prefix}makeSymmetry`,
+      label: "Make Symmetry\u2026",
+      keywords: ["symmetry", "mirror", "kaleidoscope", "radial", "mandala", "reflect", "live symmetry"],
+      description: "Puts objects sharing a parent (`ids`, default the selection) into a live symmetry group: it draws them with their mirrored or rotated copies, which follow every edit of the originals. center defaults to the objects' centre (the artboard's with no objects: an empty group to add art to with parentId). One undo step. Returns { id, symmetry, children }.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Objects to repeat (default: the selection; [] for an empty group)." }, ...SYMMETRY_PROPS, name: { type: "string", description: 'Group name (default "Symmetry").' } }, required: ["mode"], additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { ids: list2, ...input } = params;
+        const r = controller.makeSymmetry(input, list2 ? { ids: list2 } : {});
+        if (!r.ok) fail(r.message);
+        return symmetryResult(r.id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setSymmetry`,
+      label: "Symmetry Options\u2026",
+      keywords: ["symmetry", "mirror", "radial", "axis", "copies"],
+      description: "Changes symmetry groups (`ids`, default the selected one or the one holding the selection): mode, center, rotation, copies, mirror. Pass at least one. One undo step. Returns { groups }.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Symmetry group ids (default: the selection)." }, ...SYMMETRY_PROPS }, additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { ids: list2, ...patch } = params ?? {};
+        if (!Object.keys(patch).length) fail("Pass at least one of mode, center, rotation, copies, mirror.");
+        check(controller.setSymmetry(patch, list2 ? { ids: list2 } : {}));
+        const ids2 = list2 ?? controller.getState().selection.filter((id) => controller.getNode(id)?.type === "group");
+        return { groups: ids2.filter((id) => controller.getNode(id)?.symmetry).map(symmetryResult) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}releaseSymmetry`,
+      label: "Release Symmetry",
+      keywords: ["symmetry", "release", "expand", "bake"],
+      description: "Stops symmetry groups repeating their children. With expand: true the copies become real, editable objects in the group (new ids); otherwise they go. One undo step. Returns { ids } of the objects expanding added.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Symmetry group ids (default: the selection)." }, expand: { type: "boolean", description: "Keep the copies as real objects (default false)." } }, additionalProperties: false },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const r = controller.releaseSymmetry({ ...params?.ids ? { ids: params.ids } : {}, ...params?.expand ? { expand: true } : {} });
+        check(r);
+        return { ids: r.ids ?? [] };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}enterSymmetry`,
+      label: "Draw Inside Symmetry",
+      keywords: ["symmetry", "draw inside", "mirror drawing"],
+      description: "Hands the canvas to the user drawing inside a top-level symmetry group: new pen, pencil, shape and text art goes into it, mirrored as it is drawn, until vector.exitSymmetry or Escape. Returns { id }.",
+      params: { type: "object", properties: { id: { type: "string", description: "The symmetry group." } }, required: ["id"], additionalProperties: false },
+      run: (_ctx, params) => {
+        check(controller.enterSymmetry(params.id));
+        return { id: params.id };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}exitSymmetry`,
+      label: "Stop Drawing Inside Symmetry",
+      keywords: ["symmetry", "exit"],
+      description: "New art goes on top of the document again (no symmetry group is entered). Returns { ok: true }.",
+      params: { type: "object", properties: {}, additionalProperties: false },
+      run: () => {
+        controller.exitSymmetry();
+        return { ok: true };
+      }
+    }
+  ];
   const pdfCommands = () => [
     {
       ...base,
@@ -15363,12 +15721,16 @@ function createVectorCommands(controller, options = {}) {
           points: { type: "integer", minimum: 3 },
           innerRatio: { type: "number", minimum: 0, maximum: 1 },
           name: { type: "string" },
+          parentId: PARENT_ID,
           ...STYLE_PROPS
         },
         required: ["kind", "x", "y", "width", "height"]
       },
       undoable: true,
-      run: (_ctx, params) => ({ id: controller.addShape(params) })
+      run: (_ctx, params) => {
+        const { parentId, ...input } = params;
+        return { id: controller.addShape(input, parentOf(parentId)) };
+      }
     },
     {
       ...base,
@@ -15376,10 +15738,10 @@ function createVectorCommands(controller, options = {}) {
       label: "Add Path\u2026",
       keywords: ["svg", "path data", "bezier", "curve"],
       description: "Adds a path from SVG path data (`d`), in document units.",
-      params: { type: "object", properties: { d: { type: "string" }, name: { type: "string" }, ...STYLE_PROPS }, required: ["d"] },
+      params: { type: "object", properties: { d: { type: "string" }, name: { type: "string" }, parentId: PARENT_ID, ...STYLE_PROPS }, required: ["d"] },
       undoable: true,
       run: (_ctx, params) => {
-        const id = controller.addPath(params.d, { ...pickStyle(params), ...params.name ? { name: params.name } : {} });
+        const id = controller.addPath(params.d, { ...pickStyle(params), ...params.name ? { name: params.name } : {} }, parentOf(params.parentId));
         const node = controller.getNode(id);
         if (node?.type === "path" && !node.subpaths.length) {
           controller.undo();
@@ -15436,6 +15798,7 @@ function createVectorCommands(controller, options = {}) {
     ...traceCommands(),
     ...lottieCommands(),
     ...pdfCommands(),
+    ...symmetryCommands(),
     {
       ...base,
       id: `${prefix}setCorners`,
@@ -16427,6 +16790,8 @@ export {
   VECTOR_STROKE_SETTING_KEYS,
   VECTOR_STYLE_KEYS,
   VECTOR_SYMBOL_MAX_DEPTH,
+  VECTOR_SYMMETRY_MODES,
+  VECTOR_SYMMETRY_MODE_LABELS,
   VECTOR_TEXT_ALIGNS,
   VECTOR_TEXT_ALIGN_LABELS,
   VECTOR_TEXT_ALIGN_OPTIONS,
@@ -16612,6 +16977,7 @@ export {
   isVectorMaskType,
   isVectorMeshGradient,
   isVectorShadedPaint,
+  isVectorSymmetryGroup,
   isVectorTextTarget,
   joinSubpaths,
   knifePath,
@@ -16720,6 +17086,7 @@ export {
   sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
+  sanitizeVectorSymmetry,
   sanitizeVectorTextFields,
   sanitizeVectorTextFrame,
   sanitizeWidthProfile,
@@ -16763,6 +17130,7 @@ export {
   transformVectorNode,
   transformVectorPaint,
   transformVectorShadedPaint,
+  transformVectorSymmetry,
   translateAnchor,
   translateMatrix,
   trimIntervals,
@@ -16927,6 +17295,9 @@ export {
   vectorStrokes,
   vectorSymbolUses,
   vectorSymbolsUsedIn,
+  vectorSymmetryAxes,
+  vectorSymmetryDrawn,
+  vectorSymmetryMatrices,
   vectorTargetPaint,
   vectorTextBoxOutline,
   vectorTextCaret,