@hyperframes/studio 0.6.121 → 0.7.0

package/src/components/editor/domEditingDom.ts

@@ -128,18 +128,32 @@ export function findClosestByAttribute(
   }
   return null;
 }
+// ─── Composition source resolution ───────────────────────────────────────────
 
-export function getElementDepth(el: HTMLElement): number {
-  let depth = 0;
-  let current = el.parentElement;
-  while (current) {
-    depth += 1;
-    current = current.parentElement;
-  }
-  return depth;
+// The runtime INLINES subcompositions and strips the source-file linkage from the
+// mounted root (it keeps `data-composition-id` but drops `data-composition-src`/
+// `-file`), so a subcomp element's DOM ancestors no longer say which file it came
+// from. This project-global map (composition-id → source file, built once from
+// index.html's clips — see NLELayout) recovers it. The studio loads one project at a
+// time, so module scope is the right lifetime; it's empty until set, in which case
+// resolution falls back to the historical attribute-only behavior.
+let compositionSourceMap: Map<string, string> = new Map();
+
+export function setCompositionSourceMap(map: Map<string, string>): void {
+  compositionSourceMap = map;
 }
 
-// ─── Composition source resolution ───────────────────────────────────────────
+function sourceFromCompositionId(ownerRoot: HTMLElement | null): string | undefined {
+  if (!ownerRoot || compositionSourceMap.size === 0) return undefined;
+  // The runtime may rename the mounted id to a runtime-unique one, preserving the
+  // authored id on `data-hf-original-composition-id` — prefer that, then the current id.
+  const authored = ownerRoot.getAttribute("data-hf-original-composition-id");
+  const current = ownerRoot.getAttribute("data-composition-id");
+  return (
+    (authored ? compositionSourceMap.get(authored) : undefined) ??
+    (current ? compositionSourceMap.get(current) : undefined)
+  );
+}
 
 export function getSourceFileForElement(
   el: HTMLElement,
@@ -152,6 +166,7 @@ export function getSourceFileForElement(
     sourceHost?.getAttribute("data-composition-src") ??
     ownerRoot?.getAttribute("data-composition-file") ??
     ownerRoot?.getAttribute("data-composition-src") ??
+    sourceFromCompositionId(ownerRoot) ??
     activeCompositionPath ??
     "index.html";
 

package/src/components/editor/manualEditingAvailability.test.ts

@@ -24,11 +24,6 @@ describe("manual editing availability", () => {
     expect(availability.STUDIO_INSPECTOR_PANELS_ENABLED).toBe(true);
   });
 
-  it("enables GSAP drag intercept by default", async () => {
-    const availability = await loadAvailabilityWithEnv({});
-    expect(availability.STUDIO_GSAP_DRAG_INTERCEPT_ENABLED).toBe(true);
-  });
-
   it("keeps color grading off by default", async () => {
     const availability = await loadAvailabilityWithEnv({});
     expect(availability.STUDIO_COLOR_GRADING_ENABLED).toBe(false);
@@ -41,13 +36,6 @@ describe("manual editing availability", () => {
     expect(availability.STUDIO_COLOR_GRADING_ENABLED).toBe(true);
   });
 
-  it("disables GSAP drag intercept when env var is false", async () => {
-    const availability = await loadAvailabilityWithEnv({
-      VITE_STUDIO_ENABLE_GSAP_DRAG_INTERCEPT: "false",
-    });
-    expect(availability.STUDIO_GSAP_DRAG_INTERCEPT_ENABLED).toBe(false);
-  });
-
   it("disables preview selection when the inspector panel flag is explicitly off", async () => {
     const availability = await loadAvailabilityWithEnv({
       VITE_STUDIO_ENABLE_INSPECTOR_PANELS: "0",

package/src/components/editor/manualEditingAvailability.ts

@@ -73,7 +73,7 @@ export const STUDIO_COLOR_GRADING_ENABLED = resolveStudioBooleanEnvFlag(
 export const STUDIO_KEYFRAMES_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_ENABLE_KEYFRAMES", "VITE_STUDIO_KEYFRAMES_ENABLED"],
-  false,
+  true,
 );
 
 export const STUDIO_RAZOR_TOOL_ENABLED = resolveStudioBooleanEnvFlag(
@@ -92,16 +92,6 @@ export const STUDIO_STORYBOARD_ENABLED = resolveStudioBooleanEnvFlag(
   false,
 );
 
-// When disabled (the default), drag/resize/rotate commits always take the CSS
-// persist path instead of being intercepted into GSAP script keyframe
-// mutations. The keyframe intercept rewrites timeline tweens from drag
-// gestures and is opt-in until its recording path is hardened.
-export const STUDIO_GSAP_DRAG_INTERCEPT_ENABLED = resolveStudioBooleanEnvFlag(
-  env,
-  ["VITE_STUDIO_ENABLE_GSAP_DRAG_INTERCEPT", "VITE_STUDIO_GSAP_DRAG_INTERCEPT_ENABLED"],
-  true,
-);
-
 export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
 
 // Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch

package/src/components/editor/manualEdits.ts

@@ -16,6 +16,7 @@ export {
   endStudioManualEditGesture,
   isStudioManualEditGestureCurrent,
   readStudioPathOffset,
+  readAppliedStudioPathOffset,
   readStudioBoxSize,
   readStudioRotation,
   applyStudioPathOffset,

package/src/components/editor/manualEditsDom.ts

@@ -70,6 +70,19 @@ export function readStudioPathOffset(element: HTMLElement): { x: number; y: numb
   };
 }
 
+/**
+ * The path offset ACTUALLY applied right now. The `--hf-studio-offset` vars can
+ * linger after GSAP re-bakes the element's transform (`translate:"none"`), so the
+ * raw var isn't a safe drag base — using it re-commits a phantom offset and flings
+ * the element off-screen. The offset only counts when the inline `translate` is the
+ * studio var-translate; otherwise it's dormant and the applied offset is zero.
+ */
+export function readAppliedStudioPathOffset(element: HTMLElement): { x: number; y: number } {
+  return (element.style.translate || "").includes(STUDIO_OFFSET_X_PROP)
+    ? readStudioPathOffset(element)
+    : { x: 0, y: 0 };
+}
+
 export function readStudioBoxSize(element: HTMLElement): { width: number; height: number } {
   return {
     width: readPxCustomProperty(element, STUDIO_WIDTH_PROP),
@@ -250,6 +263,50 @@ function stripGsapTranslateFromTransform(element: HTMLElement): void {
   }
 }
 
+// GSAP owns the element's `transform` (it bakes x/y into a matrix and writes
+// `translate: none` every tick). Folding the drag offset into a CSS `translate`
+// — as the non-GSAP path does — composes ON TOP of GSAP's transform, and the
+// subsequent strip/reapply math compounds into a runaway matrix that flings the
+// element off-canvas. So for GSAP-animated elements we keep `translate: none`
+// and push the offset straight into GSAP's x/y via gsap.set; the var() offset is
+// still persisted (buildPathOffsetPatches), and GSAP re-reads it at init on
+// reload. Returns true when handled as GSAP (caller must skip the CSS path).
+function applyStudioPathOffsetViaGsap(
+  element: HTMLElement,
+  offset: { x: number; y: number },
+): boolean {
+  if (!gsapAnimatesProperty(element, "x", "y")) return false;
+  element.style.setProperty("translate", "none");
+  const win = element.ownerDocument.defaultView as
+    | (Window & {
+        gsap?: {
+          set: (el: Element, vars: Record<string, unknown>) => void;
+          getProperty: (el: Element, prop: string) => number;
+        };
+      })
+    | null;
+  if (win?.gsap) {
+    const baseX = Number.parseFloat(element.getAttribute("data-hf-drag-gsap-base-x") ?? "");
+    const baseY = Number.parseFloat(element.getAttribute("data-hf-drag-gsap-base-y") ?? "");
+    const origX = Number.parseFloat(element.getAttribute("data-hf-drag-initial-offset-x") ?? "");
+    const origY = Number.parseFloat(element.getAttribute("data-hf-drag-initial-offset-y") ?? "");
+    const gsapBaseX = Number.isFinite(baseX)
+      ? baseX
+      : (win.gsap.getProperty(element, "x") as number);
+    const gsapBaseY = Number.isFinite(baseY)
+      ? baseY
+      : (win.gsap.getProperty(element, "y") as number);
+    if (!Number.isFinite(baseX))
+      element.setAttribute("data-hf-drag-gsap-base-x", String(gsapBaseX));
+    if (!Number.isFinite(baseY))
+      element.setAttribute("data-hf-drag-gsap-base-y", String(gsapBaseY));
+    const deltaX = offset.x - (Number.isFinite(origX) ? origX : 0);
+    const deltaY = offset.y - (Number.isFinite(origY) ? origY : 0);
+    win.gsap.set(element, { x: gsapBaseX + deltaX, y: gsapBaseY + deltaY });
+  }
+  return true;
+}
+
 export function applyStudioPathOffset(
   element: HTMLElement,
   offset: { x: number; y: number },
@@ -257,6 +314,10 @@ export function applyStudioPathOffset(
 ): void {
   promoteInlineForTransform(element);
   writeStudioPathOffsetVars(element, offset, { updateBase: options.updateBase ?? true });
+  // GSAP elements: route through gsap.set, NOT a CSS translate (would corrupt the
+  // matrix). Symmetrical with applyStudioPathOffsetDraft — the commit path used to
+  // skip this branch, which is what flung dragged GSAP elements off-canvas.
+  if (applyStudioPathOffsetViaGsap(element, offset)) return;
   element.style.setProperty(
     "translate",
     composeTranslateValue(
@@ -274,45 +335,13 @@ export function applyStudioPathOffsetDraft(
 ): void {
   promoteInlineForTransform(element);
   writeStudioPathOffsetVars(element, offset, { updateBase: false });
-
-  const isGsapAnimated = gsapAnimatesProperty(element, "x", "y");
-  if (isGsapAnimated) {
-    element.style.setProperty("translate", "none");
-    const win = element.ownerDocument.defaultView as
-      | (Window & {
-          gsap?: {
-            set: (el: Element, vars: Record<string, unknown>) => void;
-            getProperty: (el: Element, prop: string) => number;
-          };
-        })
-      | null;
-    if (win?.gsap) {
-      const baseX = Number.parseFloat(element.getAttribute("data-hf-drag-gsap-base-x") ?? "");
-      const baseY = Number.parseFloat(element.getAttribute("data-hf-drag-gsap-base-y") ?? "");
-      const origX = Number.parseFloat(element.getAttribute("data-hf-drag-initial-offset-x") ?? "");
-      const origY = Number.parseFloat(element.getAttribute("data-hf-drag-initial-offset-y") ?? "");
-      const gsapBaseX = Number.isFinite(baseX)
-        ? baseX
-        : (win.gsap.getProperty(element, "x") as number);
-      const gsapBaseY = Number.isFinite(baseY)
-        ? baseY
-        : (win.gsap.getProperty(element, "y") as number);
-      if (!Number.isFinite(baseX))
-        element.setAttribute("data-hf-drag-gsap-base-x", String(gsapBaseX));
-      if (!Number.isFinite(baseY))
-        element.setAttribute("data-hf-drag-gsap-base-y", String(gsapBaseY));
-      const deltaX = offset.x - (Number.isFinite(origX) ? origX : 0);
-      const deltaY = offset.y - (Number.isFinite(origY) ? origY : 0);
-      win.gsap.set(element, { x: gsapBaseX + deltaX, y: gsapBaseY + deltaY });
-    }
-  } else {
-    // Non-GSAP elements: use CSS translate as before.
-    element.style.setProperty(
-      "translate",
-      composeTranslateValue(element, `${Math.round(offset.x)}px`, `${Math.round(offset.y)}px`),
-    );
-    stripGsapTranslateFromTransform(element);
-  }
+  if (applyStudioPathOffsetViaGsap(element, offset)) return;
+  // Non-GSAP elements: use CSS translate as before.
+  element.style.setProperty(
+    "translate",
+    composeTranslateValue(element, `${Math.round(offset.x)}px`, `${Math.round(offset.y)}px`),
+  );
+  stripGsapTranslateFromTransform(element);
 }
 
 /* ── Box size apply ───────────────────────────────────────────────── */

package/src/components/editor/manualEditsDomGsap.test.ts

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { applyStudioPathOffset, applyStudioPathOffsetDraft } from "./manualEditsDom";
+
+/**
+ * Regression: dragging a GSAP-animated element (e.g. a flat `to(#el, {x})` tween)
+ * must NOT fold the offset into a CSS `translate`. GSAP owns `style.transform`, so
+ * a CSS translate composes on top of it and the strip/reapply math compounds into
+ * a runaway matrix that flings the element off-canvas. Both the live draft and the
+ * commit must instead push the offset into GSAP's x/y via gsap.set and keep
+ * `translate: none`. Before the fix, the commit (applyStudioPathOffset) skipped the
+ * GSAP branch the draft already had — that asymmetry caused the off-canvas jump.
+ */
+
+function makeGsapWindow(
+  el: HTMLElement,
+  gsapSet: (e: Element, v: Record<string, unknown>) => void,
+) {
+  const win = el.ownerDocument.defaultView as unknown as {
+    __timelines?: Record<string, unknown>;
+    gsap?: unknown;
+  };
+  win.__timelines = {
+    playground: {
+      getChildren: () => [{ targets: () => [el], vars: { x: -260 } }],
+    },
+  };
+  win.gsap = {
+    set: gsapSet,
+    getProperty: () => 0,
+  };
+}
+
+afterEach(() => {
+  const win = window as unknown as { __timelines?: unknown; gsap?: unknown };
+  delete win.__timelines;
+  delete win.gsap;
+});
+
+describe("applyStudioPathOffset — GSAP-owned transform", () => {
+  it("non-GSAP element folds the offset into a CSS translate var()", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+
+    applyStudioPathOffset(el, { x: -120, y: 40 });
+
+    expect(el.style.translate).toContain("var(--hf-studio-offset-x");
+    expect(el.style.getPropertyValue("--hf-studio-offset-x")).toBe("-120px");
+    expect(el.style.getPropertyValue("--hf-studio-offset-y")).toBe("40px");
+  });
+
+  it("GSAP element keeps translate:none and routes the offset through gsap.set", () => {
+    const el = document.createElement("div");
+    el.id = "puck-a";
+    document.body.appendChild(el);
+    const gsapSet = vi.fn();
+    makeGsapWindow(el, gsapSet);
+
+    applyStudioPathOffset(el, { x: -409, y: 398 });
+
+    // No CSS translate to collide with GSAP's transform.
+    expect(el.style.translate).toBe("none");
+    expect(el.style.translate).not.toContain("var(");
+    // Offset pushed into GSAP's x/y (gsapBase 0 + delta = the offset itself here).
+    expect(gsapSet).toHaveBeenCalledWith(el, { x: -409, y: 398 });
+  });
+
+  it("draft and commit treat a GSAP element identically (translate:none)", () => {
+    const el = document.createElement("div");
+    el.id = "puck-a";
+    document.body.appendChild(el);
+    makeGsapWindow(el, vi.fn());
+
+    applyStudioPathOffsetDraft(el, { x: -50, y: 10 });
+    const draftTranslate = el.style.translate;
+    applyStudioPathOffset(el, { x: -50, y: 10 });
+    const commitTranslate = el.style.translate;
+
+    expect(draftTranslate).toBe("none");
+    expect(commitTranslate).toBe("none");
+  });
+});

package/src/components/editor/manualOffsetDrag.test.ts

@@ -193,6 +193,12 @@ describe("createManualOffsetDragMember uses raw CSS var offset", () => {
 
     element.style.setProperty(STUDIO_OFFSET_X_PROP, "30px");
     element.style.setProperty(STUDIO_OFFSET_Y_PROP, "10px");
+    // Old projects bake the offset by referencing the vars in the inline
+    // `translate` longhand — that's what makes the offset "applied" and thus the
+    // valid drag base (readAppliedStudioPathOffset). A raw var with no applied
+    // translate is dormant and reads as zero. Assign the typed `.translate`
+    // accessor (happy-dom doesn't surface it via setProperty).
+    element.style.translate = `var(${STUDIO_OFFSET_X_PROP}, 0px) var(${STUDIO_OFFSET_Y_PROP}, 0px)`;
     element.style.setProperty("transform", "translate(50px, -15px)");
 
     element.getBoundingClientRect = () => {
@@ -228,6 +234,12 @@ describe("createManualOffsetDragMember uses raw CSS var offset", () => {
     // Simulate GSAP baking a translate into transform each cycle
     for (let cycle = 0; cycle < 3; cycle++) {
       element.style.setProperty("transform", `translate(${50 * (cycle + 1)}px, 0px)`);
+      // Mark the offset as APPLIED (the inline translate references the studio
+      // vars, the form an old project bakes) so readAppliedStudioPathOffset reads
+      // the var, not zero. Without this the var is dormant and reads as zero.
+      // Assign the typed `.translate` accessor (happy-dom doesn't surface it via
+      // setProperty).
+      element.style.translate = `var(${STUDIO_OFFSET_X_PROP}, 0px) var(${STUDIO_OFFSET_Y_PROP}, 0px)`;
 
       const result = createManualOffsetDragMember({
         key: "test",

package/src/components/editor/manualOffsetDrag.ts

@@ -5,10 +5,71 @@ import {
   beginStudioManualEditGesture,
   captureStudioPathOffset,
   endStudioManualEditGesture,
-  readStudioPathOffset,
+  readAppliedStudioPathOffset,
   restoreStudioPathOffset,
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
+import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
+
+interface OffsetDragGsap {
+  set: (el: Element, vars: Record<string, number | string>) => void;
+  getProperty: (el: Element, prop: string) => number;
+}
+
+function getOffsetDragGsap(element: HTMLElement): OffsetDragGsap | null {
+  const win = element.ownerDocument.defaultView as
+    | (Window & { gsap?: Partial<OffsetDragGsap> })
+    | null;
+  const gsap = win?.gsap;
+  return gsap?.set && gsap.getProperty ? (gsap as OffsetDragGsap) : null;
+}
+
+/**
+ * Live drag preview through the GSAP channel — the SAME channel the commit
+ * lands in (a `tl.set`/keyframe on the timeline), so what the user sees while
+ * dragging equals what gets written (plan R3/R4). Reuses the commit's
+ * base+delta+rotation math so preview and commit agree by construction. Returns
+ * true when handled via gsap; false when gsap is unavailable (caller falls back
+ * to the CSS draft).
+ */
+function applyOffsetDragDraftViaGsap(
+  element: HTMLElement,
+  offset: { x: number; y: number },
+): boolean {
+  const gsap = getOffsetDragGsap(element);
+  if (!gsap) return false;
+  // GSAP owns the transform; neutralize the CSS translate longhand so the two
+  // channels can't compose into a doubled position.
+  element.style.setProperty("translate", "none");
+  const fallbackBase = {
+    x: Number(gsap.getProperty(element, "x")) || 0,
+    y: Number(gsap.getProperty(element, "y")) || 0,
+  };
+  const { newX, newY } = computeDraggedGsapPosition(element, offset, fallbackBase);
+  gsap.set(element, { x: newX, y: newY });
+  return true;
+}
+
+/**
+ * Live rotation preview through the GSAP channel — the SAME channel the commit
+ * lands in (a `tl.set`/keyframe rotation), mirroring `applyOffsetDragDraftViaGsap`.
+ * GSAP owns the transform rotation, so neutralize the CSS `rotate` longhand to keep
+ * the two channels from composing. `angle` is the absolute target rotation. Returns
+ * false when gsap is unavailable (caller falls back to the CSS draft).
+ */
+export function applyRotationDraftViaGsap(element: HTMLElement, angle: number): boolean {
+  const gsap = getOffsetDragGsap(element);
+  if (!gsap) return false;
+  element.style.setProperty("rotate", "none");
+  gsap.set(element, { rotation: angle });
+  return true;
+}
+
+/** Current GSAP transform rotation — the single-source rotation base. 0 if gsap is unavailable. */
+export function readGsapRotation(element: HTMLElement): number {
+  const gsap = getOffsetDragGsap(element);
+  return gsap ? Number(gsap.getProperty(element, "rotation")) || 0 : 0;
+}
 
 const DEFAULT_OFFSET_PROBE_PX = 100;
 const MIN_PROBE_VECTOR_LENGTH_PX = 0.01;
@@ -241,7 +302,10 @@ export function createManualOffsetDragMember(input: {
   element: HTMLElement;
   rect: ManualOffsetDragRect;
 }): ManualOffsetDragMemberResult {
-  const initialOffset = readStudioPathOffset(input.element);
+  // Base the drag on the offset ACTUALLY applied, never the raw (possibly dormant)
+  // var — see readAppliedStudioPathOffset. This keeps the commit purely relative
+  // (applied + delta) so a stale offset can't fling the element off-screen.
+  const initialOffset = readAppliedStudioPathOffset(input.element);
   input.element.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
   input.element.setAttribute("data-hf-drag-initial-offset-y", String(initialOffset.y));
 
@@ -335,7 +399,12 @@ export function applyManualOffsetDragDraft(
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  applyStudioPathOffsetDraft(member.element, offset);
+  // Position is single-sourced on the GSAP timeline; preview through gsap.set so
+  // the live draft matches the committed `tl.set`/keyframe. CSS draft only when
+  // gsap is unavailable (no preview iframe runtime).
+  if (!applyOffsetDragDraftViaGsap(member.element, offset)) {
+    applyStudioPathOffsetDraft(member.element, offset);
+  }
   return offset;
 }
 
@@ -345,7 +414,13 @@ export function applyManualOffsetDragCommit(
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  applyStudioPathOffset(member.element, offset);
+  // Optimistic visual through the GSAP channel (same as the live draft and the
+  // committed `tl.set`), so the element holds its dropped position until the
+  // source mutation soft-reloads — no transient CSS `--hf-studio-offset` write.
+  // CSS apply only when gsap is unavailable.
+  if (!applyOffsetDragDraftViaGsap(member.element, offset)) {
+    applyStudioPathOffset(member.element, offset);
+  }
   return offset;
 }
 

package/src/components/editor/motionPathCommit.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { editableAnimationId } from "./motionPathSelection";
+import {
+  commitNode,
+  commitAddWaypoint,
+  commitAddKeyframe,
+  commitRemoveWaypoint,
+  commitCreatePath,
+} from "./motionPathCommit";
+
+const anim = (over: Partial<GsapAnimation>): GsapAnimation =>
+  ({
+    id: "a1",
+    targetSelector: "#el",
+    method: "to",
+    position: 0,
+    properties: {},
+    ...over,
+  }) as GsapAnimation;
+
+describe("editableAnimationId", () => {
+  it("picks the arc animation for an arc path", () => {
+    const arc = anim({ id: "arc1", arcPath: { enabled: true, autoRotate: false, segments: [] } });
+    expect(editableAnimationId([anim({ id: "other" }), arc], "arc")).toBe("arc1");
+  });
+
+  it("picks a position-keyframe animation for a linear path", () => {
+    const kf = anim({
+      id: "kf1",
+      propertyGroup: "position",
+      keyframes: {
+        format: "percentage",
+        keyframes: [{ percentage: 0, properties: { x: 0, y: 0 } }],
+      } as never,
+    });
+    expect(editableAnimationId([kf], "linear")).toBe("kf1");
+  });
+
+  it("returns null for dynamic (unresolved) tweens — read-only", () => {
+    const dyn = anim({
+      id: "dyn",
+      arcPath: { enabled: true, autoRotate: false, segments: [] },
+      hasUnresolvedKeyframes: true,
+    });
+    expect(editableAnimationId([dyn], "arc")).toBeNull();
+  });
+
+  it("returns null for non-literal (helper) provenance — read-only", () => {
+    const helper = anim({
+      id: "h",
+      arcPath: { enabled: true, autoRotate: false, segments: [] },
+      provenance: { kind: "helper" } as never,
+    });
+    expect(editableAnimationId([helper], "arc")).toBeNull();
+  });
+
+  it("returns null when nothing matches", () => {
+    expect(editableAnimationId([anim({ id: "x" })], "linear")).toBeNull();
+  });
+});
+
+describe("commitNode", () => {
+  it("routes a keyframe node to update-keyframe by percentage", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitNode({ type: "keyframe", pct: 50 }, 120, 30, "a1", commit);
+    expect(commit).toHaveBeenCalledWith(
+      { type: "update-keyframe", animationId: "a1", percentage: 50, properties: { x: 120, y: 30 } },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+
+  it("routes a waypoint node to update-motion-path-point by index", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitNode({ type: "waypoint", index: 2 }, 80, 40, "a1", commit);
+    expect(commit).toHaveBeenCalledWith(
+      { type: "update-motion-path-point", animationId: "a1", pointIndex: 2, x: 80, y: 40 },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+});
+
+describe("commitAddWaypoint / commitRemoveWaypoint", () => {
+  it("adds a waypoint at an index with coordinates", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitAddWaypoint("a1", 1, 120, -40, commit);
+    expect(commit).toHaveBeenCalledWith(
+      { type: "add-motion-path-point", animationId: "a1", index: 1, x: 120, y: -40 },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+
+  it("removes a waypoint by index", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitRemoveWaypoint("a1", 2, commit);
+    expect(commit).toHaveBeenCalledWith(
+      { type: "remove-motion-path-point", animationId: "a1", index: 2 },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+});
+
+describe("commitAddKeyframe", () => {
+  it("inserts an x/y keyframe at a tween-relative percentage", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitAddKeyframe("a1", 42.5, 80, -20, commit);
+    expect(commit).toHaveBeenCalledWith(
+      { type: "add-keyframe", animationId: "a1", percentage: 42.5, properties: { x: 80, y: -20 } },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+});
+
+describe("commitCreatePath", () => {
+  it("authors a new motionPath to a destination at a given time", async () => {
+    const commit = vi.fn().mockResolvedValue(undefined);
+    await commitCreatePath("#title", 2.0, 300, -120, commit);
+    expect(commit).toHaveBeenCalledWith(
+      {
+        type: "add-motion-path",
+        targetSelector: "#title",
+        position: 2.0,
+        duration: 1.5,
+        x: 300,
+        y: -120,
+      },
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+});