@hyperframes/studio 0.8.124 → 0.8.126

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -9,6 +9,7 @@ import {
   restoreManualOffsetDragMembers,
   type ManualOffsetDragMember,
 } from "./manualOffsetDrag";
+import { readElementLook } from "./gestureUndoRevert";
 import { readCssRotationTarget, readRotationBase } from "./rotationDraft";
 import {
   beginStudioManualEditGesture,
@@ -179,6 +180,10 @@ export function startGesture(
     Number.isFinite(rawContentScaleX) && rawContentScaleX > 0 ? rawContentScaleX : 1;
   const contentScaleY =
     Number.isFinite(rawContentScaleY) && rawContentScaleY > 0 ? rawContentScaleY : 1;
+  const initialLook = readElementLook(
+    sel.element,
+    kind !== "drag" && !editsPlainCss(sel.element, kind === "rotate" ? "rotate" : "resize"),
+  );
   let initialPathOffset = captureStudioPathOffset(sel.element);
   let manualEditDragToken: string | undefined;
   let pathOffsetMember: ManualOffsetDragMember | undefined;
@@ -274,6 +279,7 @@ export function startGesture(
       initialPathOffset,
       initialRotation: captureStudioRotation(sel.element),
       initialBoxSize: captureStudioBoxSize(sel.element),
+      initialLook,
       pathOffsetMember,
       originLeft: rect.left,
       originTop: rect.top,

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

@@ -1,15 +1,40 @@
 // @vitest-environment happy-dom
 import { afterEach, expect, it, vi } from "vitest";
+import { savePlainRotation } from "../../hooks/plainRotation";
 import type { DomEditSelection } from "./domEditing";
 import type { GestureState } from "./domEditOverlayGestures";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import {
+  adoptingStudioPendingEdit,
   hasStudioPendingEdits,
   paintBackNewestStudioPendingEdit,
+  type StudioEditInFlight,
 } from "../../utils/studioPendingEdits";
 
+const gsapOwns = vi.hoisted(() => ({ on: false }));
+vi.mock("../../hooks/gsapRuntimeKeyframes", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../hooks/gsapRuntimeKeyframes")>()),
+  editsPlainCss: () => !gsapOwns.on,
+}));
+
+/** GSAP's own transform values per element, as `gsap.set` / `gsap.getProperty` see them. */
+function fakeGsap(start: Record<string, number>) {
+  const values = new Map<Element, Record<string, number>>();
+  const of = (el: Element) => values.get(el) ?? values.set(el, { ...start }).get(el)!;
+  gsapOwns.on = true;
+  Object.assign(window, {
+    gsap: {
+      set: (el: Element, props: Record<string, number>) => Object.assign(of(el), props),
+      getProperty: (el: Element, prop: string) => of(el)[prop] ?? 0,
+    },
+  });
+  return of;
+}
+
 afterEach(() => {
   document.body.innerHTML = "";
+  gsapOwns.on = false;
+  Reflect.deleteProperty(window, "gsap");
 });
 
 const ref = <T>(current: T) => ({ current });
@@ -24,7 +49,7 @@ const pointer = (x: number, y: number) => ({
 });
 
 /** Drags a box without GSAP 100 px right and 60 px down; its save waits for `save`. */
-function dragWithSaveRunning(save: Promise<void>) {
+function dragWithSaveRunning(save: Promise<void> | (() => Promise<void>)) {
   const element = document.createElement("div");
   element.style.setProperty("translate", "40px 30px");
   document.body.append(element);
@@ -39,7 +64,7 @@ function dragWithSaveRunning(save: Promise<void>) {
     rafPausedRef: ref(false),
     onManualDragStartRef: ref(vi.fn()),
     onBlockedMoveRef: ref(vi.fn()),
-    onPathOffsetCommitRef: ref(vi.fn(() => save)),
+    onPathOffsetCommitRef: ref(vi.fn(typeof save === "function" ? save : () => save)),
     snapGuidesRef: ref(null),
     groupGestureRef: ref(null),
     blockedMoveRef: ref(null),
@@ -69,3 +94,146 @@ it("a drag whose save is still running can be painted back at once, and shown ag
   await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
   expect(paintBackNewestStudioPendingEdit()).toBeNull();
 });
+
+/** Resizes or rotates a plain 240x160 box; the commit draws what it saves at once and its save waits for `save`. */
+function gestureWithSaveRunning(kind: "resize" | "rotate", save: Promise<void>) {
+  const element = document.createElement("div");
+  element.setAttribute(
+    "style",
+    "position: absolute; width: 240px; height: 160px; clip-path: inset(10px)",
+  );
+  document.body.append(element);
+  const selection = {
+    element,
+    capabilities: { canApplyManualSize: true, canApplyManualRotation: true },
+  };
+  const handlers = createDomEditOverlayGestureHandlers({
+    selectionRef: ref(selection as unknown as DomEditSelection),
+    overlayRectRef: ref({ left: 0, top: 0, width: 240, height: 160, editScaleX: 1, editScaleY: 1 }),
+    boxRef: ref(document.createElement("div")),
+    overlayRef: ref(null),
+    iframeRef: ref(null),
+    gestureRef: ref<GestureState | null>(null),
+    rafPausedRef: ref(false),
+    onBoxSizeCommitRef: ref(
+      vi.fn(() => {
+        element.style.setProperty("clip-path", "inset(15px)");
+        return save;
+      }),
+    ),
+    onRotationCommitRef: ref((sel: DomEditSelection, next: never) =>
+      savePlainRotation({ commitPositionPatchToHtml: () => save.then(() => undefined) }, sel, next),
+    ),
+    snapGuidesRef: ref(null),
+    groupGestureRef: ref(null),
+    blockedMoveRef: ref(null),
+    setOverlayRect: vi.fn(),
+    suppressNextBoxClickRef: ref(false),
+    hoverSelectionRef: ref(null),
+    onCanvasMouseDown: vi.fn(),
+  } as never);
+  const start = kind === "resize" ? pointer(240, 160) : pointer(240, 80);
+  expect(handlers.startGesture(kind, start as never, { resizeHandle: "se" })).toBe(true);
+  const end = kind === "resize" ? pointer(300, 200) : pointer(120, 200);
+  handlers.onPointerMove(end as never);
+  handlers.onPointerUp(end as never);
+  return element;
+}
+
+it.each(["resize", "rotate"] as const)(
+  "a %s whose save is still running can be painted back at once, and shown again",
+  async (kind) => {
+    let saved!: () => void;
+    const element = gestureWithSaveRunning(kind, new Promise<void>((resolve) => (saved = resolve)));
+    const before = "position: absolute; width: 240px; height: 160px; clip-path: inset(10px)";
+    const edited = element.getAttribute("style");
+    expect(edited).not.toBe(before);
+
+    const shown = paintBackNewestStudioPendingEdit();
+    expect(element.getAttribute("style")).toBe(before);
+    expect(paintBackNewestStudioPendingEdit()).toBeNull();
+    shown!.showAgain();
+    expect(element.getAttribute("style")).toBe(edited);
+
+    saved();
+    await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
+  },
+);
+
+it("a drag of a box GSAP positions is painted back to where GSAP had it, and shown again", async () => {
+  const gsapOf = fakeGsap({ x: 5, y: 7 });
+  let saved!: () => void;
+  const element = dragWithSaveRunning(new Promise<void>((resolve) => (saved = resolve)));
+  const moved = { ...gsapOf(element) };
+  expect(moved).not.toMatchObject({ x: 5, y: 7 });
+
+  const shown = paintBackNewestStudioPendingEdit();
+  expect(gsapOf(element)).toMatchObject({ x: 5, y: 7 });
+  shown!.showAgain();
+  expect(gsapOf(element)).toMatchObject({ x: moved.x, y: moved.y });
+
+  saved();
+  await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
+});
+
+it("a rotate of a box GSAP turns is painted back to GSAP's angle at press, and shown again", async () => {
+  const gsapOf = fakeGsap({ rotation: 10 });
+  let saved!: () => void;
+  const element = gestureWithSaveRunning(
+    "rotate",
+    new Promise<void>((resolve) => (saved = resolve)),
+  );
+  const turned = gsapOf(element).rotation;
+  expect(turned).not.toBe(10);
+
+  const shown = paintBackNewestStudioPendingEdit();
+  expect(gsapOf(element).rotation).toBe(10);
+  shown!.showAgain();
+  expect(gsapOf(element).rotation).toBe(turned);
+
+  saved();
+  await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
+});
+
+it("a GSAP drag saved as a left/top offset stays painted back while that offset is drawn", async () => {
+  fakeGsap({ x: 5, y: 7 });
+  let saved!: () => void;
+  let drawn!: Promise<void>;
+  const element = dragWithSaveRunning(() => {
+    const edit = adoptingStudioPendingEdit()!;
+    drawn = new Promise<void>((resolve) => (saved = resolve)).then(() =>
+      edit.drawKeepingUndone(() => void element.style.setProperty("left", "99px")),
+    );
+    return drawn;
+  });
+
+  const shown = paintBackNewestStudioPendingEdit();
+  saved();
+  await drawn;
+  expect(element.style.getPropertyValue("left")).toBe("");
+  shown!.showAgain();
+  expect(element.style.getPropertyValue("left")).toBe("99px");
+  await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
+});
+
+it("keeps a GSAP drag's base through every repaint of its undo, so its save adds the drag once", async () => {
+  const gsapOf = fakeGsap({ x: 5, y: 7 });
+  let edit!: StudioEditInFlight;
+  let release!: () => void;
+  const element = dragWithSaveRunning(() => {
+    edit = adoptingStudioPendingEdit()!;
+    return new Promise<void>((resolve) => (release = resolve));
+  });
+  const moved = { ...gsapOf(element) };
+
+  const shown = paintBackNewestStudioPendingEdit();
+  edit.drawKeepingUndone(() => undefined);
+  expect(gsapOf(element)).toMatchObject({ x: 5, y: 7 });
+  expect(element.getAttribute("data-hf-drag-gsap-base-x")).toBe("5");
+  shown!.showAgain();
+  expect(gsapOf(element)).toMatchObject({ x: moved.x, y: moved.y });
+  expect(element.getAttribute("data-hf-drag-gsap-base-x")).toBe("5");
+
+  release();
+  await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
+});

package/src/components/editor/gestureUndoRevert.ts

@@ -0,0 +1,104 @@
+import {
+  captureStudioPathOffset,
+  restoreStudioPathOffset,
+  type StudioPathOffsetSnapshot,
+} from "./manualEdits";
+import {
+  getOffsetDragGsap,
+  stampGestureBase,
+  type ManualOffsetDragMember,
+} from "./manualOffsetDrag";
+import type { StudioEditRevert } from "../../utils/studioPendingEdits";
+
+interface MemberPosition {
+  offset: StudioPathOffsetSnapshot;
+  gsap: { x: number; y: number } | null;
+  placement: string[];
+}
+
+// Where an element-offset move draws the element when no transform channel can take it.
+const PLACEMENT = ["position", "left", "top"];
+const placementOf = (element: HTMLElement) =>
+  PLACEMENT.map((prop) => element.style.getPropertyValue(prop));
+
+function showPlacement(element: HTMLElement, placement: string[]): void {
+  PLACEMENT.forEach((prop, i) => {
+    if (placement[i]) element.style.setProperty(prop, placement[i]!);
+    else element.style.removeProperty(prop);
+  });
+}
+
+function readMemberPosition(member: ManualOffsetDragMember): MemberPosition {
+  const gsap = member.plainTranslate ? null : getOffsetDragGsap(member.element);
+  return {
+    offset: captureStudioPathOffset(member.element),
+    gsap: gsap && {
+      x: Number(gsap.getProperty(member.element, "x")),
+      y: Number(gsap.getProperty(member.element, "y")),
+    },
+    placement: placementOf(member.element),
+  };
+}
+
+function showMemberPosition(member: ManualOffsetDragMember, position: MemberPosition): void {
+  restoreStudioPathOffset(member.element, position.offset);
+  showPlacement(member.element, position.placement);
+  if (position.gsap) getOffsetDragGsap(member.element)?.set(member.element, { ...position.gsap });
+  // The restore drops the gesture's base stamps; its save still reads them.
+  if (!member.plainTranslate)
+    stampGestureBase(member.element, member.initialOffset, member.baseGsap);
+}
+
+/** Undo's live revert of a move: its members at gesture start. */
+export function manualOffsetMoveRevert(members: ManualOffsetDragMember[]): StudioEditRevert {
+  const startPlacement = members.map((member) => placementOf(member.element));
+  return () => {
+    const shown = members.map(readMemberPosition);
+    members.forEach((member, i) =>
+      showMemberPosition(member, {
+        offset: member.initialPathOffset,
+        gsap: member.plainTranslate ? null : member.baseGsap,
+        placement: startPlacement[i]!,
+      }),
+    );
+    return () => members.forEach((member, i) => showMemberPosition(member, shown[i]!));
+  };
+}
+
+export interface StudioElementLook {
+  style: string | null;
+  gsap: Record<string, number> | null;
+}
+
+const GSAP_LOOK_PROPS = ["x", "y", "rotation", "scaleX", "scaleY"];
+
+/** Reads GSAP only for an element it owns: reading a plain one makes GSAP bake its CSS into a transform. */
+export function readElementLook(element: HTMLElement, gsapOwned: boolean): StudioElementLook {
+  const gsap = gsapOwned ? getOffsetDragGsap(element) : null;
+  return {
+    style: element.getAttribute("style"),
+    gsap:
+      gsap &&
+      Object.fromEntries(
+        GSAP_LOOK_PROPS.map((prop) => [prop, Number(gsap.getProperty(element, prop))]),
+      ),
+  };
+}
+
+function showElementLook(element: HTMLElement, look: StudioElementLook): void {
+  if (look.style === null) element.removeAttribute("style");
+  else element.setAttribute("style", look.style);
+  if (look.gsap) getOffsetDragGsap(element)?.set(element, { ...look.gsap });
+}
+
+/** Undo's live revert of a resize or rotate: the element as it looked at press. */
+export function elementLookRevert(
+  element: HTMLElement,
+  start: StudioElementLook,
+): StudioEditRevert {
+  return () => {
+    const shown = readElementLook(element, start.gsap !== null);
+    showElementLook(element, start);
+    return () => showElementLook(element, shown);
+  };
+}

package/src/components/editor/manualEditsSeekReapply.ts

@@ -1,4 +1,5 @@
 // Puts Studio's committed edits back after a timeline seek has rendered over them.
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import {
   STUDIO_BOX_SIZE_ATTR,
   STUDIO_HEIGHT_PROP,
@@ -15,15 +16,11 @@ import { STUDIO_MOTION_ATTR, STUDIO_MOTION_TIMELINE_ID } from "./studioMotionTyp
 import { gsapWritesChannels } from "../../hooks/gsapRuntimeKeyframes";
 
 function queryStudioElements(doc: Document, attr: string): HTMLElement[] {
-  const ctor = doc.defaultView?.HTMLElement;
-  if (!ctor) return [];
-  const elements = Array.from(doc.querySelectorAll(`[${attr}="true"]`)).filter(
-    (el): el is HTMLElement => el instanceof ctor,
-  );
+  const elements = Array.from(doc.querySelectorAll(`[${attr}="true"]`)).filter(isHtmlElement);
   // Handle legacy HTML files where attributes were persisted with a double data- prefix
   const legacyAttr = `data-${attr}`;
   for (const el of doc.querySelectorAll(`[${legacyAttr}="true"]`)) {
-    if (el instanceof ctor && !el.hasAttribute(attr)) {
+    if (isHtmlElement(el) && !el.hasAttribute(attr)) {
       el.setAttribute(attr, "true");
       el.removeAttribute(legacyAttr);
       elements.push(el);

package/src/components/editor/manualOffsetDrag.ts

@@ -1,3 +1,4 @@
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import type { DomEditSelection } from "./domEditing";
 import {
   applyStudioPathOffset,
@@ -13,7 +14,6 @@ import {
 import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
 import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { readTranslatePx, UNREADABLE_TRANSLATE, writeTranslatePx } from "./plainTranslate";
-import type { StudioEditRevert } from "../../utils/studioPendingEdits";
 
 interface OffsetDragGsap {
   set: (el: Element, vars: Record<string, number | string>) => void;
@@ -132,9 +132,7 @@ function getFrameElement(win: Window): HTMLElement | null {
   try {
     const frameElement = win.frameElement;
     if (!frameElement) return null;
-    const ownerWin = frameElement.ownerDocument.defaultView;
-    const htmlElement = ownerWin?.HTMLElement;
-    return htmlElement && frameElement instanceof htmlElement ? frameElement : null;
+    return isHtmlElement(frameElement) ? frameElement : null;
   } catch {
     return null;
   }
@@ -448,7 +446,7 @@ export function applyManualOffsetDragDraft(
  * the element flies off-screen the instant you drop it. The member holds the
  * true gesture-start values in JS, immune to the re-render.
  */
-function stampGestureBase(el: HTMLElement, initialOffset: Point, baseGsap: Point): void {
+export function stampGestureBase(el: HTMLElement, initialOffset: Point, baseGsap: Point): void {
   el.setAttribute("data-hf-drag-gsap-base-x", String(baseGsap.x));
   el.setAttribute("data-hf-drag-gsap-base-y", String(baseGsap.y));
   el.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
@@ -510,16 +508,6 @@ function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
   endStudioManualEditGesture(member.element, member.gestureToken);
 }
 
-/** Undo's live revert of a move: its members at gesture start. Null off the plain route, which GSAP draws. */
-export function manualOffsetMoveRevert(members: ManualOffsetDragMember[]): StudioEditRevert | null {
-  if (!members.every((member) => member.plainTranslate)) return null;
-  return () => {
-    const shown = members.map((member) => captureStudioPathOffset(member.element));
-    for (const member of members) restoreStudioPathOffset(member.element, member.initialPathOffset);
-    return () => members.forEach((member, i) => restoreStudioPathOffset(member.element, shown[i]!));
-  };
-}
-
 /** Roll back a FAILED drag to the exact gesture-start state. */
 export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
   for (const member of members) {

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildMotionPathGeometry, nearestPointOnPath } from "./motionPathGeometry";
+import { buildMotionPathGeometry, nearestPointOnPath, nodeCentre } from "./motionPathGeometry";
 import type { ReadTween } from "../../hooks/gsapRuntimeKeyframes";
 
 const kf = (percentage: number, x: number, y: number) => ({ percentage, properties: { x, y } });
@@ -135,3 +135,50 @@ describe("nearestPointOnPath", () => {
     expect(nearestPointOnPath(0, 0, [{ x: 0, y: 0 }])).toBeNull();
   });
 });
+
+describe("nodeCentre", () => {
+  // The edit bench's `keys` layer at 1 s: left 560, 260 wide now, GSAP x 50; it reaches x 60 and
+  // width 280 at 2 s, x 120 and width 320 at 3 s, so its centre is then at 760 and 840.
+  const home = { x: 690, y: 380, w: 260, h: 160, ax: 0.5, ay: 0.5 };
+  const read: ReadTween = {
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60, width: 280 } },
+      { percentage: 100, properties: { x: 120, width: 320 } },
+    ],
+  };
+
+  it("draws a keyframe that also sets the size where the layer's centre is at that keyframe", () => {
+    const geo = buildMotionPathGeometry(read, { x: 50, y: 30 })!;
+    expect(geo.nodes.map((n) => nodeCentre(n, home, 1))).toEqual([
+      { x: 760, y: 410 },
+      { x: 840, y: 410 },
+    ]);
+  });
+
+  it("keeps a layer centred by xPercent/yPercent -50 on its centre as a keyframe resizes it", () => {
+    const geo = buildMotionPathGeometry(read, { x: 50, y: 30 })!;
+    const centred = { ...home, ax: 0, ay: 0 };
+    expect(geo.nodes.map((n) => nodeCentre(n, centred, 1).x)).toEqual([750, 810]);
+  });
+
+  it("keeps a keyframe that sets no size at home plus its offset", () => {
+    const geo = buildMotionPathGeometry({ keyframes: [kf(0, 10, 20), kf(100, 200, 80)] })!;
+    expect(nodeCentre(geo.nodes[1]!, home, 1)).toEqual({ x: 890, y: 460 });
+  });
+});
+
+describe("start", () => {
+  it("keeps where GSAP started a tween whose first keyframe comes later, with the size it had", () => {
+    const read: ReadTween = {
+      keyframes: [kf(66.667, 60, 30), kf(100, 120, 30)],
+      start: { x: 40, y: 30, width: 260 },
+    };
+    expect(buildMotionPathGeometry(read)?.start).toEqual({ x: 40, y: 30, w: 260 });
+  });
+
+  it("draws no start when GSAP has not read one", () => {
+    expect(buildMotionPathGeometry({ keyframes: [kf(50, 60, 30), kf(100, 120, 30)] })?.start).toBe(
+      undefined,
+    );
+  });
+});

package/src/components/editor/motionPathGeometry.ts

@@ -11,18 +11,40 @@ export type MotionNodeRef =
   | { type: "keyframe"; pct: number } // x/y position keyframe at this tween-relative %
   | { type: "waypoint"; index: number }; // motionPath waypoint (anchor) at this index
 
-export interface MotionPathNode {
+/** An offset on the path and the layout width/height set there, when one is. */
+export interface MotionPathPoint {
   x: number;
   y: number;
+  w?: number;
+  h?: number;
+}
+
+export interface MotionPathNode extends MotionPathPoint {
   ref: MotionNodeRef;
 }
 
+/** The live layer's centre without its x/y offset, its layout size now, and the share of a size
+ *  change that moves the centre (0.5 from the left edge; 0 when xPercent -50 centres it). */
+export type MotionPathHome = { x: number; y: number; w: number; h: number; ax: number; ay: number };
+
+/** Where the layer's centre is at a node, with the size that keyframe sets. */
+export function nodeCentre(n: MotionPathPoint, home: MotionPathHome, pScale: number) {
+  const grow = (to: number | undefined, now: number, share: number) =>
+    to === undefined ? 0 : (to - now) * share;
+  return {
+    x: home.x + (n.x + grow(n.w, home.w, home.ax)) * pScale,
+    y: home.y + (n.y + grow(n.h, home.h, home.ay)) * pScale,
+  };
+}
+
 export interface MotionPathGeometry {
   /** "linear" = x/y keyframes; "arc" = motionPath tween. */
   kind: "linear" | "arc";
   /** SVG polyline points: "x,y x,y ...". */
   points: string;
   nodes: MotionPathNode[];
+  /** Where GSAP started the tween, when its first keyframe comes later: drawn, not draggable. */
+  start?: MotionPathPoint;
 }
 
 /**
@@ -78,6 +100,16 @@ export function nearestPointOnPath(
   return best;
 }
 
+const finiteNumber = (v: unknown): v is number => typeof v === "number" && isFinite(v);
+
+/** The layout width/height a keyframe sets, when it sets one. */
+function sizeAt(p: Record<string, unknown>): { w?: number; h?: number } {
+  return {
+    ...(finiteNumber(p.width) && { w: p.width }),
+    ...(finiteNumber(p.height) && { h: p.height }),
+  };
+}
+
 export function buildMotionPathGeometry(
   read: ReadTween | null,
   base: { x: number; y: number } = { x: 0, y: 0 },
@@ -94,26 +126,32 @@ export function buildMotionPathGeometry(
   // translate it folded in, else 0), so we default it and still draw a path. But if the tween
   // DOES animate an axis and a given keyframe omits it, that value is interpolated
   // (not 0) and can't be placed here → skip that node (the prior behavior).
-  const finite = (v: unknown): v is number => typeof v === "number" && isFinite(v);
-  const tweenHasX = read.keyframes.some((kf) => finite(kf.properties.x));
-  const tweenHasY = read.keyframes.some((kf) => finite(kf.properties.y));
+  const tweenHasX = read.keyframes.some((kf) => finiteNumber(kf.properties.x));
+  const tweenHasY = read.keyframes.some((kf) => finiteNumber(kf.properties.y));
   if (!tweenHasX && !tweenHasY) return null; // no positional motion (opacity/scale only)
 
+  const pointAt = (p: Record<string, unknown>): MotionPathPoint | null => {
+    if ((tweenHasX && !finiteNumber(p.x)) || (tweenHasY && !finiteNumber(p.y))) return null;
+    const x = tweenHasX ? (p.x as number) : base.x;
+    const y = tweenHasY ? (p.y as number) : base.y;
+    return { x, y, ...sizeAt(p) };
+  };
   read.keyframes.forEach((kf, i) => {
-    if (tweenHasX && !finite(kf.properties.x)) return;
-    if (tweenHasY && !finite(kf.properties.y)) return;
+    const at = pointAt(kf.properties);
+    if (!at) return;
     nodes.push({
-      x: tweenHasX ? (kf.properties.x as number) : base.x,
-      y: tweenHasY ? (kf.properties.y as number) : base.y,
+      ...at,
       ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
     });
   });
 
   if (nodes.length < 2) return null;
+  const start = !isArc && read.start ? pointAt(read.start) : null;
 
   return {
     kind: isArc ? "arc" : "linear",
     points: nodes.map((n) => `${n.x},${n.y}`).join(" "),
     nodes,
+    ...(start && { start }),
   };
 }

package/src/components/editor/motionPathHome.ts

@@ -0,0 +1,75 @@
+import type { MotionPathHome } from "./motionPathGeometry";
+
+// An element's computed transform translate: a group wrapper GSAP moved carries its offset here.
+function transformTranslate(el: HTMLElement): { x: number; y: number } {
+  const t = el.ownerDocument?.defaultView?.getComputedStyle(el).transform;
+  if (!t || t === "none") return { x: 0, y: 0 };
+  const m3 = t.match(/matrix3d\(([^)]+)\)/);
+  if (m3) {
+    const v = m3[1].split(",").map(Number);
+    return { x: v[12] || 0, y: v[13] || 0 };
+  }
+  const m = t.match(/matrix\(([^)]+)\)/);
+  if (m) {
+    const v = m[1].split(",").map(Number);
+    return { x: v[4] || 0, y: v[5] || 0 };
+  }
+  return { x: 0, y: 0 };
+}
+
+function cssTranslate(el: HTMLElement): [number, number] {
+  const raw = el.ownerDocument?.defaultView?.getComputedStyle(el).translate ?? "none";
+  const [x = "0", y = "0"] = raw === "none" ? [] : raw.split(" ");
+  const px = (v: string, size: number) =>
+    v.endsWith("%") ? (Number.parseFloat(v) / 100) * size : Number.parseFloat(v) || 0;
+  return [px(x, el.offsetWidth), px(y, el.offsetHeight)];
+}
+
+/** Centre shift per px grown: 0.5 from a set left/top, -0.5 from a set right/bottom, plus the percent.
+ *  ponytail: in-flow layers get 0 (layout may centre them); read their anchor if one draws off. */
+function growShares(el: HTMLElement, px: number, py: number): { ax: number; ay: number } {
+  const style = el.ownerDocument?.defaultView?.getComputedStyle(el);
+  if (!style || !/^(absolute|fixed)$/.test(style.position)) return { ax: 0, ay: 0 };
+  const map = el.computedStyleMap?.();
+  const auto = (side: string) => String(map?.get(side) ?? "") === "auto";
+  const share = (start: string, end: string) => (auto(start) && !auto(end) ? -0.5 : 0.5);
+  return { ax: share("left", "right") + px, ay: share("top", "bottom") + py };
+}
+
+export function elementHome(el: HTMLElement): MotionPathHome {
+  let left = 0;
+  let top = 0;
+  let node: HTMLElement | null = el;
+  while (node) {
+    left += node.offsetLeft;
+    top += node.offsetTop;
+    // Ancestor transforms (a group wrapper GSAP moved) shift where the layer renders; its own
+    // transform is the animated offset the path itself draws, so it is left out.
+    if (node !== el) {
+      const t = transformTranslate(node);
+      left += t.x;
+      top += t.y;
+    }
+    const parent = node.offsetParent as HTMLElement | null;
+    if (!parent || parent.hasAttribute("data-composition-id")) break;
+    node = parent;
+  }
+  // A translate composes once GSAP has parsed the layer; before, its parse sums translate and transform,
+  // makes minus half the size xPercent -50 and folds the rest into x, which a path sets (_parseTransform).
+  const cache = (
+    el as { _gsap?: { x?: unknown; uncache?: unknown; xPercent?: unknown; yPercent?: unknown } }
+  )._gsap;
+  const parsed = cache !== undefined && "x" in cache && !cache.uncache;
+  const [tx, ty] = cssTranslate(el);
+  const share = (cached: unknown, t: number, size: number) =>
+    parsed ? (Number(cached) || 0) / 100 : t && Math.round(size / 2) === Math.round(-t) ? -0.5 : 0;
+  const own = parsed ? { x: 0, y: 0 } : transformTranslate(el);
+  const [px, py] = [
+    share(cache?.xPercent, tx + own.x, el.offsetWidth),
+    share(cache?.yPercent, ty + own.y, el.offsetHeight),
+  ];
+  const x = left + el.offsetWidth * (0.5 + px) + (parsed ? tx : 0);
+  const y = top + el.offsetHeight * (0.5 + py) + (parsed ? ty : 0);
+  const { ax, ay } = growShares(el, px, py);
+  return { x, y, w: el.offsetWidth, h: el.offsetHeight, ax, ay };
+}