@pixerate/editor 0.115.0 → 0.116.0

package/dist/vector/index.js

@@ -10,11 +10,15 @@ import {
 } from "../chunk-3UFGNHSP.js";
 import {
   applyHomography,
+  decodePng,
   homographyFromPoints,
   homographyKeepsQuad,
+  isPng,
   orderQuad,
+  parseDataUrl,
   solve8
-} from "../chunk-GX332W2C.js";
+} from "../chunk-N3467VD6.js";
+import "../chunk-6FCKOS2B.js";
 import {
   correspondMorphContours,
   createVectorMorph,
@@ -33,7 +37,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-MMVHBKMM.js";
+} from "../chunk-T2P5TIZ6.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -67,6 +71,7 @@ import {
   VECTOR_HORIZONTAL_RESIZING_LABELS,
   VECTOR_MASK_TYPES,
   VECTOR_MERGE_MODES,
+  VECTOR_MESH_MAX,
   VECTOR_PARAGRAPH_STYLE_KEYS,
   VECTOR_PATHFINDER_OPERATIONS,
   VECTOR_PATH_TEXT_BASELINES,
@@ -100,6 +105,7 @@ import {
   arrowheadInset,
   arrowheadPath,
   arrowheadWeight,
+  autoVectorFreeformGradient,
   bakeVectorTextGeometry,
   bezierToSubpaths,
   boundsFromPoints,
@@ -122,6 +128,7 @@ import {
   createOutlineTextShaper,
   createVectorEffect,
   createVectorFilter,
+  createVectorMeshGradient,
   cssFontFamily,
   dashIntervals,
   decomposeRigid,
@@ -182,11 +189,14 @@ import {
   isVectorConnector,
   isVectorFilterType,
   isVectorFrame,
+  isVectorFreeformGradient,
   isVectorGradient,
   isVectorLiveBoolean,
   isVectorMaskActive,
   isVectorMaskGroup,
   isVectorMaskType,
+  isVectorMeshGradient,
+  isVectorShadedPaint,
   knifePath,
   layoutVectorText,
   lineSubpath,
@@ -195,6 +205,7 @@ import {
   mapVectorGradient,
   mapVectorPaint,
   mapVectorPoints,
+  mapVectorShadedPaint,
   mapVectorSubpaths,
   mapWarpMeshPoints,
   matrixAbout,
@@ -209,6 +220,7 @@ import {
   nearestSegment,
   nearestStrokePosition,
   nearestVectorConnectionSite,
+  nearestVectorShadingPoint,
   needsVectorPaintLayers,
   newVectorStrokeLayer,
   nextVectorCornerKind,
@@ -236,6 +248,7 @@ import {
   pullWarpMesh,
   rectSubpath,
   removeAnchors,
+  removeVectorFreeformPoint,
   removeVectorGradientStop,
   removeWarpMeshSplitU,
   removeWarpMeshSplitV,
@@ -253,6 +266,7 @@ import {
   roundSubpaths,
   routeVectorConnector,
   samplePlainStops,
+  sampleVectorFreeform,
   sampleVectorGradient,
   sampleVectorGradientAt,
   sampleVectorPaintDefAt,
@@ -264,6 +278,7 @@ import {
   sanitizeVectorGradient,
   sanitizeVectorMask,
   sanitizeVectorResizing,
+  sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
   sanitizeVectorTextFields,
@@ -297,6 +312,7 @@ import {
   transformVectorGradient,
   transformVectorNode,
   transformVectorPaint,
+  transformVectorShadedPaint,
   translateAnchor,
   translateMatrix,
   trimIntervals,
@@ -338,6 +354,9 @@ import {
   vectorFrameDocument,
   vectorFrameDrawn,
   vectorFrameRectPath,
+  vectorFreeformField,
+  vectorFreeformLineSegments,
+  vectorFreeformSpreadScale,
   vectorGradientArea,
   vectorGradientAspect,
   vectorGradientFocalParam,
@@ -368,8 +387,11 @@ import {
   vectorMaskedGeometry,
   vectorMaskedLocalBounds,
   vectorMaskedShapes,
+  vectorMeshColorAt,
   vectorMeshFromOutline,
+  vectorMeshLines,
   vectorMeshOutline,
+  vectorMeshPointAt,
   vectorNodeBounds,
   vectorNodeEnvelope,
   vectorNodeFilterSvg,
@@ -388,6 +410,8 @@ import {
   vectorPathTextPositions,
   vectorPathWorldBezier,
   vectorRepeaterCopies,
+  vectorRgbaToCss,
+  vectorShadedSvgDefs,
   vectorSpatialIndex,
   vectorStacksHaveGradient,
   vectorStrokeGradientDefs,
@@ -440,7 +464,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-VXR7XWMF.js";
+} from "../chunk-7LNZAWSJ.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -452,11 +476,13 @@ import {
   fitCubics,
   pathBoolean,
   pathToContours,
+  pointInBezierPath,
   segmentDerivative,
   segmentIntersections,
   segmentNearest,
   segmentPoint,
   segmentTangent,
+  simplifyRing,
   transformBezierPath
 } from "../chunk-YCSFS3GK.js";
 import {
@@ -556,7 +582,11 @@ function resolveVectorBlendOptions(options) {
 }
 function paintColors(p) {
   if (typeof p === "string") return [p];
-  if (p && typeof p === "object") return p.stops.map((s) => s.color);
+  if (p && typeof p === "object") {
+    if (p.type === "mesh") return p.colors;
+    if (p.type === "freeform") return p.points.map((q) => q.color);
+    return p.stops.map((s) => s.color);
+  }
   return [];
 }
 function vectorBlendColorDistance(a, b) {
@@ -765,6 +795,293 @@ function releaseVectorBlend(group, newId) {
   return [...keys, group.transform ? transformVectorNode(path, m) : path];
 }
 
+// src/vector/trace.ts
+var VECTOR_TRACE_MAX_PIXELS = 4e6;
+function signedArea(p) {
+  let a = 0;
+  for (let i = 0; i < p.length; i++) {
+    const [x0, y0] = p[i];
+    const [x1, y1] = p[(i + 1) % p.length];
+    a += x0 * y1 - x1 * y0;
+  }
+  return a / 2;
+}
+function pointInPoly(p, poly) {
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if (yi > p[1] !== yj > p[1] && p[0] < (xj - xi) * (p[1] - yi) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+function vectorTraceContours(field, w, h, threshold) {
+  const gw = w + 2;
+  const gh = h + 2;
+  const val = (i, j) => i === 0 || j === 0 || i > w || j > h ? -Infinity : field[(j - 1) * w + (i - 1)];
+  const inside = (i, j) => val(i, j) >= threshold;
+  const pos = (i, j) => [i - 0.5, j - 0.5];
+  const cross2 = (a, b) => {
+    const va = val(a[0], a[1]);
+    const vb = val(b[0], b[1]);
+    let t;
+    if (Number.isFinite(va) && Number.isFinite(vb) && Math.abs(vb - va) > 1e-12) t = Math.min(1, Math.max(0, (threshold - va) / (vb - va)));
+    else if (Number.isFinite(va)) t = va >= threshold ? 0.5 : 0;
+    else t = vb >= threshold ? 0.5 : 1;
+    const pa = pos(a[0], a[1]);
+    const pb = pos(b[0], b[1]);
+    return [pa[0] + (pb[0] - pa[0]) * t, pa[1] + (pb[1] - pa[1]) * t];
+  };
+  const hid = (i, j) => 2 * (j * gw + i);
+  const vid = (i, j) => 2 * (j * gw + i) + 1;
+  const next = /* @__PURE__ */ new Map();
+  const point = /* @__PURE__ */ new Map();
+  for (let j = 0; j < gh - 1; j++) {
+    for (let i = 0; i < gw - 1; i++) {
+      const tl = inside(i, j);
+      const tr = inside(i + 1, j);
+      const br = inside(i + 1, j + 1);
+      const bl = inside(i, j + 1);
+      const code = +tl << 3 | +tr << 2 | +br << 1 | +bl;
+      if (code === 0 || code === 15) continue;
+      const top = hid(i, j);
+      const bottom = hid(i, j + 1);
+      const left = vid(i, j);
+      const right = vid(i + 1, j);
+      const seg = (a, b) => next.set(a, b);
+      const mean = () => (val(i, j) + val(i + 1, j) + val(i + 1, j + 1) + val(i, j + 1)) / 4;
+      switch (code) {
+        case 1:
+          seg(left, bottom);
+          break;
+        case 2:
+          seg(bottom, right);
+          break;
+        case 3:
+          seg(left, right);
+          break;
+        case 4:
+          seg(right, top);
+          break;
+        case 5:
+          if (mean() >= threshold) {
+            seg(left, top);
+            seg(right, bottom);
+          } else {
+            seg(left, bottom);
+            seg(right, top);
+          }
+          break;
+        case 6:
+          seg(bottom, top);
+          break;
+        case 7:
+          seg(left, top);
+          break;
+        case 8:
+          seg(top, left);
+          break;
+        case 9:
+          seg(top, bottom);
+          break;
+        case 10:
+          if (mean() >= threshold) {
+            seg(top, right);
+            seg(bottom, left);
+          } else {
+            seg(top, left);
+            seg(bottom, right);
+          }
+          break;
+        case 11:
+          seg(top, right);
+          break;
+        case 12:
+          seg(right, left);
+          break;
+        case 13:
+          seg(right, bottom);
+          break;
+        case 14:
+          seg(bottom, left);
+          break;
+      }
+      const edges = [
+        [top, [i, j], [i + 1, j]],
+        [bottom, [i, j + 1], [i + 1, j + 1]],
+        [left, [i, j], [i, j + 1]],
+        [right, [i + 1, j], [i + 1, j + 1]]
+      ];
+      for (const [e, a, b] of edges) if (inside(a[0], a[1]) !== inside(b[0], b[1]) && !point.has(e)) point.set(e, cross2(a, b));
+    }
+  }
+  const out = [];
+  for (const start of [...next.keys()].sort((a, b) => a - b)) {
+    if (!next.has(start)) continue;
+    const poly = [];
+    let e = start;
+    for (; ; ) {
+      const n = next.get(e);
+      if (n === void 0) break;
+      next.delete(e);
+      const p = point.get(e);
+      if (p) poly.push(p);
+      e = n;
+      if (e === start) break;
+    }
+    if (poly.length >= 3) out.push(poly);
+  }
+  return out;
+}
+function loopsOf(field, w, h, threshold, tolerance, minArea) {
+  const loops = [];
+  for (const raw of vectorTraceContours(field, w, h, threshold)) {
+    const area = signedArea(raw);
+    if (Math.abs(area) < Math.max(0, minArea)) continue;
+    const simple = simplifyRing(raw, Math.max(0.01, tolerance));
+    if (simple.length < 3) continue;
+    loops.push({ raw, simple, area, depth: 0 });
+  }
+  for (const l of loops) l.depth = loops.filter((o) => o !== l && Math.abs(o.area) > Math.abs(l.area) && pointInPoly(l.simple[0], o.simple)).length;
+  return loops.sort((a, b) => a.depth - b.depth || Math.abs(b.area) - Math.abs(a.area));
+}
+function loopSubpath(l, tolerance, roundness) {
+  if (roundness <= 0) return { closed: true, anchors: l.simple.map(([x, y]) => ({ x, y })) };
+  const cornerAngleDeg = 25 + roundness * 125;
+  const cubics = fitCubics(l.raw, Math.max(0.05, tolerance), {
+    closed: true,
+    cornerAngleDeg
+  });
+  if (!cubics.length) return { closed: true, anchors: l.simple.map(([x, y]) => ({ x, y })) };
+  const anchors = cubics.map((c, k) => {
+    const prev = cubics[(k - 1 + cubics.length) % cubics.length];
+    return {
+      x: c.p0[0],
+      y: c.p0[1],
+      in: { x: prev.p2[0], y: prev.p2[1] },
+      out: { x: c.p1[0], y: c.p1[1] }
+    };
+  });
+  return { closed: true, anchors };
+}
+function traceField(field, w, h, threshold, o) {
+  const tolerance = o.tolerance ?? 1;
+  const roundness = Math.min(1, Math.max(0, o.cornerRoundness ?? 0.5));
+  return loopsOf(field, w, h, threshold, tolerance, o.minArea ?? 10).map((l) => loopSubpath(l, tolerance, roundness));
+}
+function quantizeVectorTraceColors(pixels, count) {
+  const n = pixels.width * pixels.height;
+  const d = pixels.data;
+  const opaque = [];
+  for (let i = 0; i < n; i++) if (d[i * 4 + 3] >= 128) opaque.push(i);
+  const boxes = opaque.length ? [opaque] : [];
+  const range = (box, c) => {
+    let lo = 255;
+    let hi = 0;
+    for (const i of box) {
+      const v = d[i * 4 + c];
+      if (v < lo) lo = v;
+      if (v > hi) hi = v;
+    }
+    return hi - lo;
+  };
+  while (boxes.length < count) {
+    let best = -1;
+    let bestRange = 0;
+    let bestC = 0;
+    boxes.forEach((b, k) => {
+      if (b.length < 2) return;
+      for (let c = 0; c < 3; c++) {
+        const r = range(b, c);
+        if (r > bestRange) {
+          bestRange = r;
+          best = k;
+          bestC = c;
+        }
+      }
+    });
+    if (best < 0) break;
+    const box = boxes[best].slice().sort((a, b) => d[a * 4 + bestC] - d[b * 4 + bestC]);
+    const key = (k) => d[box[k] * 4 + bestC];
+    const v = key(box.length >> 1);
+    let mid = box.findIndex((_, k) => key(k) >= v);
+    if (mid <= 0) mid = box.findIndex((_, k) => key(k) > v);
+    boxes.splice(best, 1, box.slice(0, mid), box.slice(mid));
+  }
+  const palette = boxes.map((b) => {
+    const s = [0, 0, 0];
+    for (const i of b) for (let c = 0; c < 3; c++) s[c] += d[i * 4 + c];
+    return [Math.round(s[0] / b.length), Math.round(s[1] / b.length), Math.round(s[2] / b.length)];
+  });
+  const index = new Int16Array(n).fill(-1);
+  const counts = palette.map(() => 0);
+  for (const i of opaque) {
+    let best = 0;
+    let bestD = Infinity;
+    palette.forEach((p, k) => {
+      const dd = (d[i * 4] - p[0]) ** 2 + (d[i * 4 + 1] - p[1]) ** 2 + (d[i * 4 + 2] - p[2]) ** 2;
+      if (dd < bestD) {
+        bestD = dd;
+        best = k;
+      }
+    });
+    index[i] = best;
+    counts[best]++;
+  }
+  return { palette, index, counts };
+}
+var hex = (c) => `#${c.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
+function traceVectorImage(pixels, options = {}) {
+  const { width: w, height: h, data } = pixels;
+  if (!(w > 0 && h > 0) || data.length < w * h * 4) throw new Error("The image has no pixels (or fewer than width \xD7 height \xD7 4 values).");
+  if (w * h > VECTOR_TRACE_MAX_PIXELS) throw new Error(`The image has ${w * h} pixels; scale it down to at most ${VECTOR_TRACE_MAX_PIXELS} to trace it.`);
+  const n = w * h;
+  if ((options.mode ?? "threshold") === "threshold") {
+    const field = new Float32Array(n);
+    const byAlpha = options.channel === "alpha";
+    for (let i = 0; i < n; i++) {
+      const a = data[i * 4 + 3] / 255;
+      field[i] = byAlpha ? a : a * (1 - (0.2126 * data[i * 4] + 0.7152 * data[i * 4 + 1] + 0.0722 * data[i * 4 + 2]) / 255);
+    }
+    const subpaths = traceField(field, w, h, Math.min(1, Math.max(0, options.threshold ?? 0.5)), options);
+    return subpaths.length ? [
+      {
+        id: "trace-1",
+        type: "path",
+        name: "Trace",
+        fill: options.color ?? "#000000",
+        stroke: null,
+        fillRule: "evenodd",
+        subpaths
+      }
+    ] : [];
+  }
+  const count = Math.min(32, Math.max(2, Math.round(options.colors ?? 6)));
+  const q = quantizeVectorTraceColors(pixels, count);
+  const order = q.palette.map((_, k) => k).filter((k) => q.counts[k] > 0).sort((a, b) => q.counts[b] - q.counts[a]);
+  const rank = new Map(order.map((k, r) => [k, r]));
+  const out = [];
+  order.forEach((k, r) => {
+    const field = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+      const ix = q.index[i];
+      field[i] = ix >= 0 && rank.get(ix) >= r ? 1 : 0;
+    }
+    const subpaths = traceField(field, w, h, 0.5, options);
+    if (subpaths.length)
+      out.push({
+        id: `trace-${out.length + 1}`,
+        type: "path",
+        name: hex(q.palette[k]),
+        fill: hex(q.palette[k]),
+        stroke: null,
+        fillRule: "evenodd",
+        subpaths
+      });
+  });
+  return out;
+}
+
 // 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);
@@ -4403,6 +4720,7 @@ var VectorEditorController = class _VectorEditorController {
       constraintIssues: this.constraintIssues,
       trackingPoints: this.trackingPoints,
       typedEntry: this.typed,
+      shadingPoint: this.getShadingSelection(),
       canUndo: h.canUndo,
       canRedo: h.canRedo,
       undoLabel: h.undoName,
@@ -5100,6 +5418,14 @@ var VectorEditorController = class _VectorEditorController {
   }
   downGradient(screen, p, input) {
     const before = this.snapshot();
+    const shaded = this.shadedUnder(screen);
+    if (shaded) {
+      this.shadingSel = shaded.index >= 0 ? { nodeId: shaded.nodeId, index: shaded.index } : null;
+      this.drag = { kind: "shading", nodeId: shaded.nodeId, index: shaded.index, start: screen, before, moved: false, alt: !!input.alt };
+      this.interaction = { type: "gradient", part: "handle" };
+      this.notify();
+      return;
+    }
     const a = this.getGradientAnnotator();
     let part = a ? hitVectorGradientAnnotator(a, screen) : null;
     if (a && part) {
@@ -6698,6 +7024,306 @@ var VectorEditorController = class _VectorEditorController {
     return { ok: true, id };
   }
   // -----------------------------------------------------------------------------------------
+  // Image tracing
+  /**
+   * Image Trace: traces RGBA `pixels` into paths (see `traceVectorImage`) and adds them as one
+   * group, the image placed with its top-left at `x, y` (default 0, 0) and `width` wide (default:
+   * one unit per pixel; the height follows). One undo step; selects the group. Returns its id and
+   * the traced paths' ids, bottom to top.
+   */
+  traceImage(pixels, options = {}) {
+    if (options.threshold !== void 0 && !(options.threshold >= 0 && options.threshold <= 1)) return { ok: false, message: "threshold must be from 0 to 1." };
+    if (options.colors !== void 0 && !(Number.isInteger(options.colors) && options.colors >= 2 && options.colors <= 32)) return { ok: false, message: "colors must be a whole number from 2 to 32." };
+    if (options.tolerance !== void 0 && !(options.tolerance > 0)) return { ok: false, message: "tolerance must be above 0 (pixels)." };
+    if (options.width !== void 0 && !(options.width > 0)) return { ok: false, message: "width must be above 0." };
+    if (options.color !== void 0 && !parseVectorColor(options.color)) return { ok: false, message: `"${options.color}" is not a colour.` };
+    let traced;
+    try {
+      traced = traceVectorImage(pixels, options);
+    } catch (e) {
+      return { ok: false, message: e.message };
+    }
+    if (!traced.length) return { ok: false, message: "Nothing to trace: no shape reached the threshold (try another threshold, the alpha channel, or colour mode)." };
+    const k = (options.width ?? pixels.width) / pixels.width;
+    const m = [k, 0, 0, k, options.x ?? 0, options.y ?? 0];
+    const children = traced.map((n) => ({ ...transformVectorNode(n, m), id: this.newId() }));
+    const id = this.newId();
+    this.change("Image Trace", () => {
+      this.setDoc([...this.doc.nodes, { id, type: "group", name: options.name ?? "Image Trace", children }]);
+      this.selection = [id];
+      this.anchors = [];
+      this.editingId = null;
+    });
+    return { ok: true, id, ids: children.map((c) => c.id) };
+  }
+  // -----------------------------------------------------------------------------------------
+  // Gradient meshes and freeform gradients
+  /** The selected point of a mesh or freeform fill (Gradient tool), or null. */
+  shadingSel = null;
+  /** Selected paths with a mesh or freeform fill. */
+  shadedPaths() {
+    return this.gradientPaths().filter((n) => isVectorShadedPaint(n.fill));
+  }
+  /** The shaded fill's point under `screen` (index), or a freeform shape under it (index -1), or null. */
+  shadedUnder(screen) {
+    const p = this.screenToDocument(screen);
+    for (const n of this.shadedPaths()) {
+      const world = this.worldOf(n.id);
+      const fill = n.fill;
+      const z = this.viewport.zoom;
+      let best = -1;
+      let bestD = 8;
+      fill.points.forEach((q, k) => {
+        const w = applyMatrix(world, q);
+        const d = Math.hypot(w.x - p.x, w.y - p.y) * z;
+        if (d <= bestD) {
+          best = k;
+          bestD = d;
+        }
+      });
+      if (best >= 0) return { nodeId: n.id, index: best };
+      if (isVectorFreeformGradient(fill) && hitTestVectorNode(n, p, 0, this.parentMatrixOf(n.id))) return { nodeId: n.id, index: -1 };
+    }
+    return null;
+  }
+  parentMatrixOf(id) {
+    return vectorParentMatrix(this.doc.nodes, id) ?? IDENTITY_MATRIX;
+  }
+  moveShading(drag, screen, p) {
+    if (drag.index < 0) return;
+    if (!drag.moved && Math.hypot(screen.x - drag.start.x, screen.y - drag.start.y) < 3) return;
+    drag.moved = true;
+    const node = this.getNode(drag.nodeId);
+    if (!node || !isVectorShadedPaint(node.fill)) return;
+    const local = this.toLocal(drag.nodeId, p);
+    const fill = mapVectorShadedPaint(node.fill, (q) => q);
+    const moved = isVectorMeshGradient(fill) ? { ...fill, points: fill.points.map((q, k) => k === drag.index ? { x: local.x, y: local.y } : q) } : { ...fill, points: fill.points.map((q, k) => k === drag.index ? { ...q, x: local.x, y: local.y } : q) };
+    this.replaceNode(drag.nodeId, normalizeVectorPaintStacks({ ...node, fill: moved }, "shorthand"));
+    this.notify(true);
+  }
+  upShading(drag) {
+    if (drag.moved) return this.commit(this.getNode(drag.nodeId) && isVectorMeshGradient(this.getNode(drag.nodeId).fill) ? "Move Mesh Point" : "Move Freeform Point", drag.before);
+    const at = this.screenToDocument(drag.start);
+    if (drag.index < 0) {
+      const r = this.addFreeformPoint(drag.nodeId, at);
+      if (r.ok) {
+        this.shadingSel = { nodeId: drag.nodeId, index: r.index };
+        this.notify();
+      }
+      return;
+    }
+    if (drag.alt && isVectorFreeformGradient(this.getNode(drag.nodeId).fill)) {
+      if (this.removeFreeformPoint(drag.nodeId, drag.index).ok) {
+        this.shadingSel = null;
+        this.notify();
+      }
+      return;
+    }
+    this.notify();
+  }
+  /** The selected point of a mesh or freeform fill (Gradient tool), with its paint's kind, or null. */
+  getShadingSelection() {
+    const sel = this.shadingSel;
+    const node = sel ? this.getNode(sel.nodeId) : void 0;
+    if (!sel || node?.type !== "path" || !isVectorShadedPaint(node.fill) || sel.index >= node.fill.points.length) return null;
+    return { ...sel, kind: node.fill.type };
+  }
+  /** The path `id` (or a message why it cannot take a mesh or freeform fill). */
+  shadingTarget(id) {
+    const n = this.getNode(id);
+    if (!n) return `There is no node "${id}".`;
+    if (n.type !== "path") return `"${id}" is a ${n.type}: meshes and freeform gradients fill paths.`;
+    if (n.locked) return `"${id}" is locked; unlock it first.`;
+    return n;
+  }
+  /** Sets each node's fill in one undo step. */
+  setFills(label, fills, merge) {
+    this.change(
+      label,
+      () => {
+        this.setDoc(mapTree(this.doc.nodes, (n) => fills.has(n.id) && n.type === "path" ? normalizeVectorPaintStacks({ ...n, fill: fills.get(n.id) }, "shorthand") : n));
+      },
+      merge
+    );
+  }
+  /**
+   * Gives paths (default: the selection) a gradient mesh over their own bounds: `rows` ×
+   * `columns` patches (1–32) with points evenly spread, coloured by `colors` (one per point, row by
+   * row), the four `corners` (top-left, top-right, bottom-right, bottom-left) blended, or the
+   * current fill colour. One undo step.
+   */
+  setMeshGradient(input, options = {}) {
+    const { rows, columns } = input;
+    if (!Number.isInteger(rows) || !Number.isInteger(columns) || rows < 1 || columns < 1 || rows > VECTOR_MESH_MAX || columns > VECTOR_MESH_MAX)
+      return { ok: false, message: `rows and columns must be whole numbers from 1 to ${VECTOR_MESH_MAX}.` };
+    const n = (rows + 1) * (columns + 1);
+    if (input.colors && input.colors.length !== n) return { ok: false, message: `colors needs ${n} colours ((rows + 1) \xD7 (columns + 1), row by row); got ${input.colors.length}.` };
+    if (input.corners && input.corners.length !== 4) return { ok: false, message: "corners needs four colours: top-left, top-right, bottom-right, bottom-left." };
+    const bad = [...input.colors ?? [], ...input.corners ?? []].find((c) => !parseVectorColor(c));
+    if (bad !== void 0) return { ok: false, message: `"${bad}" is not a colour.` };
+    const ids = options.ids ?? this.selection;
+    if (!ids.length) return { ok: false, message: "Select a path first." };
+    const fills = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const t = this.shadingTarget(id);
+      if (typeof t === "string") return { ok: false, message: t };
+      const b = vectorPathLocalBounds(t);
+      if (!b || !(b.width > 0 && b.height > 0)) return { ok: false, message: `"${id}" has no area to fill.` };
+      const base = typeof t.fill === "string" && parseVectorColor(t.fill) ? t.fill : "#ffffff";
+      fills.set(id, createVectorMeshGradient(b, rows, columns, input.colors ? { colors: input.colors } : input.corners ? { corners: input.corners } : { colors: Array.from({ length: n }, () => base) }));
+    }
+    this.setFills("Gradient Mesh", fills);
+    return { ok: true };
+  }
+  /**
+   * Gives paths (default: the selection) a freeform gradient: `points` in document units (each
+   * `{ x, y, color, opacity?, spread? }`) with optional `lines` through them, or, without points,
+   * four or more points placed inside each path and coloured along `colors` (default the current
+   * fill to white). One undo step.
+   */
+  setFreeformGradient(input = {}, options = {}) {
+    const ids = options.ids ?? this.selection;
+    if (!ids.length) return { ok: false, message: "Select a path first." };
+    const fills = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const t = this.shadingTarget(id);
+      if (typeof t === "string") return { ok: false, message: t };
+      const b = vectorPathLocalBounds(t);
+      if (!b) return { ok: false, message: `"${id}" has no area to fill.` };
+      let f;
+      if (input.points?.length) {
+        f = sanitizeVectorShadedPaint({ type: "freeform", points: input.points.map((q) => ({ ...q, ...this.toLocal(id, q) })), ...input.lines ? { lines: input.lines } : {} });
+        if (!f) return { ok: false, message: "Each point needs x, y (numbers) and a colour." };
+        if (input.lines && (f.lines?.length ?? 0) !== input.lines.length) return { ok: false, message: `Each line needs two or more point indices from 0 to ${input.points.length - 1}, none twice in a row.` };
+      } else {
+        const bad = (input.colors ?? []).find((c) => !parseVectorColor(c));
+        if (bad !== void 0) return { ok: false, message: `"${bad}" is not a colour.` };
+        const outline = subpathsToBezier(t.subpaths);
+        const inside = (q) => pointInBezierPath(outline, [q.x, q.y], t.fillRule ?? "nonzero");
+        const base = typeof t.fill === "string" && parseVectorColor(t.fill) ? t.fill : "#000000";
+        f = autoVectorFreeformGradient(b, input.colors?.length ? input.colors : [base, "#ffffff"], inside);
+      }
+      fills.set(id, f);
+    }
+    this.setFills("Freeform Gradient", fills);
+    return { ok: true };
+  }
+  /** The mesh or freeform fill of path `id` with its points in document units, or null. */
+  getShading(id) {
+    const n = this.getNode(id);
+    if (n?.type !== "path" || !isVectorShadedPaint(n.fill)) return null;
+    const world = this.worldOf(id);
+    return mapVectorShadedPaint(n.fill, (q) => applyMatrix(world, q));
+  }
+  /** Checks a shading point edit: the path, its shaded fill and the index. */
+  shadingPoint(id, index, kind) {
+    const t = this.shadingTarget(id);
+    if (typeof t === "string") return t;
+    const paint = t.fill;
+    if (kind === "mesh" ? !isVectorMeshGradient(paint) : !isVectorFreeformGradient(paint))
+      return `"${id}" has no ${kind === "mesh" ? "gradient mesh" : "freeform gradient"} fill (add one with ${kind === "mesh" ? "vector.setMeshGradient" : "vector.setFreeformGradient"}).`;
+    const p = paint;
+    if (!Number.isInteger(index) || index < 0 || index >= p.points.length) return `Point ${index} is out of range: the ${kind} has ${p.points.length} points (0 to ${p.points.length - 1}).`;
+    return { node: t, paint: p };
+  }
+  /**
+   * Changes point `index` (row by row) of path `id`'s gradient mesh: moves it to `x, y` (document
+   * units) and / or sets its `color` and `opacity`. One undo step (merged while `merge` is the same key).
+   */
+  setMeshPoint(id, index, patch, options = {}) {
+    const r = this.shadingPoint(id, index, "mesh");
+    if (typeof r === "string") return { ok: false, message: r };
+    if (patch.color !== void 0 && !parseVectorColor(patch.color)) return { ok: false, message: `"${patch.color}" is not a colour.` };
+    if (patch.x === void 0 !== (patch.y === void 0)) return { ok: false, message: "Give both x and y to move the point." };
+    const m = r.paint;
+    const at = patch.x !== void 0 ? this.toLocal(id, { x: patch.x, y: patch.y }) : m.points[index];
+    const next = {
+      ...m,
+      points: m.points.map((q, k) => k === index ? { x: at.x, y: at.y } : q),
+      colors: m.colors.map((c, k) => k === index && patch.color !== void 0 ? patch.color : c)
+    };
+    if (patch.opacity !== void 0) {
+      const ops = m.opacities ?? m.points.map(() => 1);
+      next.opacities = ops.map((o, k) => k === index ? Math.min(1, Math.max(0, patch.opacity)) : o);
+    }
+    this.setFills("Edit Mesh Point", /* @__PURE__ */ new Map([[id, next]]), options.merge);
+    return { ok: true };
+  }
+  /** Adds a point to path `id`'s freeform gradient at `x, y` (document units), coloured `color` (default: the colour there now). One undo step. Returns its index. */
+  addFreeformPoint(id, point) {
+    const t = this.shadingTarget(id);
+    if (typeof t === "string") return { ok: false, message: t };
+    if (!isVectorFreeformGradient(t.fill)) return { ok: false, message: `"${id}" has no freeform gradient fill (add one with vector.setFreeformGradient).` };
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return { ok: false, message: "x and y must be numbers." };
+    if (point.color !== void 0 && !parseVectorColor(point.color)) return { ok: false, message: `"${point.color}" is not a colour.` };
+    const local = this.toLocal(id, point);
+    const f = t.fill;
+    const b = vectorPathLocalBounds(t);
+    const here = sampleVectorFreeform(vectorFreeformField(f, b ? vectorFreeformSpreadScale(b) : 1), local);
+    const next = {
+      ...f,
+      points: [
+        ...f.points,
+        {
+          x: local.x,
+          y: local.y,
+          color: point.color ?? vectorRgbaToCss([here[0], here[1], here[2], 1]),
+          ...point.opacity !== void 0 && point.opacity < 1 ? { opacity: Math.max(0, point.opacity) } : {},
+          ...point.spread ? { spread: Math.min(1, Math.max(0, point.spread)) } : {}
+        }
+      ]
+    };
+    this.setFills("Add Freeform Point", /* @__PURE__ */ new Map([[id, next]]));
+    return { ok: true, index: next.points.length - 1 };
+  }
+  /** Changes point `index` of path `id`'s freeform gradient: position (document units), colour, opacity, spread. One undo step (merged while `merge` is the same key). */
+  setFreeformPoint(id, index, patch, options = {}) {
+    const r = this.shadingPoint(id, index, "freeform");
+    if (typeof r === "string") return { ok: false, message: r };
+    if (patch.color !== void 0 && !parseVectorColor(patch.color)) return { ok: false, message: `"${patch.color}" is not a colour.` };
+    if (patch.x === void 0 !== (patch.y === void 0)) return { ok: false, message: "Give both x and y to move the point." };
+    const f = r.paint;
+    const at = patch.x !== void 0 ? this.toLocal(id, { x: patch.x, y: patch.y }) : null;
+    const next = {
+      ...f,
+      points: f.points.map((q, k) => {
+        if (k !== index) return q;
+        const out = { ...q, ...at ? { x: at.x, y: at.y } : {}, ...patch.color !== void 0 ? { color: patch.color } : {} };
+        if (patch.opacity !== void 0) {
+          if (patch.opacity >= 1) delete out.opacity;
+          else out.opacity = Math.max(0, patch.opacity);
+        }
+        if (patch.spread !== void 0) {
+          if (patch.spread <= 0) delete out.spread;
+          else out.spread = Math.min(1, patch.spread);
+        }
+        return out;
+      })
+    };
+    this.setFills("Edit Freeform Point", /* @__PURE__ */ new Map([[id, next]]), options.merge);
+    return { ok: true };
+  }
+  /** Removes point `index` of path `id`'s freeform gradient (never the last one); lines through it close up. One undo step. */
+  removeFreeformPoint(id, index) {
+    const r = this.shadingPoint(id, index, "freeform");
+    if (typeof r === "string") return { ok: false, message: r };
+    const next = removeVectorFreeformPoint(r.paint, index);
+    if (!next) return { ok: false, message: "A freeform gradient keeps at least one point." };
+    this.setFills("Remove Freeform Point", /* @__PURE__ */ new Map([[id, next]]));
+    return { ok: true };
+  }
+  /** Replaces the lines of path `id`'s freeform gradient: each a list of two or more point indices it runs through. One undo step. */
+  setFreeformLines(id, lines) {
+    const t = this.shadingTarget(id);
+    if (typeof t === "string") return { ok: false, message: t };
+    if (!isVectorFreeformGradient(t.fill)) return { ok: false, message: `"${id}" has no freeform gradient fill (add one with vector.setFreeformGradient).` };
+    const f = sanitizeVectorShadedPaint({ ...t.fill, lines });
+    if ((f.lines?.length ?? 0) !== lines.length) return { ok: false, message: `Each line needs two or more point indices from 0 to ${t.fill.points.length - 1}, none twice in a row.` };
+    const { lines: _l, ...rest } = t.fill;
+    this.setFills("Freeform Lines", /* @__PURE__ */ new Map([[id, lines.length ? { ...rest, lines: f.lines } : rest]]));
+    return { ok: true };
+  }
+  // -----------------------------------------------------------------------------------------
   // Object snap tracking and typed entry (after cadcraft's snap/tracking.rs and its direct
   // distance entry)
   trackingPoints = [];
@@ -8914,6 +9540,8 @@ var VectorEditorController = class _VectorEditorController {
         return;
       case "gradient":
         return this.moveGradient(drag, screen, p, input);
+      case "shading":
+        return this.moveShading(drag, screen, p);
       case "envelope":
         return this.moveEnvelope(drag, p);
       case "move": {
@@ -9316,6 +9944,8 @@ var VectorEditorController = class _VectorEditorController {
         return this.upBuilder(drag);
       case "gradient":
         return this.upGradient(drag);
+      case "shading":
+        return this.upShading(drag);
       case "stroke": {
         this.notify();
         if (drag.tool === "knife") this.knife(drag.points);
@@ -11109,6 +11739,40 @@ function outlinePaths(node, parent, entered) {
   if ((hasOwnVectorAppearance(node) || isVectorMaskActive(node)) && !entered.has(node.id)) return [transformBezierPath(vectorAppearanceOutline(node), m)];
   return node.children.filter((c) => c.visible !== false).flatMap((c) => outlinePaths(c, m, entered));
 }
+function shadingOverlay(state) {
+  if (state.tool !== "gradient") return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of state.selection) {
+    const root = findVectorNode(state.document.nodes, id);
+    if (!root) continue;
+    for (const n of collectPathNodes(root)) {
+      if (seen.has(n.id) || !isVectorShadedPaint(n.fill)) continue;
+      seen.add(n.id);
+      const world = vectorWorldMatrix(state.document.nodes, n.id);
+      if (!world) continue;
+      const sc = (q) => toScreen(state, applyMatrix(world, q));
+      const curve = (c) => {
+        const [a, b, d, e] = c.map(sc);
+        return `M${fmt2(a.x)} ${fmt2(a.y)}C${fmt2(b.x)} ${fmt2(b.y)} ${fmt2(d.x)} ${fmt2(d.y)} ${fmt2(e.x)} ${fmt2(e.y)}`;
+      };
+      const fill = n.fill;
+      const lines = [];
+      if (isVectorMeshGradient(fill)) {
+        const l = vectorMeshLines(fill);
+        for (const row of [...l.rows, ...l.columns]) lines.push(row.map(curve).join(""));
+      } else (fill.lines ?? []).forEach((_, k) => lines.push(vectorFreeformLineSegments(fill, k).map(curve).join("")));
+      const sel = state.shadingPoint && state.shadingPoint.nodeId === n.id ? state.shadingPoint.index : -1;
+      out.push({
+        nodeId: n.id,
+        kind: fill.type,
+        lines,
+        points: fill.points.map((q, index) => ({ index, ...sc(q), color: isVectorMeshGradient(fill) ? fill.colors[index] : fill.points[index].color, selected: index === sel }))
+      });
+    }
+  }
+  return out;
+}
 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;
@@ -11380,6 +12044,7 @@ function getVectorOverlayRenderData(state) {
     constraints: constraintOverlay(state),
     frames: frameLabels(state),
     connectorSites: connectorSiteOverlay(state),
+    shading: shadingOverlay(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
   };
@@ -11687,8 +12352,8 @@ function vectorPaintToHex(paint) {
   if (typeof paint !== "string") return null;
   const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(paint.trim());
   if (!m) return null;
-  const hex = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
-  return `#${hex.toLowerCase()}`;
+  const hex2 = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
+  return `#${hex2.toLowerCase()}`;
 }
 var VECTOR_GRADIENT_TYPE_LABELS = { linear: "Linear", radial: "Radial", conic: "Conic", reflected: "Reflected", diamond: "Diamond" };
 var VECTOR_GRADIENT_SPREAD_LABELS = { pad: "Pad", reflect: "Reflect", repeat: "Repeat" };
@@ -11975,6 +12640,8 @@ var STYLE_PROPS = {
   fillRule: { type: "string", enum: ["nonzero", "evenodd"], description: "Which areas count as inside (default nonzero)." }
 };
 var checkPaint = (paint, where) => {
+  if (paint && typeof paint === "object" && (paint.type === "mesh" || paint.type === "freeform"))
+    return sanitizeVectorShadedPaint(paint) ?? fail(`${where} is not a valid mesh or freeform gradient (see vector.setMeshGradient / vector.setFreeformGradient).`);
   if (paint && typeof paint === "object") return sanitizeVectorGradient(paint) ?? fail(`${where} is not a valid gradient: give a type and at least one stop { offset, color }.`);
   return paint;
 };
@@ -12928,6 +13595,235 @@ function createVectorCommands(controller, options = {}) {
       issues: state.constraintIssues
     };
   };
+  const traceCommands = () => [
+    {
+      ...base,
+      id: `${prefix}traceImage`,
+      label: "Image Trace\u2026",
+      keywords: ["trace", "image trace", "live trace", "vectorize", "bitmap to vector", "png to svg", "autotrace", "posterize"],
+      description: "Traces a PNG (base64 data URL) into vector paths and adds them as one group: `threshold` mode makes one even-odd path where the image is dark (or opaque with channel alpha); `color` mode makes a stacked path per colour (median-cut to `colors`, the most common at the bottom). Placed with its top-left at x, y and `width` wide (default one unit per pixel). One undo step. Returns { id, paths: [{ id, name, fill, subpaths }] }.",
+      params: {
+        type: "object",
+        properties: {
+          image: { type: "string", description: "The image as a data:image/png;base64,\u2026 URL (up to 4 million pixels)." },
+          mode: { type: "string", enum: ["threshold", "color"], description: "threshold (one colour, default) or color (a path per colour)." },
+          channel: { type: "string", enum: ["luminance", "alpha"], description: "Threshold mode: trace dark pixels (luminance, default) or opaque ones (alpha)." },
+          threshold: { type: "number", minimum: 0, maximum: 1, description: "Threshold mode: inside where darkness (or alpha) reaches this (default 0.5)." },
+          color: { type: "string", description: "Threshold mode: the fill (default black)." },
+          colors: { type: "integer", minimum: 2, maximum: 32, description: "Colour mode: how many colours (default 6)." },
+          tolerance: { type: "number", exclusiveMinimum: 0, description: "How far the outline may stray from the pixels, in pixels (default 1; larger is simpler)." },
+          minArea: { type: "number", minimum: 0, description: "Drop shapes smaller than this many square pixels (default 10)." },
+          cornerRoundness: { type: "number", minimum: 0, maximum: 1, description: "0: polygons with sharp corners; 1: smooth curves (default 0.5)." },
+          x: { type: "number", description: "Left edge in document units (default 0)." },
+          y: { type: "number", description: "Top edge in document units (default 0)." },
+          width: { type: "number", exclusiveMinimum: 0, description: "Width in document units (default: the image width in pixels)." },
+          name: { type: "string", description: 'Group name (default "Image Trace").' }
+        },
+        required: ["image"],
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { image, ...options2 } = params;
+        const parsed = parseDataUrl(image);
+        if (!parsed || !isPng(parsed.bytes)) fail("image must be a PNG data URL (data:image/png;base64,\u2026).");
+        let decoded;
+        try {
+          decoded = decodePng(parsed.bytes, { maxPixels: VECTOR_TRACE_MAX_PIXELS });
+        } catch (e) {
+          return fail(`The PNG could not be read: ${e.message}`);
+        }
+        const r = controller.traceImage(decoded, options2);
+        check(r);
+        return {
+          id: r.id,
+          paths: r.ids.map((id) => {
+            const n = controller.getNode(id);
+            return { id, name: n.name, fill: n.fill, subpaths: n.subpaths.length };
+          })
+        };
+      }
+    }
+  ];
+  const shadingResult = (id) => ({ id, shading: controller.getShading(id) ?? fail(`"${id}" has no mesh or freeform fill.`) });
+  const COLOR = { type: "string", description: "A CSS colour." };
+  const FREEFORM_POINT = {
+    type: "object",
+    properties: {
+      x: { type: "number", description: "Document units." },
+      y: { type: "number", description: "Document units." },
+      color: COLOR,
+      opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0\u20131 (default 1)." },
+      spread: { type: "number", minimum: 0, maximum: 1, description: "Radius of pure colour round the point, as a fraction of half the shape's longer side (default 0)." }
+    },
+    required: ["x", "y", "color"],
+    additionalProperties: false
+  };
+  const LINES = { type: "array", items: { type: "array", items: { type: "integer", minimum: 0 }, minItems: 2 }, description: "Lines, each the point indices (two or more) a smooth curve runs through; the colours flow along it." };
+  const shadingCommands = () => [
+    {
+      ...base,
+      id: `${prefix}getShading`,
+      label: "Get Mesh or Freeform Gradient",
+      readOnly: true,
+      keywords: ["mesh", "gradient mesh", "freeform", "freeform gradient", "points"],
+      description: `Returns a path's mesh or freeform fill with its points in document units: { id, shading } where shading is { type: "mesh", rows, columns, points (row by row), colors, opacities? } or { type: "freeform", points: [{ x, y, color, opacity?, spread? }], lines? }. Point indices are what the edit commands take.`,
+      params: { type: "object", properties: { id: { type: "string", description: "The path (from vector.list)." } }, required: ["id"], additionalProperties: false },
+      run: (_ctx, params) => shadingResult(params.id)
+    },
+    {
+      ...base,
+      id: `${prefix}setMeshGradient`,
+      label: "Create Gradient Mesh\u2026",
+      keywords: ["mesh", "gradient mesh", "coons", "patch", "shading", "realistic", "smooth shading"],
+      description: "Fills paths (`ids`, default the selection) with a gradient mesh over their bounds: rows \xD7 columns smooth patches whose points blend colours. Colour it with `colors` (one per point, (rows + 1) \xD7 (columns + 1), row by row) or the four `corners`, else the current fill colour, then move and recolour points with vector.setMeshPoint. One undo step. Returns { meshes: [{ id, shading }] }.",
+      params: {
+        type: "object",
+        properties: {
+          ids: { ...IDS, description: "Paths to fill (default: the selection)." },
+          rows: { type: "integer", minimum: 1, maximum: 32, description: "Patch rows." },
+          columns: { type: "integer", minimum: 1, maximum: 32, description: "Patch columns." },
+          colors: { type: "array", items: COLOR, description: "A colour per point, row by row ((rows + 1) \xD7 (columns + 1) of them)." },
+          corners: { type: "array", items: COLOR, minItems: 4, maxItems: 4, description: "Top-left, top-right, bottom-right and bottom-left colours, blended across." }
+        },
+        required: ["rows", "columns"],
+        additionalProperties: false
+      },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const list2 = ids(params);
+        check(controller.setMeshGradient({ rows: params.rows, columns: params.columns, ...params.colors ? { colors: params.colors } : {}, ...params.corners ? { corners: params.corners } : {} }, { ids: list2 }));
+        return { meshes: list2.map(shadingResult) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setMeshPoint`,
+      label: "Edit Mesh Point",
+      keywords: ["mesh", "mesh point", "colour", "move point"],
+      description: "Moves point `index` (row by row, from vector.getShading) of a path's gradient mesh to x, y (document units, both or neither) and / or sets its colour and opacity. One undo step. Returns { id, shading }.",
+      params: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "The path." },
+          index: { type: "integer", minimum: 0, description: "Point index, row by row." },
+          x: { type: "number", description: "New position (document units)." },
+          y: { type: "number", description: "New position (document units)." },
+          color: COLOR,
+          opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0\u20131." }
+        },
+        required: ["id", "index"],
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { id, index, ...patch } = params;
+        if (!Object.keys(patch).length) fail("Pass at least one of x / y, color, opacity.");
+        check(controller.setMeshPoint(id, index, patch));
+        return shadingResult(id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setFreeformGradient`,
+      label: "Create Freeform Gradient\u2026",
+      keywords: ["freeform", "freeform gradient", "colour points", "shading", "blend colours"],
+      description: "Fills paths (`ids`, default the selection) with a freeform gradient: colour `points` placed anywhere (document units) blending into each other, with optional `lines` that carry colour along smooth curves. Without points, four or more are placed inside each path, coloured along `colors` (default its fill to white). One undo step. Returns { gradients: [{ id, shading }] }.",
+      params: {
+        type: "object",
+        properties: {
+          ids: { ...IDS, description: "Paths to fill (default: the selection)." },
+          points: { type: "array", items: FREEFORM_POINT, description: "The colour points (document units)." },
+          lines: LINES,
+          colors: { type: "array", items: COLOR, description: "Without points: colours the placed points take, first to last." }
+        },
+        additionalProperties: false
+      },
+      undoable: true,
+      enabled: enabledFor,
+      run: (_ctx, params) => {
+        const { ids: _i, ...input } = params ?? {};
+        const list2 = ids(params);
+        check(controller.setFreeformGradient(input, { ids: list2 }));
+        return { gradients: list2.map(shadingResult) };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}addFreeformPoint`,
+      label: "Add Freeform Point",
+      keywords: ["freeform", "colour point", "add point"],
+      description: "Adds a colour point to a path's freeform gradient at x, y (document units), coloured `color` (default: the colour there now). One undo step. Returns { id, index, shading }.",
+      params: {
+        type: "object",
+        properties: { id: { type: "string", description: "The path." }, x: { type: "number", description: "Document units." }, y: { type: "number", description: "Document units." }, color: COLOR, opacity: FREEFORM_POINT.properties.opacity, spread: FREEFORM_POINT.properties.spread },
+        required: ["id", "x", "y"],
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { id, ...point } = params;
+        const r = controller.addFreeformPoint(id, point);
+        check(r);
+        return { ...shadingResult(id), index: r.index };
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setFreeformPoint`,
+      label: "Edit Freeform Point",
+      keywords: ["freeform", "colour point", "move point", "spread"],
+      description: "Changes point `index` (from vector.getShading) of a path's freeform gradient: x, y (document units, both or neither), color, opacity, spread. One undo step. Returns { id, shading }.",
+      params: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "The path." },
+          index: { type: "integer", minimum: 0, description: "Point index." },
+          x: { type: "number", description: "New position (document units)." },
+          y: { type: "number", description: "New position (document units)." },
+          color: COLOR,
+          opacity: FREEFORM_POINT.properties.opacity,
+          spread: FREEFORM_POINT.properties.spread
+        },
+        required: ["id", "index"],
+        additionalProperties: false
+      },
+      undoable: true,
+      run: (_ctx, params) => {
+        const { id, index, ...patch } = params;
+        if (!Object.keys(patch).length) fail("Pass at least one of x / y, color, opacity, spread.");
+        check(controller.setFreeformPoint(id, index, patch));
+        return shadingResult(id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}removeFreeformPoint`,
+      label: "Remove Freeform Point",
+      keywords: ["freeform", "colour point", "delete point"],
+      description: "Removes point `index` of a path's freeform gradient (never the last one); lines through it close up and later indices shift down. One undo step. Returns { id, shading }.",
+      params: { type: "object", properties: { id: { type: "string", description: "The path." }, index: { type: "integer", minimum: 0, description: "Point index." } }, required: ["id", "index"], additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        check(controller.removeFreeformPoint(params.id, params.index));
+        return shadingResult(params.id);
+      }
+    },
+    {
+      ...base,
+      id: `${prefix}setFreeformLines`,
+      label: "Freeform Lines",
+      keywords: ["freeform", "lines", "colour lines", "curve"],
+      description: "Replaces the lines of a path's freeform gradient (an empty list removes them): each line is the point indices a smooth curve runs through, carrying the colours along it. One undo step. Returns { id, shading }.",
+      params: { type: "object", properties: { id: { type: "string", description: "The path." }, lines: LINES }, required: ["id", "lines"], additionalProperties: false },
+      undoable: true,
+      run: (_ctx, params) => {
+        check(controller.setFreeformLines(params.id, params.lines));
+        return shadingResult(params.id);
+      }
+    }
+  ];
   const snapResult = () => {
     const { grid, objects, guides, threshold, angles, tracking, trackPolar, polarRelative } = controller.getState().snap;
     return { grid, objects, guides, threshold, angles: [...angles], tracking: tracking !== false, trackPolar: !!trackPolar, polarRelative: !!polarRelative };
@@ -13453,6 +14349,8 @@ function createVectorCommands(controller, options = {}) {
     ...frameCommands(),
     ...connectorCommands(),
     ...trackingCommands(),
+    ...shadingCommands(),
+    ...traceCommands(),
     {
       ...base,
       id: `${prefix}setCorners`,
@@ -14426,6 +15324,7 @@ export {
   VECTOR_MAX_CONSTRAINTS,
   VECTOR_MAX_TRACKING_POINTS,
   VECTOR_MERGE_MODES,
+  VECTOR_MESH_MAX,
   VECTOR_OVERLAY_THEME,
   VECTOR_PARAGRAPH_STYLE_KEYS,
   VECTOR_PATHFINDER_ACTIONS,
@@ -14449,6 +15348,7 @@ export {
   VECTOR_TOOLS,
   VECTOR_TOOL_GLYPHS,
   VECTOR_TOOL_SHORTCUTS,
+  VECTOR_TRACE_MAX_PIXELS,
   VECTOR_TRANSFORM_HANDLES,
   VECTOR_VERTICAL_RESIZING,
   VECTOR_VERTICAL_RESIZING_LABELS,
@@ -14484,6 +15384,7 @@ export {
   arrowheadPath,
   arrowheadWeight,
   autoConstrainVector,
+  autoVectorFreeformGradient,
   bakeVectorTextGeometry,
   bendSegment,
   bezierToSubpaths,
@@ -14511,6 +15412,7 @@ export {
   createVectorCommands,
   createVectorEffect,
   createVectorFilter,
+  createVectorMeshGradient,
   createVectorMorph,
   cssFontFamily,
   curvatureMoveAnchor,
@@ -14617,11 +15519,14 @@ export {
   isVectorConnector,
   isVectorFilterType,
   isVectorFrame,
+  isVectorFreeformGradient,
   isVectorGradient,
   isVectorLiveBoolean,
   isVectorMaskActive,
   isVectorMaskGroup,
   isVectorMaskType,
+  isVectorMeshGradient,
+  isVectorShadedPaint,
   isVectorTextTarget,
   joinSubpaths,
   knifePath,
@@ -14634,6 +15539,7 @@ export {
   mapWarpMeshPoints as mapVectorMeshPoints,
   mapVectorPaint,
   mapVectorPoints,
+  mapVectorShadedPaint,
   mapVectorSubpaths,
   matrixRotation,
   measureVectorConstraint,
@@ -14649,6 +15555,7 @@ export {
   nearestSegment,
   nearestStrokePosition,
   nearestVectorConnectionSite,
+  nearestVectorShadingPoint,
   needsVectorPaintLayers,
   newVectorStrokeLayer,
   nextVectorConstraintName,
@@ -14679,6 +15586,7 @@ export {
   puckerBloatPaths,
   pullWarpMesh as pullVectorMesh,
   purgeVectorConstraints,
+  quantizeVectorTraceColors,
   recognizeInkShape,
   rectSubpath,
   refineMorphContour,
@@ -14688,6 +15596,7 @@ export {
   removeAnchors,
   removeAnchorsKeepingShape,
   removeRedundantPoints,
+  removeVectorFreeformPoint,
   removeVectorGradientStop,
   removeWarpMeshSplitU as removeVectorMeshSplitU,
   removeWarpMeshSplitV as removeVectorMeshSplitV,
@@ -14709,6 +15618,7 @@ export {
   routeVectorConnector,
   samplePlainStops,
   samplePolyline,
+  sampleVectorFreeform,
   sampleVectorGradient,
   sampleVectorGradientAt,
   sampleVectorPaintDefAt,
@@ -14720,6 +15630,7 @@ export {
   sanitizeVectorGradient,
   sanitizeVectorMask,
   sanitizeVectorResizing,
+  sanitizeVectorShadedPaint,
   sanitizeVectorStrokeSettings,
   sanitizeVectorStrokes,
   sanitizeVectorTextFields,
@@ -14759,10 +15670,12 @@ export {
   toVectorKeyInput,
   toVectorModifiers,
   toVectorPointerInput,
+  traceVectorImage,
   transformVectorEffects,
   transformVectorGradient,
   transformVectorNode,
   transformVectorPaint,
+  transformVectorShadedPaint,
   translateAnchor,
   translateMatrix,
   trimIntervals,
@@ -14827,6 +15740,9 @@ export {
   vectorFrameDocument,
   vectorFrameDrawn,
   vectorFrameRectPath,
+  vectorFreeformField,
+  vectorFreeformLineSegments,
+  vectorFreeformSpreadScale,
   vectorGradientArea,
   vectorGradientAspect,
   vectorGradientBarPosition,
@@ -14863,13 +15779,16 @@ export {
   vectorMaskedGeometry,
   vectorMaskedLocalBounds,
   vectorMaskedShapes,
+  vectorMeshColorAt,
   warpMeshColumns as vectorMeshColumns,
   warpMeshControlBounds as vectorMeshControlBounds,
   warpMeshEditPoints as vectorMeshEditPoints,
   vectorMeshFromOutline,
   warpMeshGridCurves as vectorMeshGridCurves,
+  vectorMeshLines,
   vectorMeshOutline,
   warpMeshParamAt as vectorMeshParamAt,
+  vectorMeshPointAt,
   warpMeshRows as vectorMeshRows,
   vectorNodeBounds,
   vectorNodeEnvelope,
@@ -14898,6 +15817,8 @@ export {
   vectorRepeaterCopies,
   vectorResizeCursor,
   vectorResultStyle,
+  vectorRgbaToCss,
+  vectorShadedSvgDefs,
   vectorShapeBuilderHit,
   vectorShapeBuilderMap,
   vectorShearForSide,
@@ -14935,6 +15856,7 @@ export {
   vectorTextSpans,
   vectorTextStyleAt,
   vectorToolLabel,
+  vectorTraceContours,
   vectorTrackingPaths,
   warpPresetGrid as vectorWarpPresetGrid,
   warpPresetMesh as vectorWarpPresetMesh,