@pixerate/editor 0.140.3 → 0.141.0

package/dist/vector/index.d.cts

@@ -52,3 +52,4 @@ export { createCanvasTextShaper, createMetricTextShaper, createOutlineTextShaper
 export { loadOpenTypeFont, parseOpenTypeFont, type OpenTypeFont } from '../text/opentype.cjs';
 export type { TextFont, TextShaper } from '../text/types.cjs';
 export * from './effect-tools.cjs';
+export * from './playback.cjs';

package/dist/vector/index.d.ts

@@ -52,3 +52,4 @@ export { createCanvasTextShaper, createMetricTextShaper, createOutlineTextShaper
 export { loadOpenTypeFont, parseOpenTypeFont, type OpenTypeFont } from '../text/opentype.js';
 export type { TextFont, TextShaper } from '../text/types.js';
 export * from './effect-tools.js';
+export * from './playback.js';

package/dist/vector/index.js

@@ -38,7 +38,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-2SHFIVC3.js";
+} from "../chunk-DAS7M4RY.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -507,7 +507,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-XGOU44RJ.js";
+} from "../chunk-77SG47WT.js";
 import "../chunk-ORDXMBD4.js";
 import {
   createProvenance
@@ -4169,8 +4169,8 @@ var Page = class {
     const fns = list.slice(1).map((s, k) => `<< /FunctionType 2 /Domain [0 1] /C0 ${rgb(list[k].c)} /C1 ${rgb(s.c)} /N 1 >>`);
     const fn = fns.length === 1 ? fns[0] : `<< /FunctionType 3 /Domain [${n(list[0].t)} ${n(list[list.length - 1].t)}] /Functions [${fns.join(" ")}] /Bounds [${list.slice(1, -1).map((s) => n(s.t)).join(" ")}] /Encode [${fns.map(() => "0 1").join(" ")}] >>`;
     const a = def.attrs;
-    const num = (k, d = 0) => a[k] === void 0 ? d : parseFloat(String(a[k]));
-    const coords = def.type === "linear" ? `/ShadingType 2 /Coords [${n(num("x1"))} ${n(num("y1"))} ${n(num("x2", 1))} ${n(num("y2"))}]` : `/ShadingType 3 /Coords [${n(num("fx", num("cx", 0.5)))} ${n(num("fy", num("cy", 0.5)))} ${n(num("fr"))} ${n(num("cx", 0.5))} ${n(num("cy", 0.5))} ${n(num("r", 0.5))}]`;
+    const num2 = (k, d = 0) => a[k] === void 0 ? d : parseFloat(String(a[k]));
+    const coords = def.type === "linear" ? `/ShadingType 2 /Coords [${n(num2("x1"))} ${n(num2("y1"))} ${n(num2("x2", 1))} ${n(num2("y2"))}]` : `/ShadingType 3 /Coords [${n(num2("fx", num2("cx", 0.5)))} ${n(num2("fy", num2("cy", 0.5)))} ${n(num2("fr"))} ${n(num2("cx", 0.5))} ${n(num2("cy", 0.5))} ${n(num2("r", 0.5))}]`;
     this.writer.shadingDicts.set(`${this.writer.pageIndex}:${name}`, `<< ${coords} /ColorSpace /DeviceRGB /Function ${fn} /Extend [true true] >>`);
     return name;
   }
@@ -4807,28 +4807,28 @@ function gradientOf(it, frame) {
 }
 function effectOf(it, frame, c, id) {
   const v = (k) => lottieValueAt(it[k], frame);
-  const num = (k, d = 0) => v(k)[0] ?? d;
+  const num2 = (k, d = 0) => v(k)[0] ?? d;
   let raw = null;
   switch (it.ty) {
     case "tm":
-      raw = { type: "trim", params: { start: num("s"), end: num("e", 100), offset: num("o"), mode: Number(it.m) === 2 ? "individual" : "simultaneous" } };
+      raw = { type: "trim", params: { start: num2("s"), end: num2("e", 100), offset: num2("o"), mode: Number(it.m) === 2 ? "individual" : "simultaneous" } };
       break;
     case "rd":
-      raw = { type: "roundCorners", params: { radius: num("r") } };
+      raw = { type: "roundCorners", params: { radius: num2("r") } };
       break;
     case "pb":
-      raw = { type: "puckerBloat", params: { amount: num("a") } };
+      raw = { type: "puckerBloat", params: { amount: num2("a") } };
       break;
     case "tw": {
       const [x = c.x, y = c.y] = v("c");
-      raw = { type: "twist", params: { angle: num("a"), center: { x: x - c.x, y: y - c.y } } };
+      raw = { type: "twist", params: { angle: num2("a"), center: { x: x - c.x, y: y - c.y } } };
       break;
     }
     case "zz":
-      raw = { type: "zigzag", params: { size: num("s"), ridges: num("r"), smooth: num("pt", 1) === 2 } };
+      raw = { type: "zigzag", params: { size: num2("s"), ridges: num2("r"), smooth: num2("pt", 1) === 2 } };
       break;
     case "op":
-      raw = { type: "offset", params: { amount: num("a"), join: ["miter", "round", "bevel"][Number(it.lj ?? 1) - 1] ?? "miter", miterLimit: num("ml", 4) || 4 } };
+      raw = { type: "offset", params: { amount: num2("a"), join: ["miter", "round", "bevel"][Number(it.lj ?? 1) - 1] ?? "miter", miterLimit: num2("ml", 4) || 4 } };
       break;
     case "mm":
       raw = { type: "merge", params: { mode: MERGE[Number(it.mm ?? 1) - 1] ?? "merge" } };
@@ -4844,7 +4844,7 @@ function effectOf(it, frame, c, id) {
       const [sx, sy] = at("s", [100, 100]);
       raw = {
         type: "repeater",
-        params: { copies: num("c", 1), offset: num("o"), position: { x: px, y: py }, anchor: { x: ax - c.x, y: ay - c.y }, rotation: at("r", [0])[0], scale: { x: sx, y: sy }, startOpacity: at("so", [100])[0], endOpacity: at("eo", [100])[0], composite: Number(it.m) === 1 ? "above" : "below" }
+        params: { copies: num2("c", 1), offset: num2("o"), position: { x: px, y: py }, anchor: { x: ax - c.x, y: ay - c.y }, rotation: at("r", [0])[0], scale: { x: sx, y: sy }, startOpacity: at("so", [100])[0], endOpacity: at("eo", [100])[0], composite: Number(it.m) === 1 ? "above" : "below" }
       };
       break;
     }
@@ -6456,11 +6456,11 @@ function segsToSubpath(segs, closed, types) {
     const last = anchors.pop();
     if (last.in) anchors[0].in = last.in;
   }
-  const typed = anchors.map((a) => {
+  const typed2 = anchors.map((a) => {
     const type = types.get(`${a.x},${a.y}`);
     return tidy(type ? { ...a, type } : a, !!type);
   });
-  return { anchors: typed, closed };
+  return { anchors: typed2, closed };
 }
 var isZeroSeg = (s) => s.c.every((p) => Math.abs(p[0] - s.c[0][0]) < 1e-9 && Math.abs(p[1] - s.c[0][1]) < 1e-9);
 function mergePair(a, b, tol) {
@@ -8497,10 +8497,10 @@ var VectorEditorController = class _VectorEditorController {
     if (node?.type !== "path") return { ok: false, message: "There is no such path." };
     const g = vectorStrokeWidthGeometry(node);
     if (!g || !(g.unit > 0)) return { ok: false, message: "The path has no visible stroke." };
-    const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
-    const t = num(values.t);
-    const left = num(values.left);
-    const right = num(values.right);
+    const num2 = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+    const t = num2(values.t);
+    const left = num2(values.left);
+    const right = num2(values.right);
     const scale = (w) => w === void 0 ? void 0 : Math.max(0, w) / g.unit;
     const profile = sanitizeWidthProfile(node.strokeWidthProfile);
     let points;
@@ -10768,18 +10768,18 @@ var VectorEditorController = class _VectorEditorController {
     const sp = pen && node ? node.subpaths[pen.subpath] : void 0;
     if (!pen || !node || !sp?.anchors.length) return { ok: false, message: "Start a path with the pen first: typed entry places its next point." };
     const last = getAnchorWorld(this.doc, { nodeId: pen.nodeId, subpath: pen.subpath, index: sp.anchors.length - 1 });
-    const num = "(-?(?:\\d+\\.?\\d*|\\.\\d+))";
+    const num2 = "(-?(?:\\d+\\.?\\d*|\\.\\d+))";
     const t = text.replace(/\s+/g, "");
     let target = null;
     let m;
-    if (m = t.match(new RegExp(`^@${num},${num}$`))) target = { x: last.x + parseFloat(m[1]), y: last.y + parseFloat(m[2]) };
-    else if (m = t.match(new RegExp(`^${num},${num}$`))) target = { x: parseFloat(m[1]), y: parseFloat(m[2]) };
-    else if (m = t.match(new RegExp(`^${num}<${num}$`))) {
+    if (m = t.match(new RegExp(`^@${num2},${num2}$`))) target = { x: last.x + parseFloat(m[1]), y: last.y + parseFloat(m[2]) };
+    else if (m = t.match(new RegExp(`^${num2},${num2}$`))) target = { x: parseFloat(m[1]), y: parseFloat(m[2]) };
+    else if (m = t.match(new RegExp(`^${num2}<${num2}$`))) {
       const base = this.snap.polarRelative ? (this.penAngles().angles?.[0] ?? this.snap.angles[0] ?? 0) - (this.snap.angles[0] ?? 0) : 0;
       const dir = vectorAngleDirection(parseFloat(m[2]) + base);
       const len2 = parseFloat(m[1]);
       target = { x: last.x + dir.x * len2, y: last.y + dir.y * len2 };
-    } else if (m = t.match(new RegExp(`^${num}$`))) {
+    } else if (m = t.match(new RegExp(`^${num2}$`))) {
       const toward = this.pointer;
       const d = toward ? Math.hypot(toward.x - last.x, toward.y - last.y) : 0;
       if (!toward || d < 1e-9) return { ok: false, message: "Point the pointer the way the distance should go (or type length<angle)." };
@@ -14974,6 +14974,120 @@ function pencilPressureProfile(points, pressures) {
   return pressureWidthProfile(s.map((d, i) => ({ t: d / total, pressure: pressures[i] })));
 }
 
+// src/vector/playback.ts
+var VECTOR_PLAYBACK_KIND = "vector";
+function createVectorPlaybackLocator(controller) {
+  return (ref) => {
+    if (ref.kind !== VECTOR_PLAYBACK_KIND && ref.kind !== "item") return null;
+    const node = controller.getNode(ref.id);
+    if (!node) return null;
+    const b = vectorNodeBounds(node, vectorParentMatrix(controller.getState().document.nodes, ref.id) ?? IDENTITY_MATRIX);
+    if (!b) return null;
+    const w = Math.max(b.width, 4);
+    const h = Math.max(b.height, 4);
+    return { x: b.x - (w - b.width) / 2, y: b.y - (h - b.height) / 2, width: w, height: h };
+  };
+}
+var num = (v) => typeof v === "number" && Number.isFinite(v);
+var dragOut = (from, to) => [
+  { type: "move", to: from },
+  { type: "press" },
+  { type: "drag", to },
+  { type: "release" }
+];
+var click = (at) => [{ type: "move", to: at }, { type: "press" }, { type: "release" }];
+var typed = (text) => {
+  if (typeof text !== "string" || !text.trim()) return [];
+  const line2 = text.replace(/\s+/g, " ").trim();
+  return [{ type: "type", text: line2.length > 60 ? `${line2.slice(0, 59)}\u2026` : line2 }];
+};
+function pathPoints(d, max = 24) {
+  let anchors;
+  try {
+    anchors = bezierToSubpaths(d).flatMap((s) => s.anchors.map((a) => ({ x: a.x, y: a.y })));
+  } catch {
+    return [];
+  }
+  if (anchors.length <= max) return anchors;
+  const step = (anchors.length - 1) / (max - 1);
+  return Array.from({ length: max }, (_, i) => anchors[Math.round(i * step)]);
+}
+function trace(points) {
+  if (!points.length) return [];
+  const [first, ...rest] = points;
+  const total = rest.reduce((sum, p, i) => sum + Math.hypot(p.x - (i ? rest[i - 1] : first).x, p.y - (i ? rest[i - 1] : first).y), 0);
+  const ms = (p, i) => {
+    const prev = i ? rest[i - 1] : first;
+    return total > 0 ? Math.max(16, 900 * Math.hypot(p.x - prev.x, p.y - prev.y) / total) : 16;
+  };
+  return [{ type: "move", to: first }, { type: "press" }, ...rest.map((p, i) => ({ type: "drag", to: p, ms: ms(p, i) })), { type: "release" }];
+}
+var PLANS = {
+  addShape: (p) => {
+    if (![p.x, p.y, p.width, p.height].every(num)) return null;
+    return dragOut({ x: p.x, y: p.y }, { x: p.x + p.width, y: p.y + p.height });
+  },
+  addPath: (p) => typeof p.d === "string" ? trace(pathPoints(p.d)) : null,
+  addText: (p) => {
+    if (typeof p.path === "string") {
+      const points = pathPoints(p.path, 2);
+      return points.length ? [...click(points[0]), ...typed(p.text)] : null;
+    }
+    const x = num(p.x) ? p.x : 0;
+    const y = num(p.y) ? p.y : 0;
+    const start = num(p.width) && num(p.height) ? dragOut({ x, y }, { x: x + p.width, y: y + p.height }) : click({ x, y });
+    return [...start, ...typed(p.text)];
+  },
+  placeSymbol: (p, controller) => {
+    const doc = controller.getState().document;
+    const t = Array.isArray(p.transform) && p.transform.length === 6 ? p.transform : null;
+    const at = t ? { x: t[4], y: t[5] } : { x: num(p.x) ? p.x : doc.width / 2, y: num(p.y) ? p.y : doc.height / 2 };
+    return click(at);
+  },
+  setTextStyle: (p, controller) => {
+    const node = controller.getNode(p.id);
+    if (node?.type !== "text") return null;
+    const rect = createVectorPlaybackLocator(controller)({ kind: VECTOR_PLAYBACK_KIND, id: p.id });
+    if (!rect) return null;
+    const length = Math.max(1, node.text.length);
+    const start = Math.min(length, Math.max(0, num(p.start) ? p.start : 0));
+    const end = Math.min(length, Math.max(start, num(p.end) ? p.end : length));
+    const y = rect.y + rect.height / 2;
+    return [
+      { type: "focus", rect },
+      ...dragOut({ x: rect.x + rect.width * start / length, y }, { x: rect.x + rect.width * end / length, y })
+    ];
+  },
+  setMeshPoint: (p, controller) => {
+    const shading = controller.getShading(p.id);
+    const point = shading?.points[p.index];
+    if (!point) return null;
+    return num(p.x) && num(p.y) ? dragOut(point, { x: p.x, y: p.y }) : click(point);
+  }
+};
+var placeImage = (p, controller) => {
+  const doc = controller.getState().document;
+  const x = num(p.x) ? p.x : 0;
+  const y = num(p.y) ? p.y : 0;
+  const w = num(p.width) ? p.width : doc.width - x;
+  return dragOut({ x, y }, { x: x + w, y: y + w });
+};
+function withVectorPlayback(controller, prefix, commands) {
+  return commands.map((spec) => {
+    if (!spec.id.startsWith(prefix)) return spec;
+    const name = spec.id.slice(prefix.length);
+    const props = spec.params?.properties ?? {};
+    const planner = PLANS[name] ?? (/Image$/.test(name) && "x" in props && "width" in props ? placeImage : void 0);
+    const surface = spec.playbackSurface ?? spec.scope ?? "vector";
+    if (!planner || spec.plan) return { ...spec, playbackSurface: surface };
+    return {
+      ...spec,
+      playbackSurface: surface,
+      plan: (_ctx, params) => planner(params ?? {}, controller)
+    };
+  });
+}
+
 // src/vector/commands.ts
 var EFFECT_PARAMS_DESCRIPTION = "Effect parameters (missing ones keep their value or default). trim: start, end (percent), offset (degrees), mode simultaneous|individual. roundCorners: radius. puckerBloat: amount (\u2212100\u2026100). twist: angle, center {x, y} (offset from the middle). zigzag: size, ridges, smooth. wiggle: size, detail, smooth, speed, correlation, phase, seed, time (seconds). offset: amount, join miter|round|bevel, miterLimit, copies, copyOffset. merge: mode merge|add|subtract|intersect|exclude. repeater: copies (fractions fade the last), offset, position {x, y}, anchor {x, y} (offset from the middle), rotation, scale {x, y} (percent), startOpacity, endOpacity (percent), composite below|above. contour: direction inside|outside|center, steps, offset, fillColor / strokeColor (end colours, null keeps the colour), acceleration (\u2212100\u2026100), join. blockShadow: angle (degrees, 0 right, 90 down), distance, color (null: the shape fill colour), opacity, endOpacity (percent; lower than opacity fades it into a long shadow). extrude: mode parallel|perspective, angle (degrees) and depth (units) for parallel, vanishingPoint {x, y} (offset from the middle) and toward (percent of the way there) for perspective, color (null: the shape fill colour), lightAngle (degrees the light comes from, 0 right, -90 above), shading (percent). bevel: width (units), lightAngle (degrees), shading (percent), color (null: the shape fill colour). envelope: style (a warp preset: arc|arcLower|arcUpper|arch|bulge|shellLower|shellUpper|flag|wave|fish|rise|fisheye|inflate|squeeze|twist, or mesh), bend, horizontal, vertical (percent, \u2212100\u2026100), orientation horizontal|vertical, rows, columns, mesh { us, vs, points } (node space; prefer vector.envelope).";
 var fail = (message) => {
@@ -17275,7 +17389,7 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
-  return [
+  return withVectorPlayback(controller, prefix, [
     {
       ...base,
       id: `${prefix}list`,
@@ -18186,7 +18300,7 @@ function createVectorCommands(controller, options = {}) {
         return { nodes: controller.getState().document.nodes.length, selection: controller.getState().selection };
       }
     }
-  ];
+  ]);
 }
 
 // src/vector/generate.ts
@@ -18680,6 +18794,7 @@ export {
   VECTOR_PATH_TEXT_BASELINES,
   VECTOR_PENCIL_STRING_PX,
   VECTOR_PERSPECTIVE_PLANES,
+  VECTOR_PLAYBACK_KIND,
   VECTOR_PRESSURE_NOMINAL,
   VECTOR_ROTATE_HANDLE_OFFSET,
   VECTOR_SPATIAL_MIN,
@@ -18768,6 +18883,7 @@ export {
   createVectorGenerationToolProvider,
   createVectorMeshGradient,
   createVectorMorph,
+  createVectorPlaybackLocator,
   cssFontFamily,
   curvatureMoveAnchor,
   cutSubpathAt,
@@ -19283,6 +19399,7 @@ export {
   withVectorAnchorIds,
   withVectorDocumentAnchorIds,
   withVectorFills,
+  withVectorPlayback,
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths

package/dist/vector/playback.d.cts

@@ -0,0 +1,13 @@
+import type { CommandSpec } from '../commands/registry.cjs';
+import type { PlaybackRect, PlaybackRef } from '../tools/playback.cjs';
+import type { VectorEditorController } from './controller.cjs';
+/** The playback kind of a vector node (`{ kind: 'vector', id }`, as in `data-vector-id`). */
+export declare const VECTOR_PLAYBACK_KIND = "vector";
+/** Finds `{ kind: 'vector', id }` (a node's document-space bounds) for agent playback. */
+export declare function createVectorPlaybackLocator(controller: Pick<VectorEditorController, 'getState' | 'getNode'>): (ref: PlaybackRef) => PlaybackRect | null;
+/**
+ * Adds agent playback plans to vector commands whose effect has a place but no ids yet (shapes,
+ * paths, text, symbols, stylized images) and to edits of a part of a node (a text range, a mesh
+ * point). Other commands play from the ids in their params.
+ */
+export declare function withVectorPlayback(controller: VectorEditorController, prefix: string, commands: CommandSpec[]): CommandSpec[];

package/dist/vector/playback.d.ts

@@ -0,0 +1,13 @@
+import type { CommandSpec } from '../commands/registry.js';
+import type { PlaybackRect, PlaybackRef } from '../tools/playback.js';
+import type { VectorEditorController } from './controller.js';
+/** The playback kind of a vector node (`{ kind: 'vector', id }`, as in `data-vector-id`). */
+export declare const VECTOR_PLAYBACK_KIND = "vector";
+/** Finds `{ kind: 'vector', id }` (a node's document-space bounds) for agent playback. */
+export declare function createVectorPlaybackLocator(controller: Pick<VectorEditorController, 'getState' | 'getNode'>): (ref: PlaybackRef) => PlaybackRect | null;
+/**
+ * Adds agent playback plans to vector commands whose effect has a place but no ids yet (shapes,
+ * paths, text, symbols, stylized images) and to edits of a part of a node (a text range, a mesh
+ * point). Other commands play from the ids in their params.
+ */
+export declare function withVectorPlayback(controller: VectorEditorController, prefix: string, commands: CommandSpec[]): CommandSpec[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.140.3",
+  "version": "0.141.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-agent-tools/SKILL.md

@@ -61,6 +61,19 @@ editor's, or (in discovery mode) only `list_toolsets`, `search_tools`, `enable_t
 6. **Undo your own mistakes** with the domain's `undo_*` tool or the `history.undo` command, not
    by hand-reverting with more edits.
 
+## Playback
+
+The host may act your calls out on screen (agent playback): your cursor glides to what a call
+names, presses, drags or types, and the change lands as one undo step. Results are the same with
+or without it, and calls simply take a little longer while it plays.
+
+- Do not add waits or poll for the animation; each call returns once its change is applied.
+- Name your targets with the ids read tools return (`ids`, `nodeId`, `layerId`, a range). They are
+  also what the cursor heads for, so the user can follow along.
+- A batch (`run_commands`) plays its steps' moves first, then applies once as one undo step.
+- If you connect over MCP, your client's name labels your cursor; several agents get separate
+  cursors.
+
 ## Errors
 
 A failed call comes back as an `isError` result whose text says what was wrong and how to fix

package/skills/pixerate-canvas/SKILL.md

@@ -271,6 +271,9 @@ effects provider (for example Flair); without one the read tools say so and the
   `get_editor_state` again, not guess.
 - `canvas_add_node` with `nearNodeId` also adds an edge from that node. Pass an explicit
   `position` (and no `nearNodeId`) for a free-standing design element.
+- With agent playback on, the cursor clicks where `canvas_add_node` will place the node, drags
+  `canvas_connect` from source to target, and rings the nodes a layout or arrange command moved.
+  Nothing about the calls changes: still read ids with `get_editor_state` and pass them back.
 - `canvas_update_node` changes `data` only. Move nodes with layout, align or distribute commands,
   or by the host's own means; do not expect `position` inside `data` to move anything.
 - Align needs at least two nodes and distribute at least three; locked nodes never move. Shape

package/skills/pixerate-image-editor/SKILL.md

@@ -415,8 +415,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 
 ## Pitfalls
 
-- Effects need a shape: on an empty layer they draw nothing. They cannot go on adjustment
-  layers. A clipped layer's effects stay inside the layer it is clipped to.
+- Agent playback (if on) opens each write's panel, then traces `points`, drags boxes or visits the layers and sliders named; results are unchanged.
+- Effects need a shape: on an empty layer they draw nothing. They cannot go on adjustment layers. A clipped layer's effects stay inside the layer it is clipped to.
 - `bevel-emboss` has no `blend` / `opacity`: it uses `highlightBlend`, `highlightOpacity`,
   `shadowBlend` and `shadowOpacity`. Inner shadows and inner glows use `choke`, not `spread`.
 - Glows paint a colour or a gradient, never a pattern; strokes take all three. Pattern effects

package/skills/pixerate-vector/SKILL.md

@@ -459,6 +459,11 @@ the animation editor.
 
 The most common ones are below. Read [references/pitfalls.md](references/pitfalls.md) before working with connectors, frames, masks, filters, text, symbols, constraints, blends, gradient meshes or live corners.
 
+- With agent playback on, `vector.addShape` is dragged out from (x, y) to (x + width, y + height),
+  `vector.addPath` is traced through its anchors, and text is clicked in and typed out. So give
+  shapes their real place and size in the first call rather than adding them at 0, 0 and moving
+  them after: the user watches the cursor go where the shape lands. Commands with `ids` visit those
+  nodes; nothing else about the calls changes.
 - `d` and anchor positions are in the node's own space; `bounds` are in document space. For
   rotated nodes (`rotation` not 0), `vector.moveAnchor` and `vector.bendSegment` take document
   coordinates, so compute them from the drawn position, not from `d`.

package/dist/chunk-BTZS3KZY.js

@@ -1,221 +0,0 @@
-// src/canvas/layout.ts
-import dagre from "@dagrejs/dagre";
-var DEFAULT_NODE_WIDTH = 200;
-var DEFAULT_NODE_HEIGHT = 60;
-var DEFAULT_PLACEMENT_GAP = 48;
-function getCenteredNodePosition(width = 0, height = 0, screenToFlowPosition, screenDimensions) {
-  const rect = screenDimensions ?? (typeof document !== "undefined" ? { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight } : { width: 1920, height: 1080 });
-  const flowPos = screenToFlowPosition({ x: rect.width / 2, y: rect.height / 2 });
-  return {
-    x: flowPos.x - width / 2,
-    y: flowPos.y - height / 2
-  };
-}
-function centerNodes(nodes, screenToFlowPosition, getNodesBounds, screenDimensions) {
-  if (nodes.length === 0) {
-    return [];
-  }
-  const bounds = getNodesBounds(nodes);
-  const boundingBoxOrigin = { x: bounds.x, y: bounds.y };
-  const centeredPosition = getCenteredNodePosition(
-    bounds.width,
-    bounds.height,
-    screenToFlowPosition,
-    screenDimensions
-  );
-  const deltaX = centeredPosition.x - boundingBoxOrigin.x;
-  const deltaY = centeredPosition.y - boundingBoxOrigin.y;
-  return nodes.map((node) => ({
-    ...node,
-    position: {
-      x: node.position.x + deltaX,
-      y: node.position.y + deltaY
-    }
-  }));
-}
-function getLayoutedNodes(nodes, edges, getNodesBounds, options = {}) {
-  if (nodes.length === 0) return [];
-  const {
-    direction = "LR",
-    ranksep = 100,
-    nodesep = 25,
-    defaultNodeWidth = DEFAULT_NODE_WIDTH,
-    defaultNodeHeight = DEFAULT_NODE_HEIGHT
-  } = options;
-  const dagreGraph = new dagre.graphlib.Graph();
-  dagreGraph.setDefaultEdgeLabel(() => ({}));
-  dagreGraph.setGraph({ rankdir: direction, ranksep, nodesep });
-  const nodeIds = new Set(nodes.map((node) => node.id));
-  nodes.forEach((node) => {
-    const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
-    const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
-    dagreGraph.setNode(node.id, { width: nodeWidth, height: nodeHeight });
-  });
-  edges.forEach((edge) => {
-    if (nodeIds.has(edge.source) && nodeIds.has(edge.target)) {
-      dagreGraph.setEdge(edge.source, edge.target);
-    }
-  });
-  dagre.layout(dagreGraph);
-  return nodes.map((node) => {
-    const nodeWithPosition = dagreGraph.node(node.id);
-    const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
-    const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
-    return {
-      ...node,
-      position: {
-        x: nodeWithPosition.x - nodeWidth / 2,
-        y: nodeWithPosition.y - nodeHeight / 2
-      }
-    };
-  });
-}
-function estimateNodeSize(node, defaultWidth = DEFAULT_NODE_WIDTH, defaultHeight = DEFAULT_NODE_HEIGHT) {
-  const label = String(node.data?.label ?? node.data?.title ?? node.id ?? "");
-  const lines = label.split(/\n|<br\s*\/?>/);
-  const longest = Math.max(...lines.map((l) => l.replace(/<[^>]+>/g, "").length), 1);
-  const width = Math.min(480, Math.max(defaultWidth, longest * 8 + 48));
-  const height = Math.max(defaultHeight, lines.length * 20 + 24);
-  return { width, height };
-}
-function boundsOf(rects) {
-  if (!rects.length) return null;
-  const minX = Math.min(...rects.map((r) => r.x));
-  const minY = Math.min(...rects.map((r) => r.y));
-  const maxX = Math.max(...rects.map((r) => r.x + r.width));
-  const maxY = Math.max(...rects.map((r) => r.y + r.height));
-  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
-}
-function centre(r) {
-  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
-}
-function overlaps(a, b, pad = 16) {
-  return a.x < b.x + b.width + pad && a.x + a.width + pad > b.x && a.y < b.y + b.height + pad && a.y + a.height + pad > b.y;
-}
-function flowSide(direction = "LR") {
-  switch (direction) {
-    case "LR":
-      return "right";
-    case "RL":
-      return "left";
-    case "BT":
-      return "above";
-    case "TB":
-    default:
-      return "below";
-  }
-}
-function ensureLayout(nodes, edges, options = {}) {
-  if (nodes.length === 0) return [];
-  const stored = options.storedPositions ?? {};
-  const missing = nodes.filter((n) => !stored[n.id]);
-  if (missing.length === 0) {
-    return nodes.map((n) => ({
-      ...n,
-      position: { ...stored[n.id] }
-    }));
-  }
-  const autoLayouted = getLayoutedNodes(nodes, edges, void 0, options);
-  const autoMap = new Map(
-    autoLayouted.map((n) => [n.id, n.position])
-  );
-  const both = nodes.filter((n) => stored[n.id] && autoMap.has(n.id));
-  if (both.length === 0) {
-    return autoLayouted;
-  }
-  let dx = 0;
-  let dy = 0;
-  for (const n of both) {
-    const s = stored[n.id];
-    const a = autoMap.get(n.id);
-    dx += s.x - a.x;
-    dy += s.y - a.y;
-  }
-  dx /= both.length;
-  dy /= both.length;
-  return nodes.map((node) => {
-    if (stored[node.id]) {
-      return {
-        ...node,
-        position: { ...stored[node.id] }
-      };
-    }
-    const autoPos = autoMap.get(node.id) ?? { x: 0, y: 0 };
-    return {
-      ...node,
-      position: {
-        x: Math.round(autoPos.x + dx),
-        y: Math.round(autoPos.y + dy)
-      }
-    };
-  });
-}
-function placeBeside(rects, size, side, nearNodeId, options = {}) {
-  const {
-    gap = DEFAULT_PLACEMENT_GAP,
-    ignore = [],
-    maxAttempts = 32
-  } = options;
-  const skip = new Set([nearNodeId, ...ignore].filter(Boolean));
-  const obstacles = Object.entries(rects).filter(([id]) => !skip.has(id)).map(([, r]) => r);
-  const anchor = nearNodeId && rects[nearNodeId] || boundsOf(Object.values(rects)) || { x: 0, y: 0, width: 0, height: 0 };
-  const anchorCenter = centre(anchor);
-  let baseX;
-  let baseY;
-  switch (side) {
-    case "right":
-      baseX = anchor.x + anchor.width + gap;
-      baseY = anchorCenter.y - size.height / 2;
-      break;
-    case "left":
-      baseX = anchor.x - gap - size.width;
-      baseY = anchorCenter.y - size.height / 2;
-      break;
-    case "above":
-      baseX = anchorCenter.x - size.width / 2;
-      baseY = anchor.y - gap - size.height;
-      break;
-    case "below":
-    default:
-      baseX = anchorCenter.x - size.width / 2;
-      baseY = anchor.y + anchor.height + gap;
-      break;
-  }
-  const isHorizontal = side === "right" || side === "left";
-  const step = (isHorizontal ? size.height : size.width) + 20;
-  for (let i = 0; i < maxAttempts; i++) {
-    const offset = i === 0 ? 0 : Math.ceil(i / 2) * step * (i % 2 === 1 ? 1 : -1);
-    const candidateBox = {
-      x: isHorizontal ? baseX : baseX + offset,
-      y: isHorizontal ? baseY + offset : baseY,
-      width: size.width,
-      height: size.height
-    };
-    if (!obstacles.some((obstacle) => overlaps(candidateBox, obstacle, 8))) {
-      return {
-        x: Math.round(candidateBox.x),
-        y: Math.round(candidateBox.y)
-      };
-    }
-  }
-  return {
-    x: Math.round(baseX),
-    y: Math.round(baseY)
-  };
-}
-
-export {
-  DEFAULT_NODE_WIDTH,
-  DEFAULT_NODE_HEIGHT,
-  DEFAULT_PLACEMENT_GAP,
-  getCenteredNodePosition,
-  centerNodes,
-  getLayoutedNodes,
-  estimateNodeSize,
-  boundsOf,
-  centre,
-  overlaps,
-  flowSide,
-  ensureLayout,
-  placeBeside
-};