@pixerate/editor 0.130.0 → 0.133.0

package/dist/vector/index.js

@@ -12,6 +12,7 @@ import {
   applyHomography,
   homographyFromPoints,
   homographyKeepsQuad,
+  invertHomography,
   orderQuad,
   solve8
 } from "../chunk-GX332W2C.js";
@@ -42,7 +43,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-L5OTIYOO.js";
+} from "../chunk-VGZSIXX3.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -74,12 +75,16 @@ import {
   VECTOR_GRADIENT_TYPES,
   VECTOR_HORIZONTAL_RESIZING,
   VECTOR_HORIZONTAL_RESIZING_LABELS,
+  VECTOR_LENS_LABELS,
+  VECTOR_LENS_SPECS,
+  VECTOR_LENS_TYPES,
   VECTOR_MASK_TYPES,
   VECTOR_MERGE_MODES,
   VECTOR_MESH_MAX,
   VECTOR_PARAGRAPH_STYLE_KEYS,
   VECTOR_PATHFINDER_OPERATIONS,
   VECTOR_PATH_TEXT_BASELINES,
+  VECTOR_PERSPECTIVE_PLANES,
   VECTOR_PRESSURE_NOMINAL,
   VECTOR_SPATIAL_MIN,
   VECTOR_STROKE_GRADIENT_MODES,
@@ -198,6 +203,7 @@ import {
   isVectorFrame,
   isVectorFreeformGradient,
   isVectorGradient,
+  isVectorLens,
   isVectorLiveBoolean,
   isVectorMaskActive,
   isVectorMaskGroup,
@@ -212,6 +218,7 @@ import {
   mapBezierPath,
   mapVectorGradient,
   mapVectorPaint,
+  mapVectorPaintColors,
   mapVectorPoints,
   mapVectorShadedPaint,
   mapVectorSubpaths,
@@ -265,6 +272,7 @@ import {
   replaceVectorText,
   rerouteVectorConnectors,
   resizeWarpMesh,
+  resolveVectorLenses,
   resolveVectorSymbols,
   reverseSubpath,
   reverseVectorGradient,
@@ -284,6 +292,7 @@ import {
   sanitizeVectorFilters,
   sanitizeVectorFrame,
   sanitizeVectorGradient,
+  sanitizeVectorLens,
   sanitizeVectorMask,
   sanitizeVectorResizing,
   sanitizeVectorShadedPaint,
@@ -309,6 +318,7 @@ import {
   splitWarpMeshU,
   splitWarpMeshV,
   starSubpath,
+  stripVectorLensViews,
   stripVectorSymbolArt,
   strokePositionPoint,
   strokeWidthProfileOf,
@@ -387,6 +397,8 @@ import {
   vectorGradientUnitsMatrix,
   vectorInstanceDrawn,
   vectorInstanceGroup,
+  vectorLensColorMap,
+  vectorLensDrawn,
   vectorLiveBooleanSteps,
   vectorMaskContains,
   vectorMaskContentBounds,
@@ -483,7 +495,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-PRYMC442.js";
+} from "../chunk-FOBB6AIO.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -824,6 +836,131 @@ function releaseVectorBlend(group, newId) {
   return [...keys, group.transform ? transformVectorNode(path, m) : path];
 }
 
+// src/vector/perspective.ts
+function vectorPerspectivePlanes(p) {
+  return p.vanishingPoints.length <= 1 ? ["floor", "side", "front"] : ["floor", "left", "right"];
+}
+function sanitizeVectorPerspective(value) {
+  if (!value || typeof value !== "object") return null;
+  const r = value;
+  const isPt = (v) => !!v && typeof v === "object" && Number.isFinite(v.x) && Number.isFinite(v.y);
+  if (!Array.isArray(r.vanishingPoints) || r.vanishingPoints.length < 1 || r.vanishingPoints.length > 3 || !r.vanishingPoints.every(isPt) || !isPt(r.origin)) return null;
+  const origin = { x: r.origin.x, y: r.origin.y };
+  const vps = r.vanishingPoints.map((v) => ({ x: v.x, y: v.y }));
+  if (vps.some((v) => Math.hypot(v.x - origin.x, v.y - origin.y) < 1e-6)) return null;
+  const out = { vanishingPoints: vps, origin };
+  if (typeof r.gridSize === "number" && r.gridSize > 0 && Number.isFinite(r.gridSize)) out.gridSize = Math.min(1e3, r.gridSize);
+  if (typeof r.extent === "number" && Number.isFinite(r.extent)) out.extent = Math.min(100, Math.max(1, Math.round(r.extent)));
+  if (r.visible === false) out.visible = false;
+  return out;
+}
+function towards(o, vp, want) {
+  const d = Math.hypot(vp.x - o.x, vp.y - o.y);
+  let a = 1 / d;
+  if (want === "right" ? vp.x - o.x < 0 : vp.y - o.y > 0) a = -a;
+  return [a * vp.x, a * vp.y, a];
+}
+function vectorPerspectivePlaneMap(p, plane) {
+  if (!vectorPerspectivePlanes(p).includes(plane)) return null;
+  const o = p.origin;
+  const [v1, v2, v3] = p.vanishingPoints;
+  const right = [1, 0, 0];
+  const up = v3 ? towards(o, v3, "up") : [0, -1, 0];
+  let x;
+  let y;
+  if (p.vanishingPoints.length <= 1) {
+    if (plane === "floor") [x, y] = [right, towards(o, v1, "up")];
+    else if (plane === "side") [x, y] = [towards(o, v1, "right"), up];
+    else [x, y] = [right, up];
+  } else if (plane === "floor") [x, y] = [towards(o, v2, "right"), towards(o, v1, "up")];
+  else if (plane === "left") [x, y] = [towards(o, v1, "right"), up];
+  else [x, y] = [towards(o, v2, "right"), up];
+  return [x[0], y[0], o.x, x[1], y[1], o.y, x[2], y[2], 1];
+}
+function vectorPerspectiveFlatToPlane(p, plane) {
+  const h = vectorPerspectivePlaneMap(p, plane);
+  if (!h) return null;
+  const o = p.origin;
+  return (q) => {
+    const u = q.x - o.x;
+    const v = o.y - q.y;
+    const w = h[6] * u + h[7] * v + h[8];
+    if (!(w > 1e-6)) return null;
+    return applyHomography(h, { x: u, y: v });
+  };
+}
+function vectorPerspectivePlaneToFlat(p, plane) {
+  const h = vectorPerspectivePlaneMap(p, plane);
+  const inv = h ? invertHomography(h) : null;
+  if (!inv) return null;
+  const o = p.origin;
+  return (q) => {
+    const f = applyHomography(inv, q);
+    if (!f) return null;
+    const w = h[6] * f.x + h[7] * f.y + h[8];
+    if (!(w > 1e-6)) return null;
+    return { x: o.x + f.x, y: o.y - f.y };
+  };
+}
+function vectorPerspectiveMapPath(p, plane, path) {
+  const f = vectorPerspectiveFlatToPlane(p, plane);
+  if (!f) return null;
+  let behind = false;
+  const out = mapBezierPath(
+    path,
+    (q) => {
+      const r = f(q);
+      if (!r) {
+        behind = true;
+        return q;
+      }
+      return r;
+    },
+    0.1
+  );
+  return behind ? null : out;
+}
+function vectorPerspectiveGridLines(p, plane) {
+  const h = vectorPerspectivePlaneMap(p, plane);
+  if (!h) return [];
+  const g = p.gridSize ?? 20;
+  const n2 = p.extent ?? 12;
+  const max = n2 * g;
+  const lo = (axis) => axis === "y" && plane !== "floor" ? 0 : -max;
+  const w = (u, v) => h[6] * u + h[7] * v + h[8];
+  const at = (u, v) => applyHomography(h, { x: u, y: v });
+  const segment = (u0, v0, u1, v1) => {
+    const wa = w(u0, v0);
+    const wb = w(u1, v1);
+    const min = 0.05;
+    if (wa < min && wb < min) return null;
+    let t0 = 0;
+    let t1 = 1;
+    if (wa < min) t0 = (min - wa) / (wb - wa);
+    if (wb < min) t1 = (min - wa) / (wb - wa);
+    const a = at(u0 + (u1 - u0) * t0, v0 + (v1 - v0) * t0);
+    const b = at(u0 + (u1 - u0) * t1, v0 + (v1 - v0) * t1);
+    return a && b ? { a, b } : null;
+  };
+  const out = [];
+  for (let k = lo("x") / g; k <= n2; k++) {
+    const s = segment(k * g, lo("y"), k * g, max);
+    if (s) out.push(s);
+  }
+  for (let k = lo("y") / g; k <= n2; k++) {
+    const s = segment(lo("x"), k * g, max, k * g);
+    if (s) out.push(s);
+  }
+  return out;
+}
+function vectorPerspectivePreset(points, width, height) {
+  const horizon = height * 0.35;
+  const origin = { x: width / 2, y: height * 0.8 };
+  const vps = points === 1 ? [{ x: width / 2, y: horizon }] : [{ x: -width * 0.3, y: horizon }, { x: width * 1.3, y: horizon }];
+  if (points === 3) vps.push({ x: width / 2, y: height * 3 });
+  return { vanishingPoints: vps, origin, gridSize: Math.max(4, Math.round(Math.min(width, height) / 20)), extent: 12 };
+}
+
 // src/vector/constraints/lm.ts
 var MAX_ROWS = 800;
 var maxAbs = (v) => v.reduce((m, a) => Number.isFinite(a) ? Math.max(m, Math.abs(a)) : Infinity, 0);
@@ -2296,12 +2433,20 @@ function collapsedNode(node, box, prefix) {
   byPrefix.set(prefix, out);
   return out;
 }
+var lensResolved = /* @__PURE__ */ new WeakMap();
+function resolvedLensNodes(doc) {
+  const hit = lensResolved.get(doc.nodes);
+  if (hit) return hit;
+  const nodes = resolveVectorLenses(doc).nodes;
+  lensResolved.set(doc.nodes, nodes);
+  return nodes;
+}
 function getVectorSceneRenderData(state, options = {}) {
   const defs = [];
   const filters = [];
   const prefix = options.idPrefix ?? "ve-";
   const v = state.viewport;
-  const all = state.document.nodes;
+  const all = resolvedLensNodes(state.document);
   const stats = { nodes: all.length, culled: 0, collapsed: 0 };
   let nodes;
   const size = options.viewportSize;
@@ -2396,6 +2541,21 @@ function shadingOverlay(state) {
   }
   return out;
 }
+function perspectiveOverlay(state) {
+  const grid = state.document.perspective;
+  if (!grid || grid.visible === false) return null;
+  const r = (n2) => Math.round(n2 * 10) / 10;
+  const planes = vectorPerspectivePlanes(grid).map((plane) => ({
+    plane,
+    active: state.perspectivePlane === plane,
+    d: vectorPerspectiveGridLines(grid, plane).map(({ a, b }) => {
+      const p = toScreen(state, a);
+      const q = toScreen(state, b);
+      return `M${r(p.x)} ${r(p.y)}L${r(q.x)} ${r(q.y)}`;
+    }).join("")
+  }));
+  return { planes, vanishingPoints: grid.vanishingPoints.map((v) => toScreen(state, v)), origin: toScreen(state, grid.origin) };
+}
 function symmetryOverlay(state) {
   const ids = /* @__PURE__ */ new Set([...state.selection, ...state.symmetryTarget ? [state.symmetryTarget] : []]);
   const out = [];
@@ -2709,6 +2869,7 @@ function getVectorOverlayRenderData(state) {
     connectorSites: connectorSiteOverlay(state),
     shading: shadingOverlay(state),
     symmetry: symmetryOverlay(state),
+    perspective: perspectiveOverlay(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
   };
@@ -3517,6 +3678,7 @@ ${offset}
 var pdfString = (s) => `(${s.replace(/[\\()]/g, (c) => `\\${c}`).replace(/[^\x20-\x7e]/g, "?")})`;
 function vectorDocumentToPdf(doc, options = {}) {
   const notes = /* @__PURE__ */ new Set();
+  doc = resolveVectorLenses(doc);
   const scale = options.scale ?? 1;
   const compress = options.compress !== false;
   const frames = options.pages === "artboards" ? vectorArtboards(doc) : [];
@@ -3730,8 +3892,9 @@ function nodeGroup(node, notes) {
   const m = nodeMatrix(node);
   let items = [];
   const live = (node.effects ?? []).some((e) => e.enabled !== false && (e.type === "wiggle" || e.type === "envelope" || e.type === "contour" || e.type === "blockShadow" || e.type === "extrude" || e.type === "bevel"));
-  if (node.type === "text" || node.type === "instance" || live || isVectorMaskGroup(node) || isVectorFrame(node) || isVectorSymmetryGroup(node)) {
+  if (node.type === "text" || node.type === "instance" || live || isVectorMaskGroup(node) || isVectorFrame(node) || isVectorSymmetryGroup(node) || isVectorLens(node)) {
     if (live) notes.push(`${label(node)}: wiggle, envelope, contour, block shadow, extrude and bevel effects have no Lottie equivalent (exported as drawn).`);
+    if (isVectorLens(node)) notes.push(`${label(node)}: a lens exports as drawn (what it shows now, clipped by its outline).`);
     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;
@@ -3785,6 +3948,7 @@ function vectorDocumentToLottie(doc, options = {}) {
   const fps = options.fps ?? 30;
   const op = Math.max(1, Math.round(options.frames ?? 1));
   const shapes = [];
+  if (!options.nodes) doc = resolveVectorLenses(doc);
   for (const n2 of [...options.nodes ?? doc.nodes].reverse()) {
     const g = nodeGroup(n2, notes);
     if (g) shapes.push(g);
@@ -6966,6 +7130,7 @@ var VectorEditorController = class _VectorEditorController {
       typedEntry: this.typed,
       shadingPoint: this.getShadingSelection(),
       symmetryTarget: this.symmetryTarget && this.doc.nodes.some((n2) => n2.id === this.symmetryTarget) ? this.symmetryTarget : null,
+      perspectivePlane: this.perspectivePlane && this.doc.perspective && vectorPerspectivePlanes(this.doc.perspective).includes(this.perspectivePlane) ? this.perspectivePlane : null,
       canUndo: h.canUndo,
       canRedo: h.canRedo,
       undoLabel: h.undoName,
@@ -6982,7 +7147,7 @@ var VectorEditorController = class _VectorEditorController {
       out = { ...out, symbols: out.symbols.map((s) => s.id === edit.symbolId ? { ...s, nodes: out.nodes } : s) };
     }
     out = resolveVectorSymbols(out);
-    return rerouteVectorConnectors(this.solved(out));
+    return resolveVectorLenses(rerouteVectorConnectors(this.solved(out)));
   }
   /**
    * `doc` with its constraints solved (geometry edited since the last solve moving least) and
@@ -7476,7 +7641,7 @@ var VectorEditorController = class _VectorEditorController {
     return vectorDocumentToSvg(this.storedDocument(), options);
   }
   toJSON() {
-    return cloneVectorDocument(stripVectorSymbolArt(this.storedDocument()));
+    return cloneVectorDocument(stripVectorLensViews(stripVectorSymbolArt(this.storedDocument())));
   }
   /** Adds a node (ids are kept unless taken). Returns its id. */
   addNode(node, options = {}) {
@@ -9493,6 +9658,109 @@ var VectorEditorController = class _VectorEditorController {
     this.notify();
   }
   // -----------------------------------------------------------------------------------------
+  // Perspective drawing
+  perspectivePlane = null;
+  /** The document's perspective grid, or null. */
+  getPerspective() {
+    return this.doc.perspective ?? null;
+  }
+  /**
+   * Sets the document's perspective grid (CorelDRAW's Perspective Drawing): 1 to 3 vanishing
+   * points, the origin where its planes meet, the cell size and extent, and whether it shows;
+   * `null` removes it. One undo step.
+   */
+  setPerspective(grid) {
+    let next = null;
+    if (grid) {
+      next = sanitizeVectorPerspective(grid);
+      if (!next) return { ok: false, message: "A perspective grid needs 1 to 3 vanishing points { x, y } away from an origin { x, y }." };
+    }
+    this.change(next ? "Perspective Grid" : "Remove Perspective Grid", () => {
+      const { perspective: _p, ...rest } = this.doc;
+      this.doc = next ? { ...rest, perspective: next } : rest;
+    });
+    if (!next) this.perspectivePlane = null;
+    return { ok: true, perspective: next };
+  }
+  /**
+   * Draws new rectangles, ellipses, polygons and stars on a plane of the perspective grid (their
+   * drag box is taken on the plane, so they recede with it), or flat again with `null`.
+   */
+  setPerspectivePlane(plane) {
+    if (plane !== null) {
+      const grid = this.doc.perspective;
+      if (!grid) return { ok: false, message: "There is no perspective grid: set one with vector.setPerspective first." };
+      const planes = vectorPerspectivePlanes(grid);
+      if (!planes.includes(plane)) return { ok: false, message: `This grid's planes are ${planes.join(", ")}.` };
+    }
+    this.perspectivePlane = plane;
+    this.notify();
+    return { ok: true };
+  }
+  /**
+   * Lays objects onto a plane of the perspective grid: each is read flat, relative to the grid's
+   * origin (right and up), and projected onto the plane, so art near the origin keeps its size and
+   * art further along recedes. Paths and groups are mapped in document space (their transforms
+   * baked in); text and instances must be converted to outlines first. One undo step. Returns
+   * the ids changed.
+   */
+  attachToPerspective(plane, options = {}) {
+    const grid = this.doc.perspective;
+    if (!grid) return { ok: false, message: "There is no perspective grid: set one with vector.setPerspective first." };
+    const planes = vectorPerspectivePlanes(grid);
+    if (!planes.includes(plane)) return { ok: false, message: `This grid's planes are ${planes.join(", ")}.` };
+    const ids = [...new Set(options.ids ?? this.selectedRoots())];
+    if (!ids.length) return { ok: false, message: "Select objects to put on the plane first." };
+    const next = /* @__PURE__ */ new Map();
+    const project = (n2, m) => {
+      const own = n2.transform ? multiplyMatrices(m, n2.transform) : m;
+      if (n2.type === "text" || n2.type === "instance") return `"${n2.id}" is ${n2.type === "text" ? "text" : "a symbol instance"}: convert it to outlines first (vector.createOutlines${n2.type === "instance" ? " after vector.detachInstance" : ""}).`;
+      if (n2.type === "group") {
+        const children = [];
+        for (const c of n2.children) {
+          const r = project(c, own);
+          if (typeof r === "string") return r;
+          children.push(r);
+        }
+        const { transform: _t2, ...rest2 } = n2;
+        return { ...rest2, children };
+      }
+      const flat = transformBezierPath(subpathsToBezier(n2.subpaths), own);
+      const mapped = vectorPerspectiveMapPath(grid, plane, flat);
+      if (!mapped) return `"${n2.id}" reaches beyond the plane's horizon: move it nearer the origin, or the vanishing points further out.`;
+      const { transform: _t, ...rest } = n2;
+      return { ...rest, subpaths: bezierToSubpaths(mapped) };
+    };
+    for (const id of ids) {
+      const loc = locateVectorNode(this.doc.nodes, id);
+      if (!loc) return { ok: false, message: `There is no node "${id}".` };
+      const node = loc.list[loc.index];
+      if (node.locked) return { ok: false, message: `"${id}" is locked; unlock it first.` };
+      const parentM = this.parentMatrixOf(id);
+      const r = project(node, parentM);
+      if (typeof r === "string") return { ok: false, message: r };
+      const inv = invertMatrix(parentM);
+      next.set(id, isIdentityMatrix(inv) ? r : transformVectorNode(r, inv));
+    }
+    this.change(`Attach to ${plane[0].toUpperCase()}${plane.slice(1)} Plane`, () => {
+      this.setDoc(mapTree(this.doc.nodes, (n2) => next.get(n2.id) ?? n2));
+    });
+    return { ok: true, ids };
+  }
+  /** A shape's subpaths drawn on the active perspective plane from its flat drag box, or null to keep it flat. */
+  perspectiveShape(kind, start, end) {
+    const grid = this.doc.perspective;
+    const plane = this.perspectivePlane;
+    if (!grid || !plane || kind === "line" || !vectorPerspectivePlanes(grid).includes(plane)) return null;
+    const toFlat = vectorPerspectivePlaneToFlat(grid, plane);
+    const a = toFlat?.(start);
+    const b = toFlat?.(end);
+    if (!a || !b) return null;
+    const flat = this.createShapeNode({ kind, ...boundsFromPoints(a, b) });
+    const mapped = vectorPerspectiveMapPath(grid, plane, subpathsToBezier(flat.subpaths));
+    return mapped ? bezierToSubpaths(mapped) : null;
+  }
+  // -----------------------------------------------------------------------------------------
   // PDF
   /**
    * The document as a vector PDF (see `vectorDocumentToPdf`): one page of the artboard, or a page
@@ -10134,6 +10402,51 @@ var VectorEditorController = class _VectorEditorController {
    * (`{ nodeId, side? }`) or unglue it (`null`, the end staying where it is), and `route`,
    * `radius`, `gap` set how they run. Plain open paths given by id become connectors. One undo step.
    */
+  /**
+   * Makes closed paths lenses (CorelDRAW's Lens) or changes their lens: `lens` is merged over the
+   * current settings (a different `type` starts from that type's defaults), and `null` makes
+   * them plain paths again. One undo step. Returns each path's id and resulting lens.
+   */
+  setLens(lens, options = {}) {
+    const ids = options.ids ?? this.selection;
+    if (!ids.length) return { ok: false, message: "Select a closed path to make a lens first." };
+    if (lens && lens.type !== void 0 && !VECTOR_LENS_TYPES.includes(lens.type)) return { ok: false, message: `Unknown lens "${lens.type}": use ${VECTOR_LENS_TYPES.join(", ")}.` };
+    if (lens?.color !== void 0 && lens.color !== null && !parseVectorColor(lens.color)) return { ok: false, message: `"${lens.color}" is not a colour: use a CSS colour such as #ff0000.` };
+    const next = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const n2 = this.getNode(id);
+      if (!n2) return { ok: false, message: `There is no node "${id}".` };
+      if (n2.locked) return { ok: false, message: `"${id}" is locked; unlock it first.` };
+      if (lens === null) {
+        if (n2.type === "path" && n2.lens) next.set(id, null);
+        continue;
+      }
+      if (n2.type !== "path" || !n2.subpaths.some((sp) => sp.closed) || isVectorConnector(n2)) return { ok: false, message: `"${id}" is not a closed path: only closed paths can be lenses.` };
+      const type = lens.type ?? n2.lens?.type;
+      if (!type) return { ok: false, message: `"${id}" is not a lens yet: pass a type (${VECTOR_LENS_TYPES.join(", ")}).` };
+      const spec = VECTOR_LENS_SPECS[type];
+      if (lens.amount !== void 0 && !(Number.isFinite(lens.amount) && lens.amount >= spec.min && lens.amount <= spec.max)) return { ok: false, message: `amount for a ${type} lens must be from ${spec.min} to ${spec.max} (${spec.unit}).` };
+      const base = n2.lens && n2.lens.type === type ? n2.lens : { type };
+      next.set(id, sanitizeVectorLens({ ...base, ...lens, type }));
+    }
+    if (!next.size) return { ok: true, lenses: [] };
+    this.change(
+      lens === null ? "Remove Lens" : "Lens",
+      () => {
+        this.setDoc(
+          mapTree(this.doc.nodes, (n2) => {
+            if (!next.has(n2.id) || n2.type !== "path") return n2;
+            const l = next.get(n2.id);
+            if (l) return { ...n2, lens: l };
+            const { lens: _l, lensView: _v, ...rest } = n2;
+            return rest;
+          })
+        );
+      },
+      options.merge
+    );
+    return { ok: true, lenses: [...next].map(([id, l]) => ({ id, lens: l })) };
+  }
   setConnector(patch, options = {}) {
     const ids = options.ids ?? this.selection;
     if (!ids.length) return { ok: false, message: "Select a connector first." };
@@ -12239,7 +12552,9 @@ var VectorEditorController = class _VectorEditorController {
           const y2 = drag.start.y + h;
           bounds = boundsFromPoints(start, { x: x2, y: y2 });
         }
-        const shaped = this.createShapeNode({ kind: drag.tool === "frame" ? "rect" : drag.tool, ...bounds });
+        const kind = drag.tool === "frame" ? "rect" : drag.tool;
+        const onPlane = drag.tool !== "frame" ? this.perspectiveShape(kind, start, { x: bounds.x === start.x ? bounds.x + bounds.width : bounds.x, y: bounds.y === start.y ? bounds.y + bounds.height : bounds.y }) : null;
+        const shaped = onPlane ? { subpaths: onPlane } : this.createShapeNode({ kind, ...bounds });
         this.replaceNode(drag.nodeId, { ...node, subpaths: shaped.subpaths });
         this.interaction = { type: "draw", tool: drag.tool, nodeId: drag.nodeId, bounds };
         this.notify(true);
@@ -14091,7 +14406,8 @@ function createVectorCommands(controller, options = {}) {
           ...isVectorFrame(n2) ? { frameRect: n2.frame } : {},
           ...n2.resizing ? { resizing: n2.resizing } : {},
           ...n2.type === "path" && n2.connector ? { connector: n2.connector } : {},
-          ...n2.type === "group" && n2.symmetry ? { symmetry: n2.symmetry } : {}
+          ...n2.type === "group" && n2.symmetry ? { symmetry: n2.symmetry } : {},
+          ...n2.type === "path" && n2.lens ? { lens: n2.lens } : {}
         });
         if (n2.type === "group") visit(n2.children, depth + 1);
       }
@@ -15055,6 +15371,130 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
+  const LENS_AMOUNTS = VECTOR_LENS_TYPES.map((t) => `${t} ${VECTOR_LENS_SPECS[t].min}\u2026${VECTOR_LENS_SPECS[t].max} ${VECTOR_LENS_SPECS[t].unit} (default ${VECTOR_LENS_SPECS[t].amount})`).join("; ");
+  const lensCommands = () => [
+    {
+      ...base,
+      id: `${prefix}setLens`,
+      label: "Lens\u2026",
+      keywords: ["lens", "magnify", "fisheye", "fish eye", "invert", "brighten", "grayscale", "heat map", "wireframe", "transparency", "tint", "loupe"],
+      description: "Makes closed paths (`ids`, default the selection) lenses, or changes their lens: inside its outline, what is drawn below shows changed (magnify, fisheye, brighten, invert, tintedGrayscale, colorAdd, colorLimit, heatMap, wireframe, or the lens's own fill see-through for transparency). The lens follows every edit below it; its bounds stay its own shape. Pass type to make or switch a lens (missing values take that type's defaults); omit it to change amount or color of existing lenses. One undo step. Returns { lenses: [{ id, lens }] }.",
+      params: {
+        type: "object",
+        properties: {
+          ids: { ...IDS, description: "Closed paths to make or change (default: the selection)." },
+          type: { type: "string", enum: [...VECTOR_LENS_TYPES], description: "What the lens does. Required for a path that is not a lens yet." },
+          amount: { type: "number", description: `Strength, by type: ${LENS_AMOUNTS}.` },
+          color: { type: ["string", "null"], description: "CSS colour for tintedGrayscale, colorAdd, colorLimit and wireframe (default per type; ignored by the others)." }
+        },
+        additionalProperties: false
+      },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const { ids: list2, ...patch } = params ?? {};
+        if (!Object.keys(patch).length) fail("Pass at least one of type, amount, color.");
+        const r = controller.setLens(patch, list2 ? { ids: list2 } : {});
+        check(r);
+        return { lenses: r.lenses ?? [] };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeLens`,
+      label: "Remove Lens",
+      keywords: ["lens", "remove", "plain"],
+      description: "Makes lenses (`ids`, default the selection) plain paths again; ids that are not lenses are skipped. One undo step. Returns { ids } of the paths that stopped being lenses.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Lens ids (default: the selection)." } }, additionalProperties: false },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const r = controller.setLens(null, params?.ids ? { ids: params.ids } : {});
+        check(r);
+        return { ids: (r.lenses ?? []).map((l) => l.id) };
+      }
+    }
+  ];
+  const PLANE = { type: "string", enum: [...VECTOR_PERSPECTIVE_PLANES], description: "A plane of the grid: floor, left and right (2 or 3 vanishing points), or floor, side and front (1 point)." };
+  const perspectiveResult = () => {
+    const grid = controller.getPerspective();
+    return { perspective: grid, planes: grid ? vectorPerspectivePlanes(grid) : [], drawingOn: controller.getState().perspectivePlane };
+  };
+  const perspectiveCommands = () => [
+    {
+      ...base,
+      id: `${prefix}getPerspective`,
+      label: "Perspective Grid",
+      keywords: ["perspective", "grid", "vanishing point", "horizon"],
+      description: "Reads the document's perspective grid: { perspective: { vanishingPoints, origin, gridSize, extent, visible } or null, planes (the planes it has), drawingOn (the plane new shapes are drawn on, or null) }.",
+      params: { type: "object", properties: {}, additionalProperties: false },
+      run: () => perspectiveResult()
+    },
+    {
+      ...base,
+      id: `${prefix}setPerspective`,
+      label: "Perspective Grid\u2026",
+      keywords: ["perspective", "grid", "vanishing point", "one point", "two point", "three point", "horizon", "drawing in perspective"],
+      description: "Sets the document's perspective grid (CorelDRAW's Perspective Drawing): 1 vanishing point (planes floor, side, front), 2 (floor, left, right; walls recede to the first and second) or 3 (the third is where the walls' verticals meet). Put the vanishing points on the horizon line and the origin below it, where the planes meet. One undo step. Returns the grid as vector.getPerspective does.",
+      params: {
+        type: "object",
+        properties: {
+          vanishingPoints: { type: "array", minItems: 1, maxItems: 3, items: { ...POINT, description: "A vanishing point (document units)." }, description: "1 to 3 vanishing points, document units." },
+          origin: { ...POINT, description: "Where the planes meet (document units), not on a vanishing point." },
+          gridSize: { type: "number", exclusiveMinimum: 0, description: "Grid cell size at the origin, document units (default 20)." },
+          extent: { type: "integer", minimum: 1, maximum: 100, description: "Cells drawn out from the origin along each axis (default 12)." },
+          visible: { type: "boolean", description: "Show the grid on the canvas (default true)." }
+        },
+        required: ["vanishingPoints", "origin"],
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        check(controller.setPerspective(params));
+        return perspectiveResult();
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removePerspective`,
+      label: "Remove Perspective Grid",
+      keywords: ["perspective", "grid", "remove"],
+      description: "Removes the perspective grid (art already on its planes stays as drawn). One undo step. Returns { perspective: null }.",
+      params: { type: "object", properties: {}, additionalProperties: false },
+      undoable: true,
+      run: () => {
+        check(controller.setPerspective(null));
+        return { perspective: null };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setPerspectivePlane`,
+      label: "Draw on Perspective Plane",
+      keywords: ["perspective", "plane", "draw", "floor", "wall"],
+      description: "Makes the Rectangle, Ellipse, Polygon and Star tools draw on a plane of the grid (their drag box is taken on the plane, so shapes recede with it), or flat again with plane null. Not an undo step. Returns the grid as vector.getPerspective does.",
+      params: { type: "object", properties: { plane: { ...PLANE, type: ["string", "null"], enum: [...VECTOR_PERSPECTIVE_PLANES, null], description: `${PLANE.description} null draws flat.` } }, required: ["plane"], additionalProperties: false },
+      run: (_ctx, params) => {
+        check(controller.setPerspectivePlane(params.plane));
+        return perspectiveResult();
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}attachToPerspective`,
+      label: "Attach to Perspective",
+      keywords: ["perspective", "attach", "plane", "project", "wall", "floor", "sign"],
+      description: "Lays objects (`ids`, default the selection) onto a plane of the grid: each is read flat relative to the grid origin (right and up) and projected, so art near the origin keeps its size and further art recedes. Draw or place the flat art beside the origin first. Text and instances must be outlines (vector.createOutlines). One undo step. Returns { ids }.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Objects to project (default: the selection)." }, plane: PLANE }, required: ["plane"], additionalProperties: false },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const r = controller.attachToPerspective(params.plane, params.ids ? { ids: params.ids } : {});
+        check(r);
+        return { ids: r.ids ?? [] };
+      }
+    }
+  ];
   const pdfCommands = () => [
     {
       ...base,
@@ -15891,6 +16331,8 @@ function createVectorCommands(controller, options = {}) {
     ...lottieCommands(),
     ...pdfCommands(),
     ...symmetryCommands(),
+    ...perspectiveCommands(),
+    ...lensCommands(),
     {
       ...base,
       id: `${prefix}setCorners`,
@@ -16922,6 +17364,9 @@ export {
   VECTOR_HORIZONTAL_RESIZING,
   VECTOR_HORIZONTAL_RESIZING_LABELS,
   VECTOR_INK_MAX_CORNERS,
+  VECTOR_LENS_LABELS,
+  VECTOR_LENS_SPECS,
+  VECTOR_LENS_TYPES,
   VECTOR_MASK_TYPES,
   VECTOR_MASK_TYPE_LABELS,
   VECTOR_MASK_TYPE_OPTIONS,
@@ -16937,6 +17382,7 @@ export {
   VECTOR_PATH_ACTIONS,
   VECTOR_PATH_TEXT_BASELINES,
   VECTOR_PENCIL_STRING_PX,
+  VECTOR_PERSPECTIVE_PLANES,
   VECTOR_PRESSURE_NOMINAL,
   VECTOR_ROTATE_HANDLE_OFFSET,
   VECTOR_SPATIAL_MIN,
@@ -17128,6 +17574,7 @@ export {
   isVectorFrame,
   isVectorFreeformGradient,
   isVectorGradient,
+  isVectorLens,
   isVectorLiveBoolean,
   isVectorMaskActive,
   isVectorMaskGroup,
@@ -17147,6 +17594,7 @@ export {
   mapVectorGradient,
   mapWarpMeshPoints as mapVectorMeshPoints,
   mapVectorPaint,
+  mapVectorPaintColors,
   mapVectorPoints,
   mapVectorShadedPaint,
   mapVectorSubpaths,
@@ -17217,6 +17665,7 @@ export {
   resampleGradientStops,
   resizeWarpMesh as resizeVectorMesh,
   resolveVectorBlendOptions,
+  resolveVectorLenses,
   resolveVectorSymbols,
   reverseMorphContour,
   reverseSubpath,
@@ -17238,7 +17687,9 @@ export {
   sanitizeVectorFilters,
   sanitizeVectorFrame,
   sanitizeVectorGradient,
+  sanitizeVectorLens,
   sanitizeVectorMask,
+  sanitizeVectorPerspective,
   sanitizeVectorResizing,
   sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
@@ -17267,6 +17718,7 @@ export {
   splitWarpMeshU as splitVectorMeshU,
   splitWarpMeshV as splitVectorMeshV,
   starSubpath,
+  stripVectorLensViews,
   stripVectorSymbolArt,
   strokePositionPoint,
   strokeWidthProfileOf,
@@ -17383,6 +17835,8 @@ export {
   vectorInkShapeName,
   vectorInstanceDrawn,
   vectorInstanceGroup,
+  vectorLensColorMap,
+  vectorLensDrawn,
   vectorLiveBooleanSteps,
   vectorMaskContains,
   vectorMaskContentBounds,
@@ -17432,6 +17886,13 @@ export {
   vectorPathTextPositions,
   vectorPathWorldBezier,
   vectorPathfinderShape,
+  vectorPerspectiveFlatToPlane,
+  vectorPerspectiveGridLines,
+  vectorPerspectiveMapPath,
+  vectorPerspectivePlaneMap,
+  vectorPerspectivePlaneToFlat,
+  vectorPerspectivePlanes,
+  vectorPerspectivePreset,
   vectorPolarAngles,
   vectorPolarIncrementOf,
   vectorRepeaterCopies,