@pixerate/editor 0.132.0 → 0.134.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-ECVI5QRE.js";
+} from "../chunk-7RJ6P7MI.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -83,6 +84,7 @@ import {
   VECTOR_PARAGRAPH_STYLE_KEYS,
   VECTOR_PATHFINDER_OPERATIONS,
   VECTOR_PATH_TEXT_BASELINES,
+  VECTOR_PERSPECTIVE_PLANES,
   VECTOR_PRESSURE_NOMINAL,
   VECTOR_SPATIAL_MIN,
   VECTOR_STROKE_GRADIENT_MODES,
@@ -206,6 +208,7 @@ import {
   isVectorMaskActive,
   isVectorMaskGroup,
   isVectorMaskType,
+  isVectorMasterPage,
   isVectorMeshGradient,
   isVectorShadedPaint,
   isVectorSymmetryGroup,
@@ -271,6 +274,7 @@ import {
   rerouteVectorConnectors,
   resizeWarpMesh,
   resolveVectorLenses,
+  resolveVectorMasterPages,
   resolveVectorSymbols,
   reverseSubpath,
   reverseVectorGradient,
@@ -317,6 +321,7 @@ import {
   splitWarpMeshV,
   starSubpath,
   stripVectorLensViews,
+  stripVectorMasterArt,
   stripVectorSymbolArt,
   strokePositionPoint,
   strokeWidthProfileOf,
@@ -411,6 +416,8 @@ import {
   vectorMaskedGeometry,
   vectorMaskedLocalBounds,
   vectorMaskedShapes,
+  vectorMasterArt,
+  vectorMasterPages,
   vectorMeshColorAt,
   vectorMeshFromOutline,
   vectorMeshLines,
@@ -425,6 +432,7 @@ import {
   vectorNodeToBezier,
   vectorNodesNear,
   vectorOperandOperation,
+  vectorPages,
   vectorPaintLayerNodes,
   vectorPaintSolid,
   vectorPaintToSvg,
@@ -493,7 +501,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-IEYXYMRQ.js";
+} from "../chunk-HHTCDFZC.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -834,6 +842,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);
@@ -2310,7 +2443,7 @@ var lensResolved = /* @__PURE__ */ new WeakMap();
 function resolvedLensNodes(doc) {
   const hit = lensResolved.get(doc.nodes);
   if (hit) return hit;
-  const nodes = resolveVectorLenses(doc).nodes;
+  const nodes = resolveVectorLenses(resolveVectorMasterPages(doc)).nodes;
   lensResolved.set(doc.nodes, nodes);
   return nodes;
 }
@@ -2414,6 +2547,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 = [];
@@ -2727,6 +2875,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
   };
@@ -3535,10 +3684,10 @@ ${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);
+  doc = resolveVectorLenses(resolveVectorMasterPages(doc));
   const scale = options.scale ?? 1;
   const compress = options.compress !== false;
-  const frames = options.pages === "artboards" ? vectorArtboards(doc) : [];
+  const frames = options.pages === "artboards" ? vectorPages(doc) : [];
   if (options.pages === "artboards" && !frames.length) notes.add("There are no artboards (top-level frames): the whole drawing is one page.");
   const docs = frames.length ? frames.map((f) => vectorFrameDocument(doc, f.id, findVectorNode)) : [doc];
   const w = new PdfWriter();
@@ -3805,7 +3954,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);
+  if (!options.nodes) doc = resolveVectorLenses(resolveVectorMasterPages(doc));
   for (const n2 of [...options.nodes ?? doc.nodes].reverse()) {
     const g = nodeGroup(n2, notes);
     if (g) shapes.push(g);
@@ -6987,6 +7136,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,
@@ -7003,7 +7153,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 resolveVectorLenses(rerouteVectorConnectors(this.solved(out)));
+    return resolveVectorLenses(resolveVectorMasterPages(rerouteVectorConnectors(this.solved(out))));
   }
   /**
    * `doc` with its constraints solved (geometry edited since the last solve moving least) and
@@ -7497,7 +7647,7 @@ var VectorEditorController = class _VectorEditorController {
     return vectorDocumentToSvg(this.storedDocument(), options);
   }
   toJSON() {
-    return cloneVectorDocument(stripVectorLensViews(stripVectorSymbolArt(this.storedDocument())));
+    return cloneVectorDocument(stripVectorMasterArt(stripVectorLensViews(stripVectorSymbolArt(this.storedDocument()))));
   }
   /** Adds a node (ids are kept unless taken). Returns its id. */
   addNode(node, options = {}) {
@@ -9514,6 +9664,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
@@ -10312,6 +10565,146 @@ var VectorEditorController = class _VectorEditorController {
     });
     return { ok: true, id };
   }
+  // -----------------------------------------------------------------------------------------
+  // Pages and master pages
+  /**
+   * The document's pages (top-level frames that are not master pages, in order: `number` from 1)
+   * with the master each uses, and its master pages.
+   */
+  getPages() {
+    const pages = vectorPages(this.doc);
+    const masters = vectorMasterPages(this.doc);
+    const box = (f) => ({ x: f.frame.x, y: f.frame.y, width: f.frame.width, height: f.frame.height });
+    return {
+      pages: pages.map((p, i) => ({ id: p.id, name: p.name ?? `Page ${i + 1}`, number: i + 1, masterId: p.frame.masterId && masters.some((m) => m.id === p.frame.masterId) ? p.frame.masterId : null, bounds: box(p) })),
+      masters: masters.map((m) => ({ id: m.id, name: m.name ?? "Master", usedBy: pages.filter((p) => p.frame.masterId === m.id).map((p) => p.id), bounds: box(m) }))
+    };
+  }
+  /** Where a new page or master goes: right of every top-level frame, or below them for a master. */
+  nextPageRect(master) {
+    const frames = this.doc.nodes.filter(isVectorFrame);
+    const pages = vectorPages(this.doc);
+    const like = pages[pages.length - 1]?.frame ?? frames[frames.length - 1]?.frame;
+    const width = like?.width ?? this.doc.width;
+    const height = like?.height ?? this.doc.height;
+    if (!frames.length) return { x: 0, y: 0, width, height };
+    const gap = Math.max(20, Math.round(width * 0.1));
+    if (master) {
+      const bottom = Math.max(...frames.map((f) => f.frame.y + f.frame.height));
+      const left = Math.min(...frames.map((f) => f.frame.x));
+      return { x: left, y: bottom + gap * 2, width, height };
+    }
+    const right = Math.max(...pages.map((f) => f.frame.x + f.frame.width), ...pages.length ? [] : frames.map((f) => f.frame.x + f.frame.width));
+    const top = pages.length ? Math.min(...pages.map((f) => f.frame.y)) : Math.min(...frames.map((f) => f.frame.y));
+    return { x: right + gap, y: top, width, height };
+  }
+  /**
+   * Adds a page: a frame the size of the last page (or the document), to the right of the others,
+   * after page `after` in the page order (default last), using master page `masterId` (default:
+   * the master the last page uses). The first page added to a document without frames covers the
+   * artboard and takes the existing top-level art in. One undo step; selects it. Returns its id.
+   */
+  addPage(input = {}) {
+    const pages = vectorPages(this.doc);
+    if (input.masterId && !isVectorMasterPage(this.doc.nodes.find((n2) => n2.id === input.masterId))) return { ok: false, message: `"${input.masterId}" is not a master page (add one with vector.addMasterPage).` };
+    if (input.after !== void 0 && !pages.some((p) => p.id === input.after)) return { ok: false, message: `"${input.after}" is not a page.` };
+    const first = !this.doc.nodes.some(isVectorFrame);
+    const rect = this.nextPageRect(false);
+    const id = this.newId();
+    const masterId = input.masterId === void 0 ? pages[pages.length - 1]?.frame.masterId ?? null : input.masterId;
+    const adopted = first ? this.doc.nodes.filter((n2) => !n2.locked && n2.visible !== false && !n2.blendStep) : [];
+    const page = {
+      id,
+      type: "group",
+      name: input.name ?? `Page ${pages.length + 1}`,
+      frame: { ...rect, fill: "#ffffff", ...masterId ? { masterId } : {} },
+      children: adopted
+    };
+    const taken = new Set(adopted.map((n2) => n2.id));
+    this.change("Add Page", () => {
+      const rest = this.doc.nodes.filter((n2) => !taken.has(n2.id));
+      const at = input.after ? rest.findIndex((n2) => n2.id === input.after) + 1 : rest.length;
+      this.setDoc([...rest.slice(0, at), page, ...rest.slice(at)]);
+      this.selection = [id];
+      this.anchors = [];
+      this.editingId = null;
+    });
+    return { ok: true, id };
+  }
+  /**
+   * Adds an empty master page (a frame with `master` set, the size of the last page) below the
+   * pages. Art drawn in it shows on every page that uses it; text can show `{page}` and `{pages}`.
+   * With `assignTo` (page ids, or `all`), those pages use it. One undo step; selects it.
+   */
+  addMasterPage(input = {}) {
+    const pages = vectorPages(this.doc);
+    const assign = input.assignTo === "all" ? pages.map((p) => p.id) : input.assignTo ?? [];
+    for (const pid of assign) if (!pages.some((p) => p.id === pid)) return { ok: false, message: `"${pid}" is not a page.` };
+    const rect = this.nextPageRect(true);
+    const id = this.newId();
+    const master = { id, type: "group", name: input.name ?? `Master ${String.fromCharCode(65 + vectorMasterPages(this.doc).length % 26)}`, frame: { ...rect, master: true }, children: [] };
+    const set = new Set(assign);
+    this.change("Add Master Page", () => {
+      this.setDoc([...this.doc.nodes.map((n2) => set.has(n2.id) && isVectorFrame(n2) ? { ...n2, frame: { ...n2.frame, masterId: id } } : n2), master]);
+      this.selection = [id];
+      this.anchors = [];
+      this.editingId = null;
+    });
+    return { ok: true, id };
+  }
+  /** Makes pages use master page `masterId`, or none with null. One undo step. */
+  setPageMaster(masterId, options = {}) {
+    const pages = vectorPages(this.doc);
+    const ids = options.ids ?? this.selection.filter((id) => pages.some((p) => p.id === id));
+    if (!ids.length) return { ok: false, message: "Select a page (a top-level frame) first." };
+    for (const id of ids) if (!pages.some((p) => p.id === id)) return { ok: false, message: `"${id}" is not a page${isVectorMasterPage(this.getNode(id)) ? " (it is a master page)" : ""}.` };
+    if (masterId !== null && !isVectorMasterPage(this.doc.nodes.find((n2) => n2.id === masterId))) return { ok: false, message: `"${masterId}" is not a master page.` };
+    const set = new Set(ids);
+    this.change(masterId ? "Apply Master Page" : "Remove Master Page", () => {
+      this.setDoc(
+        this.doc.nodes.map((n2) => {
+          if (!set.has(n2.id) || !isVectorFrame(n2)) return n2;
+          const { masterId: _m, ...frame } = n2.frame;
+          return { ...n2, frame: masterId ? { ...frame, masterId } : frame };
+        })
+      );
+    });
+    return { ok: true, ids: [...ids] };
+  }
+  /** Moves page `id` to position `index` (0-based) in the page order. One undo step. Returns the new order. */
+  movePage(id, index) {
+    const pages = vectorPages(this.doc);
+    const from = pages.findIndex((p) => p.id === id);
+    if (from < 0) return { ok: false, message: `"${id}" is not a page.` };
+    if (!Number.isInteger(index) || index < 0 || index >= pages.length) return { ok: false, message: `index must be from 0 to ${pages.length - 1}.` };
+    if (index === from) return { ok: true, order: pages.map((p) => p.id) };
+    const order = pages.map((p) => p.id);
+    order.splice(index, 0, ...order.splice(from, 1));
+    const slots = this.doc.nodes.map((n2, i) => pages.some((p) => p.id === n2.id) ? i : -1).filter((i) => i >= 0);
+    const byId = new Map(pages.map((p) => [p.id, p]));
+    this.change("Move Page", () => {
+      const nodes = this.doc.nodes.slice();
+      slots.forEach((slot, k) => nodes[slot] = byId.get(order[k]));
+      this.setDoc(nodes);
+    });
+    return { ok: true, order };
+  }
+  /**
+   * Goes to a page (or master page): selects it and brings it into view, fitted to a canvas of
+   * `size` screen pixels when given, otherwise at the current zoom with its corner near the
+   * canvas's top-left. Not an undo step.
+   */
+  goToPage(id, options = {}) {
+    const n2 = this.doc.nodes.find((x) => x.id === id);
+    if (!isVectorFrame(n2)) return { ok: false, message: `"${id}" is not a page or master page.` };
+    const b = vectorNodeBounds(n2) ?? { x: n2.frame.x, y: n2.frame.y, width: n2.frame.width, height: n2.frame.height };
+    this.selection = [id];
+    this.anchors = [];
+    if (options.size) this.zoomToFit(options.size, { bounds: b });
+    else this.setViewport({ x: 40 - b.x * this.viewport.zoom, y: 40 - b.y * this.viewport.zoom });
+    this.notify();
+    return { ok: true };
+  }
   /**
    * Frame Selection: puts the selected (or given) objects, which must share a parent, into a new
    * frame fitted to their bounds plus `padding` (document units, default 0), in their place in the
@@ -12305,7 +12698,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);
@@ -14634,7 +15029,8 @@ function createVectorCommands(controller, options = {}) {
           name: { type: "string", description: "Layer name (default the text's start)." },
           fill: PAINT,
           stroke: PAINT,
-          strokeWidth: { type: "number", minimum: 0, description: "Stroke width (default 1)." }
+          strokeWidth: { type: "number", minimum: 0, description: "Stroke width (default 1)." },
+          parentId: { type: "string", description: "A group (frame, master page, symmetry group) to add it into, on top of its children (default: the top of the document). On a master page, {page} and {pages} show each page's number and the page count." }
         },
         required: ["text"],
         additionalProperties: false
@@ -14654,7 +15050,7 @@ function createVectorCommands(controller, options = {}) {
             ...params.paragraph ? { paragraph: params.paragraph } : {},
             ...params.fill !== void 0 ? { fill: checkPaint(params.fill, "fill") } : {},
             ...params.stroke !== void 0 ? { stroke: checkPaint(params.stroke, "stroke") } : {}
-          });
+          }, parentOf(params.parentId));
         } catch (e) {
           fail(e instanceof Error ? e.message : String(e));
         }
@@ -15166,6 +15562,86 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
+  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,
@@ -15646,6 +16122,109 @@ function createVectorCommands(controller, options = {}) {
   ];
   const frameResult = (id) => controller.getFrames().find((f) => f.id === id) ?? fail(`"${id}" is not a frame.`);
   const FRAME_PAINT = { ...PAINT, description: `The frame's background, drawn below its children. ${PAINT.description}` };
+  const pagesResult = () => controller.getPages();
+  const pageCommands = () => [
+    {
+      ...base,
+      id: `${prefix}listPages`,
+      label: "Pages",
+      keywords: ["pages", "master page", "multipage", "page numbers", "document pages"],
+      description: "Lists the document's pages (top-level frames that are not master pages, in order) and its master pages: { pages: [{ id, name, number, masterId, bounds }], masters: [{ id, name, usedBy, bounds }] }. Place master art inside the master bounds.",
+      params: { type: "object", properties: {}, additionalProperties: false },
+      run: () => pagesResult()
+    },
+    {
+      ...base,
+      id: `${prefix}addPage`,
+      label: "Add Page",
+      keywords: ["page", "add page", "new page", "insert page", "multipage"],
+      description: "Adds a page: a frame the size of the last page (or the document) right of the others, after page `after` (default last), using master `masterId` (default: the last page's master; null for none). The first page of a document without frames covers the artboard and takes its art in. Add art to it with parentId. One undo step. Returns { id } and the pages.",
+      params: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: 'Page name (default "Page n").' },
+          masterId: { type: ["string", "null"], description: "Master page id, or null for none (default: the last page's master)." },
+          after: { type: "string", description: "Page id to insert after (default: at the end)." }
+        },
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const r = controller.addPage(params ?? {});
+        check(r);
+        return { id: r.id, ...pagesResult() };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}addMasterPage`,
+      label: "Add Master Page",
+      keywords: ["master page", "template page", "header", "footer", "page numbers"],
+      description: 'Adds an empty master page (a frame below the pages, not a page itself). Art added to it (parentId: its id) shows on every page using it, laid out by each object\'s resizing constraints; text there can show {page} and {pages}. `assignTo` page ids or "all" make pages use it. One undo step. Returns { id } and the pages.',
+      params: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: 'Master name (default "Master A", "Master B", \u2026).' },
+          assignTo: { anyOf: [{ type: "string", enum: ["all"] }, { ...IDS }], description: 'Pages that use it: "all" or page ids (default none).' }
+        },
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const r = controller.addMasterPage(params ?? {});
+        check(r);
+        return { id: r.id, ...pagesResult() };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setPageMaster`,
+      label: "Apply Master Page",
+      keywords: ["master page", "apply master", "page template"],
+      description: "Makes pages (`ids`, default the selected pages) use master page `masterId`, or none with null. One undo step. Returns the pages.",
+      params: { type: "object", properties: { ids: { ...IDS, description: "Page ids (default: the selected pages)." }, masterId: { type: ["string", "null"], description: "Master page id, or null for none." } }, required: ["masterId"], additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        check(controller.setPageMaster(params.masterId, params.ids ? { ids: params.ids } : {}));
+        return pagesResult();
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}movePage`,
+      label: "Move Page",
+      keywords: ["page order", "reorder pages", "move page"],
+      description: "Moves page `id` to position `index` (0-based) in the page order; page numbers follow. One undo step. Returns the pages.",
+      params: { type: "object", properties: { id: { type: "string", description: "The page." }, index: { type: "integer", minimum: 0, description: "New position, 0 for first." } }, required: ["id", "index"], additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        check(controller.movePage(params.id, params.index));
+        return pagesResult();
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}goToPage`,
+      label: "Go to Page",
+      keywords: ["go to page", "navigate", "show page", "zoom to page"],
+      description: "Selects a page or master page and brings it into view for the user (fitted when the canvas size is given). Not an undo step. Returns { id }.",
+      params: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Page or master page id." },
+          canvasWidth: { type: "number", exclusiveMinimum: 0, description: "Canvas width in screen pixels, to fit the page (optional)." },
+          canvasHeight: { type: "number", exclusiveMinimum: 0, description: "Canvas height in screen pixels, to fit the page (optional)." }
+        },
+        required: ["id"],
+        additionalProperties: false
+      },
+      run: (_ctx, params) => {
+        const size = params.canvasWidth && params.canvasHeight ? { width: params.canvasWidth, height: params.canvasHeight } : void 0;
+        check(controller.goToPage(params.id, size ? { size } : {}));
+        return { id: params.id };
+      }
+    }
+  ];
   const frameCommands = () => [
     {
       ...base,
@@ -15995,6 +16574,7 @@ function createVectorCommands(controller, options = {}) {
     ...symbolCommands(),
     ...constraintCommands(),
     ...frameCommands(),
+    ...pageCommands(),
     ...connectorCommands(),
     ...trackingCommands(),
     ...shadingCommands(),
@@ -16002,6 +16582,7 @@ function createVectorCommands(controller, options = {}) {
     ...lottieCommands(),
     ...pdfCommands(),
     ...symmetryCommands(),
+    ...perspectiveCommands(),
     ...lensCommands(),
     {
       ...base,
@@ -17052,6 +17633,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,
@@ -17248,6 +17830,7 @@ export {
   isVectorMaskActive,
   isVectorMaskGroup,
   isVectorMaskType,
+  isVectorMasterPage,
   isVectorMeshGradient,
   isVectorShadedPaint,
   isVectorSymmetryGroup,
@@ -17335,6 +17918,7 @@ export {
   resizeWarpMesh as resizeVectorMesh,
   resolveVectorBlendOptions,
   resolveVectorLenses,
+  resolveVectorMasterPages,
   resolveVectorSymbols,
   reverseMorphContour,
   reverseSubpath,
@@ -17358,6 +17942,7 @@ export {
   sanitizeVectorGradient,
   sanitizeVectorLens,
   sanitizeVectorMask,
+  sanitizeVectorPerspective,
   sanitizeVectorResizing,
   sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
@@ -17387,6 +17972,7 @@ export {
   splitWarpMeshV as splitVectorMeshV,
   starSubpath,
   stripVectorLensViews,
+  stripVectorMasterArt,
   stripVectorSymbolArt,
   strokePositionPoint,
   strokeWidthProfileOf,
@@ -17519,6 +18105,8 @@ export {
   vectorMaskedGeometry,
   vectorMaskedLocalBounds,
   vectorMaskedShapes,
+  vectorMasterArt,
+  vectorMasterPages,
   vectorMeshColorAt,
   warpMeshColumns as vectorMeshColumns,
   warpMeshControlBounds as vectorMeshControlBounds,
@@ -17539,6 +18127,7 @@ export {
   vectorNodeToBezier,
   vectorNodesNear,
   vectorOperandOperation,
+  vectorPages,
   vectorPaintLayerNodes,
   vectorPaintSolid,
   vectorPaintSwatch,
@@ -17554,6 +18143,13 @@ export {
   vectorPathTextPositions,
   vectorPathWorldBezier,
   vectorPathfinderShape,
+  vectorPerspectiveFlatToPlane,
+  vectorPerspectiveGridLines,
+  vectorPerspectiveMapPath,
+  vectorPerspectivePlaneMap,
+  vectorPerspectivePlaneToFlat,
+  vectorPerspectivePlanes,
+  vectorPerspectivePreset,
   vectorPolarAngles,
   vectorPolarIncrementOf,
   vectorRepeaterCopies,