From c9337a564ba58b0349719995eac8d67009a0eeeb Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Wed, 20 May 2026 15:51:41 -0400
Subject: [PATCH 1/6] removed animate options from move

---
 packages/graph/src/base/types.ts              |  5 ++-
 packages/graph/src/base/useGraphCRUD.ts       |  9 ++---
 packages/graph/src/schematics/edge.ts         | 33 ++++++++++---------
 .../src/abstract-syntax-trees/MainView.vue    |  4 +--
 .../useTreeGraphPositioner.ts                 |  8 ++++-
 packages/shapes/src/animation/autoAnimate.ts  |  3 ++
 6 files changed, 39 insertions(+), 23 deletions(-)

diff --git a/packages/graph/src/base/types.ts b/packages/graph/src/base/types.ts
index 784d7266..997c022e 100644
--- a/packages/graph/src/base/types.ts
+++ b/packages/graph/src/base/types.ts
@@ -105,8 +105,11 @@ export const MOVE_NODE_OPTIONS_DEFAULTS: MoveNodeOptions = {
   broadcast: true,
 };
 
-export const BULK_MOVE_NODE_OPTIONS_DEFAULTS: MoveNodeOptions = {
+export type BulkMoveNodeOptions = BroadcastOption & AnimateOption;
+
+export const BULK_MOVE_NODE_OPTIONS_DEFAULTS: BulkMoveNodeOptions = {
   broadcast: true,
+  animate: false,
 };
 
 export type EditEdgeLabelOptions = BroadcastOption & HistoryOption;
diff --git a/packages/graph/src/base/useGraphCRUD.ts b/packages/graph/src/base/useGraphCRUD.ts
index 21ef2db7..48952ad7 100644
--- a/packages/graph/src/base/useGraphCRUD.ts
+++ b/packages/graph/src/base/useGraphCRUD.ts
@@ -12,6 +12,7 @@ import { getConnectedEdges } from '../helpers';
 import { nodeLetterLabelGetter } from '../labels';
 import type { GraphSettings } from '../settings';
 import type { GEdge, GNode } from '../types';
+import { AnimationKeyframe } from './../../../shapes/src/animation/interpolation/types';
 import type { GraphAnimations } from './animations';
 import {
   ADD_EDGE_DEFAULTS,
@@ -299,15 +300,15 @@ export const useGraphCRUD = ({
       ...options,
     };
 
-    const finalizeFrame = autoAnimate.captureFrame(() =>
-      draw(getCtx(magicCanvas.canvas)),
-    );
+    const animate = fullOptions.animate
+      ? autoAnimate.captureFrame(() => draw(getCtx(magicCanvas.canvas)))
+      : null;
 
     for (const { nodeId, coords } of nodeMovements) {
       moveNode(nodeId, coords, fullOptions);
     }
 
-    finalizeFrame();
+    animate?.();
   };
 
   const editEdgeLabel = (
diff --git a/packages/graph/src/schematics/edge.ts b/packages/graph/src/schematics/edge.ts
index 42f252c3..fcc3edb3 100644
--- a/packages/graph/src/schematics/edge.ts
+++ b/packages/graph/src/schematics/edge.ts
@@ -22,19 +22,19 @@ export const getEdgeSchematic = (
 ): Omit<SchemaItem, 'priority'> | undefined => {
   const { displayEdgeLabels, isGraphDirected } = graph.settings.value;
 
-  const [from, to] = getConnectedNodes(edge.id, graph);
-  const edgesAlongPath = getEdgesAlongPath(from.id, to.id, graph);
+  const [fromNode, toNode] = getConnectedNodes(edge.id, graph);
+  const edgesAlongPath = getEdgesAlongPath(fromNode.id, toNode.id, graph);
 
   const multipleEdgesInPath = edgesAlongPath.length > 1;
-  const isSelfDirected = to === from;
+  const isSelfDirected = toNode.id === fromNode.id;
 
-  const fromNodeBorderWidth = graph.getTheme('nodeBorderWidth', from);
-  const toNodeBorderWidth = graph.getTheme('nodeBorderWidth', to);
+  const fromNodeBorderWidth = graph.getTheme('nodeBorderWidth', fromNode);
+  const toNodeBorderWidth = graph.getTheme('nodeBorderWidth', toNode);
 
-  const fromNodeSize = graph.getTheme('nodeSize', from);
-  const toNodeSize = graph.getTheme('nodeSize', to);
+  const fromNodeSize = graph.getTheme('nodeSize', fromNode);
+  const toNodeSize = graph.getTheme('nodeSize', toNode);
 
-  const angle = Math.atan2(to.y - from.y, to.x - from.x);
+  const angle = Math.atan2(toNode.y - fromNode.y, toNode.x - fromNode.x);
 
   const arrowHeadSpacingAwayFromNode =
     toNodeBorderWidth / 2 + WHITESPACE_BETWEEN_ARROW_TIP_AND_NODE;
@@ -43,10 +43,10 @@ export const getEdgeSchematic = (
     y: (toNodeSize + arrowHeadSpacingAwayFromNode) * Math.sin(angle),
   };
 
-  const edgeStart = { x: from.x, y: from.y };
+  const edgeStart = { x: fromNode.x, y: fromNode.y };
   const edgeEnd = {
-    x: to.x - (isGraphDirected ? arrowDrawOffset.x : 0),
-    y: to.y - (isGraphDirected ? arrowDrawOffset.y : 0),
+    x: toNode.x - (isGraphDirected ? arrowDrawOffset.x : 0),
+    y: toNode.y - (isGraphDirected ? arrowDrawOffset.y : 0),
   };
 
   const edgeWidth = graph.getTheme('edgeWidth', edge);
@@ -74,10 +74,13 @@ export const getEdgeSchematic = (
      *  from causing angle issues when no other edges are present
      */
     graph.edges.value
-      .filter((e) => (e.from === from.id || e.to === to.id) && e.from !== e.to)
+      .filter(
+        (e) =>
+          (e.from === fromNode.id || e.to === toNode.id) && e.from !== e.to,
+      )
       .map((e) => {
         const [fromNode, toNode] = getConnectedNodes(e.id, graph);
-        return from.id === fromNode.id ? toNode : fromNode;
+        return fromNode.id === fromNode.id ? toNode : fromNode;
       })
       .filter(
         (point, index, self) =>
@@ -117,7 +120,7 @@ export const getEdgeSchematic = (
     const shape = graph.shapes.uturn({
       id: edge.id,
       spacing: edgeWidth * 1.2,
-      at: { x: from.x, y: from.y },
+      at: { x: fromNode.x, y: fromNode.y },
       upDistance,
       downDistance,
       rotation: largestAngularSpace,
@@ -136,7 +139,7 @@ export const getEdgeSchematic = (
   const sumOfToAndFromNodeSize =
     fromNodeSize + fromNodeBorderWidth / 2 + toNodeSize + toNodeBorderWidth / 2;
   const distanceSquaredBetweenNodes =
-    (from.x - to.x) ** 2 + (from.y - to.y) ** 2;
+    (fromNode.x - toNode.x) ** 2 + (fromNode.y - toNode.y) ** 2;
   const areNodesTouching =
     sumOfToAndFromNodeSize ** 2 > distanceSquaredBetweenNodes;
 
diff --git a/packages/products/src/abstract-syntax-trees/MainView.vue b/packages/products/src/abstract-syntax-trees/MainView.vue
index 98438e0b..39ae2cba 100644
--- a/packages/products/src/abstract-syntax-trees/MainView.vue
+++ b/packages/products/src/abstract-syntax-trees/MainView.vue
@@ -99,9 +99,9 @@
 <template>
   <GraphProduct v-bind="graphWithCanvas">
     <template #top-center>
-      <GButton @click="shapeGraph(graphNodesAndEdges.rootNode)">
+      <!-- <GButton @click="shapeGraph(graphNodesAndEdges.rootNode)">
         Shape
-      </GButton>
+      </GButton> -->
     </template>
     <template #center-left>
       <CodeEditor v-model="code" />
diff --git a/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts b/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
index 97fc4e78..7816674c 100644
--- a/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
+++ b/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
@@ -31,12 +31,18 @@ export type UseTreeGraphPositionerOptions = {
    * @default (rootNode) => ({ x: rootNode.x, y: rootNode.y })
    */
   rootNodeCoordinates: Coordinate | ((rootNode: GNode) => Coordinate);
+  /**
+   * if `true`, nodes and edges animate into place
+   * @default false
+   */
+  animate: boolean;
 };
 
 export const TREE_FORMATION_OPTIONS_DEFAULTS = {
   xOffset: 250,
   yOffset: 200,
   shape: 'standard',
+  animate: false,
   rootNodeCoordinates: (rootNode) => ({ x: rootNode.x, y: rootNode.y }),
 } as const satisfies UseTreeGraphPositionerOptions;
 
@@ -80,7 +86,7 @@ export const useTreeGraphPositioner = (
     if (!newPositions) return;
 
     reshapingActive.value = true;
-    await graph.bulkMoveNode(newPositions);
+    await graph.bulkMoveNode(newPositions, { animate: treeOptions.animate });
     reshapingActive.value = false;
   };
 
diff --git a/packages/shapes/src/animation/autoAnimate.ts b/packages/shapes/src/animation/autoAnimate.ts
index 0210c14a..6b5f30ff 100644
--- a/packages/shapes/src/animation/autoAnimate.ts
+++ b/packages/shapes/src/animation/autoAnimate.ts
@@ -96,6 +96,9 @@ export const useAutoAnimate = (
      * finalize(); // triggers animation between captured states
      */
     captureFrame: (flushDraw: () => void) => {
+      // clear any stale snapshots left over from previous abandoned frames
+      snapshotMap.clear();
+
       const takeSnapshot = (state: 'before' | 'after') => {
         capturedSchemas = [];
         activelyCapturingSchemas = true;

From 3c96df86ced5ac3ee4c39809eb6fc2d934eb1800 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Wed, 20 May 2026 16:07:15 -0400
Subject: [PATCH 2/6] added animation api to bulk move

---
 packages/graph/src/base/useGraphCRUD.ts            | 3 ++-
 packages/products/src/sandbox/ui/IslandToolbar.vue | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/graph/src/base/useGraphCRUD.ts b/packages/graph/src/base/useGraphCRUD.ts
index 48952ad7..d81a6e72 100644
--- a/packages/graph/src/base/useGraphCRUD.ts
+++ b/packages/graph/src/base/useGraphCRUD.ts
@@ -28,6 +28,7 @@ import {
 import type {
   AddEdgeOptions,
   AddNodeOptions,
+  BulkMoveNodeOptions,
   EditEdgeLabelOptions,
   MoveNodeOptions,
   RemoveEdgeOptions,
@@ -293,7 +294,7 @@ export const useGraphCRUD = ({
 
   const bulkMoveNode = (
     nodeMovements: GNodeMoveInstruction[],
-    options: Partial<MoveNodeOptions> = {},
+    options: Partial<BulkMoveNodeOptions> = {},
   ) => {
     const fullOptions = {
       ...BULK_MOVE_NODE_OPTIONS_DEFAULTS,
diff --git a/packages/products/src/sandbox/ui/IslandToolbar.vue b/packages/products/src/sandbox/ui/IslandToolbar.vue
index 4839a810..0e24f7c3 100644
--- a/packages/products/src/sandbox/ui/IslandToolbar.vue
+++ b/packages/products/src/sandbox/ui/IslandToolbar.vue
@@ -61,7 +61,9 @@
     return canRedo.value;
   });
 
-  const treePositionerControls = useTreeGraphPositionerSync(graph.value);
+  const treePositionerControls = useTreeGraphPositionerSync(graph.value, {
+    animate: true,
+  });
 </script>
 
 <template>

From 2ebfc0e6acde77405e0b0a269ec2c183124cba4f Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Wed, 20 May 2026 16:18:59 -0400
Subject: [PATCH 3/6] export graph position controls

---
 .../shared/graph-tree-positioner/useTreeGraphPositioner.ts    | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts b/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
index 7816674c..408aee92 100644
--- a/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
+++ b/packages/products/src/shared/graph-tree-positioner/useTreeGraphPositioner.ts
@@ -96,3 +96,7 @@ export const useTreeGraphPositioner = (
     options: optionsRef,
   };
 };
+
+export type TreeGraphPositionerControls = ReturnType<
+  typeof useTreeGraphPositioner
+>;

From fc8dfac432a84ceccf1e9ca9dac215f6398567be Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Wed, 20 May 2026 16:21:58 -0400
Subject: [PATCH 4/6] added animation back via options to binary tree

---
 packages/products/src/binary-trees/tree/treeArrayToGraph.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/products/src/binary-trees/tree/treeArrayToGraph.ts b/packages/products/src/binary-trees/tree/treeArrayToGraph.ts
index 0c04df9d..1142d73d 100644
--- a/packages/products/src/binary-trees/tree/treeArrayToGraph.ts
+++ b/packages/products/src/binary-trees/tree/treeArrayToGraph.ts
@@ -103,7 +103,7 @@ export const treeArrayToGraph = (
     })
     .filter(Boolean) as GNodeMoveInstruction[];
 
-  graph.bulkMoveNode(movementObj);
+  graph.bulkMoveNode(movementObj, { animate: true });
 
   for (const edge of newTreeEdges) {
     graph.addEdge(edge, { animate: true });

From c35cb8ec2172c8d7bdbc9a4529d1d3adc88b7373 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Thu, 21 May 2026 11:04:28 -0400
Subject: [PATCH 5/6] ast types

---
 packages/graph/src/base/useGraphCRUD.ts       |  1 +
 .../src/abstract-syntax-trees/MainView.vue    | 58 +++++++++++++------
 packages/utils/src/ctx/index.ts               |  4 +-
 3 files changed, 42 insertions(+), 21 deletions(-)

diff --git a/packages/graph/src/base/useGraphCRUD.ts b/packages/graph/src/base/useGraphCRUD.ts
index d81a6e72..1945edba 100644
--- a/packages/graph/src/base/useGraphCRUD.ts
+++ b/packages/graph/src/base/useGraphCRUD.ts
@@ -168,6 +168,7 @@ export const useGraphCRUD = ({
         focus: false,
         broadcast: false,
         history: false,
+        animate: fullOptions.animate,
       });
       if (!newNode) continue;
       createdNodes.push(newNode);
diff --git a/packages/products/src/abstract-syntax-trees/MainView.vue b/packages/products/src/abstract-syntax-trees/MainView.vue
index 39ae2cba..4369c33b 100644
--- a/packages/products/src/abstract-syntax-trees/MainView.vue
+++ b/packages/products/src/abstract-syntax-trees/MainView.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
   import { GEdge, GNode } from '@magic/graph/types';
+  import { getCtx } from '@magic/utils/ctx';
   import { debounce } from '@magic/utils/debounce';
   import * as ts from 'typescript';
 
@@ -12,27 +13,38 @@
   import CodeEditor from './code-editor/CodeEditor.vue';
   import { AST_GRAPH_SETTINGS } from './settings';
 
+  type ASTNode = ts.Node;
+  type ASTEdge = { fromNode: ts.Node; toNode: ts.Node };
+
   const graphWithCanvas = useGraphWithCanvas(AST_GRAPH_SETTINGS);
 
   /**
    * coverts ts node object into a unique serializable form
    * @example getNodeUniqueId(node) // "example.ts:VariableStatement:0-21"
    */
-  const getNodeUniqueId = (node: ts.Node) => {
+  const getASTNodeId = (node: ts.Node) => {
     const kindName = ts.SyntaxKind[node.kind];
     return `${kindName}:${node.pos}-${node.end}`;
   };
 
+  const getASTEdgeId = ({
+    fromNode,
+    toNode,
+  }: {
+    fromNode: ts.Node;
+    toNode: ts.Node;
+  }) => {
+    const fromNodeId = getASTNodeId(fromNode);
+    const toNodeId = getASTNodeId(toNode);
+    return `[${fromNodeId}]->[${toNodeId}]`;
+  };
+
   const getAllNodesAndEdges = (node: ts.Node) => {
-    const nodeIds: string[] = [];
-    const edges: { from: string; to: string }[] = [];
-    const processNode = (node: ts.Node) => {
-      const parentNodeId = node.parent
-        ? getNodeUniqueId(node.parent)
-        : undefined;
-      const nodeId = getNodeUniqueId(node);
-      if (parentNodeId) edges.push({ from: parentNodeId, to: nodeId });
-      nodeIds.push(nodeId);
+    const nodeIds: ASTNode[] = [];
+    const edges: ASTEdge[] = [];
+    const processNode = (node: ASTNode) => {
+      if (node.parent) edges.push({ fromNode: node.parent, toNode: node });
+      nodeIds.push(node);
       node.forEachChild(processNode);
     };
     processNode(node);
@@ -62,18 +74,19 @@
   const graphNodesAndEdges = computed(() => {
     const { nodes, edges } = astNodesAndEdges.value;
     const graphNodes = nodes.map(
-      (nodeId): GNode => ({
-        id: nodeId,
-        label: nodeId,
+      (astNode): GNode => ({
+        id: getASTNodeId(astNode),
+        label: getASTNodeId(astNode),
         x: 0,
         y: 0,
       }),
     );
 
     const graphEdges = edges.map(
-      (e): GEdge => ({
-        ...e,
-        id: `${e.from}-${e.to}`,
+      (astEdge): GEdge => ({
+        to: getASTNodeId(astEdge.toNode),
+        from: getASTNodeId(astEdge.fromNode),
+        id: getASTEdgeId(astEdge),
         label: '',
       }),
     );
@@ -85,13 +98,20 @@
     };
   });
 
-  const loadAst = () => {
-    graphWithCanvas.graph.load(graphNodesAndEdges.value);
+  const loadAst = async () => {
+    const { graph, canvas } = graphWithCanvas;
+    const draw = () => {
+      const ctx = getCtx(canvas.canvas.value);
+      graph.draw(ctx);
+    };
+    const animate = graph.autoAnimate.captureFrame(draw);
+    graph.load(graphNodesAndEdges.value);
     shapeGraph(graphNodesAndEdges.value.rootNode);
+    animate();
   };
 
   onMounted(loadAst);
-  const debouncedLoadAst = debounce(loadAst, 2000);
+  const debouncedLoadAst = debounce(loadAst, 1000);
 
   watch(code, debouncedLoadAst);
 </script>
diff --git a/packages/utils/src/ctx/index.ts b/packages/utils/src/ctx/index.ts
index 5c416f54..27c8404f 100644
--- a/packages/utils/src/ctx/index.ts
+++ b/packages/utils/src/ctx/index.ts
@@ -1,12 +1,12 @@
 import type { MaybeRef } from 'vue';
 
 /**
- * pulls ctx from a canvas or canvas ref (vue.js), throws if not found
+ * gets `ctx` from a `<canvas />` or canvas ref (vue.js)
  *
  * @returns {CanvasRenderingContext2D}
  * @example const ctx = getCtx(canvasRef);
  * // ctx is defined and ready to use
- * @throws {Error} if canvas or 2d context not found
+ * @throws {Error} if canvas element isn't in the DOM or `canvas.getContext` returns `null`
  */
 export const getCtx = (
   canvasInput: MaybeRef<HTMLCanvasElement | null | undefined>,

From e231bea20a9d7b264676ff7b03a4a81845a00270 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Thu, 21 May 2026 20:16:16 -0400
Subject: [PATCH 6/6] add better comments extension to .vscode

---
 .vscode/extensions.json                                  | 7 ++++++-
 packages/products/src/abstract-syntax-trees/MainView.vue | 2 +-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 9106560f..224442ac 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,3 +1,8 @@
 {
-  "recommendations": ["Vue.volar", "streetsidesoftware.code-spell-checker", "dbaeumer.vscode-eslint"]
+  "recommendations": [
+    "Vue.volar",
+    "streetsidesoftware.code-spell-checker",
+    "dbaeumer.vscode-eslint",
+    "aaron-bond.better-comments"
+  ]
 }
diff --git a/packages/products/src/abstract-syntax-trees/MainView.vue b/packages/products/src/abstract-syntax-trees/MainView.vue
index 4369c33b..18fe0b24 100644
--- a/packages/products/src/abstract-syntax-trees/MainView.vue
+++ b/packages/products/src/abstract-syntax-trees/MainView.vue
@@ -111,7 +111,7 @@
   };
 
   onMounted(loadAst);
-  const debouncedLoadAst = debounce(loadAst, 1000);
+  const debouncedLoadAst = debounce(loadAst, 500);
 
   watch(code, debouncedLoadAst);
 </script>