@hyperframes/studio 0.8.125 → 0.8.127

package/src/components/editor/motionPathGeometry.ts

@@ -8,21 +8,43 @@ import type { ReadTween } from "../../hooks/gsapRuntimeKeyframes";
 
 /** Which source edit a dragged node maps to. */
 export type MotionNodeRef =
-  | { type: "keyframe"; pct: number } // x/y position keyframe at this tween-relative %
+  | { type: "keyframe"; pct: number; step?: number } // x/y keyframe at this tween-relative %, array slot
   | { 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,34 @@ 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,
-      ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
+      ...at,
+      ref: isArc
+        ? { type: "waypoint", index: i }
+        : { type: "keyframe", pct: kf.percentage, ...(kf.step == null ? {} : { step: kf.step }) },
     });
   });
 
   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 };
+}

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

@@ -1,54 +1,64 @@
 // @vitest-environment happy-dom
 import { expect, it } from "vitest";
-import { pressBelongsToLayer, pressSelectedLayer } from "./motionPathLayerNode";
+import { controlForNode, controlUnder, pressControl } from "./motionPathLayerNode";
 
-// Keyframe nodes at x 60 and 120 (y 30), drawn from home (500, 400); dots of radius 6.
-const atLayer = { x: 60, y: 30, ax: 560, ay: 430 };
-const other = { x: 120, y: 30, ax: 620, ay: 430 };
+// Keyframe nodes at x 60 and 120 (y 30); GSAP renders the layer at the first.
+const atLayer = { x: 60, y: 30 };
+const other = { x: 120, y: 30 };
 const live = { x: 60, y: 30 };
 
+// The editor overlay: the selection's chrome (box and a handle) and another layer's off-canvas marker.
+const overlay = document.createElement("div");
+const chrome = document.createElement("div");
+chrome.setAttribute("data-dom-edit-chrome", "true");
 const box = document.createElement("div");
 box.setAttribute("data-dom-edit-selection-box", "true");
+const handle = document.createElement("button");
+const marker = document.createElement("div");
+chrome.append(box, handle);
+overlay.append(chrome, marker);
+const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
 const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
-document.body.append(box, circle);
+const line = document.createElementNS("http://www.w3.org/2000/svg", "polyline");
+svg.append(line, circle);
+document.body.append(overlay, svg);
 
-/** A press on `circle` at (x, y), with `under` what the document hit-tests there. */
-function press(x: number, y: number, under: Element[]) {
-  document.elementsFromPoint = () => [circle, ...under];
-  return { currentTarget: circle, clientX: x, clientY: y } as unknown as React.PointerEvent;
+/** A press on `circle`, with `under` what the document hit-tests below it. */
+function press(under: Element[]) {
+  document.elementsFromPoint = () => [circle, line, ...under];
+  return { currentTarget: circle, clientX: 0, clientY: 0 } as unknown as React.PointerEvent;
 }
 
 it("the node GSAP renders the layer at is the layer, inside the box or out", () => {
-  expect(pressBelongsToLayer(press(562, 431, [box]), { x: 562, y: 431 }, atLayer, 6, live)).toBe(
-    true,
-  );
-  expect(pressBelongsToLayer(press(570, 440, []), { x: 570, y: 440 }, atLayer, 6, live)).toBe(true);
+  expect(controlForNode(press([box, overlay]), atLayer, live)).toBe(box);
+  expect(controlForNode(press([overlay]), atLayer, live)).toBe(box);
 });
 
-it("inside the layer's box another node's grab ring is the layer's; its dot stays the node's", () => {
-  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, live)).toBe(
-    true,
-  );
-  expect(pressBelongsToLayer(press(617, 430, [box]), { x: 617, y: 430 }, other, 6, live)).toBe(
-    false,
-  );
+it("inside the layer's box any other node is the layer's, so a drag from its middle moves it", () => {
+  expect(controlForNode(press([box, overlay]), other, live)).toBe(box);
+  expect(controlForNode(press([box, overlay]), other, null)).toBe(box);
 });
 
-it("outside the layer's box a node's whole grab ring is the node's", () => {
-  expect(pressBelongsToLayer(press(610, 430, []), { x: 610, y: 430 }, other, 6, live)).toBe(false);
-  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, null)).toBe(
-    true,
-  );
+it("a handle above the box under a node takes the press, not the box or the node", () => {
+  expect(controlForNode(press([handle, box, overlay]), other, live)).toBe(handle);
+  expect(controlForNode(press([handle, box, overlay]), atLayer, live)).toBe(handle);
+  expect(controlUnder(press([handle, overlay]))).toBe(handle);
 });
 
-it("hands a press to the selected layer's box with its pointer and position", () => {
+it("outside the layer's box and its handles a node is the node's", () => {
+  expect(controlForNode(press([overlay]), other, live)).toBeNull();
+  expect(controlForNode(press([marker, overlay]), other, live)).toBeNull();
+  expect(controlForNode(press([document.body]), other, live)).toBeNull();
+});
+
+it("hands a press to the control with its pointer and position", () => {
   const got: number[][] = [];
   const listen = (e: Event) => {
     const p = e as PointerEvent;
     got.push([p.pointerId, p.clientX, p.clientY, p.button]);
     e.preventDefault();
   };
-  box.addEventListener("pointerdown", listen);
+  handle.addEventListener("pointerdown", listen);
   const nativeEvent = new PointerEvent("pointerdown", {
     pointerId: 7,
     clientX: 12,
@@ -58,24 +68,22 @@ it("hands a press to the selected layer's box with its pointer and position", ()
     cancelable: true,
   });
   const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
-  expect(pressSelectedLayer(down)).toBe(true);
+  expect(pressControl(down, handle)).toBe(true);
   expect(got).toEqual([[7, 12, 34, 0]]);
-  box.removeEventListener("pointerdown", listen);
-  box.remove();
-  expect(pressSelectedLayer(down)).toBe(false);
-  document.body.append(box);
+  expect(pressControl(down, null)).toBe(false);
+  handle.removeEventListener("pointerdown", listen);
 });
 
-it("keeps the press when the box does not start a gesture with it, or takes no pointer", () => {
+it("keeps the press when the control does not start a gesture with it, or takes no pointer", () => {
   let got = 0;
   const listen = () => void got++;
   box.addEventListener("pointerdown", listen);
   const nativeEvent = new PointerEvent("pointerdown", { bubbles: true, cancelable: true });
   const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
-  expect(pressSelectedLayer(down)).toBe(false);
+  expect(pressControl(down, box)).toBe(false);
   expect(got).toBe(1);
   box.style.pointerEvents = "none";
-  expect(pressSelectedLayer(down)).toBe(false);
+  expect(pressControl(down, box)).toBe(false);
   expect(got).toBe(1);
   box.style.pointerEvents = "";
   box.removeEventListener("pointerdown", listen);

package/src/components/editor/motionPathLayerNode.ts

@@ -1,28 +1,32 @@
 type Point = { x: number; y: number };
-type DrawnNode = Point & { ax: number; ay: number };
 
 const LAYER_BOX = '[data-dom-edit-selection-box="true"]';
+export const SELECTION_CHROME = `${LAYER_BOX}, [data-dom-edit-chrome="true"], [data-dom-edit-crop-frame="true"]`;
 
 /** How far a node's dot reaches; a selected node draws it larger. */
 export const dotRadius = (r: number, selected: boolean) => (selected ? r * 1.5 : r);
 
-/** A press on the layer's own node, or in its box but off a node's dot, belongs to the layer. */
-export function pressBelongsToLayer(
+export function controlUnder(e: React.PointerEvent): Element | null {
+  const path = e.currentTarget.closest("svg");
+  const hits = e.currentTarget.ownerDocument.elementsFromPoint(e.clientX, e.clientY);
+  const hit = hits.find((el) => !path?.contains(el));
+  return hit?.closest(SELECTION_CHROME) ? hit : null;
+}
+
+/** The handle or box above a node, else the box if the layer sits at the node; null: the node. */
+export function controlForNode(
   e: React.PointerEvent,
-  point: Point,
-  pressed: DrawnNode,
-  dotR: number,
+  pressed: Point,
   live: Point | null,
-): boolean {
-  if (live && Math.abs(pressed.x - live.x) < 0.5 && Math.abs(pressed.y - live.y) < 0.5) return true;
-  const hits = e.currentTarget.ownerDocument.elementsFromPoint(e.clientX, e.clientY);
-  const inBox = hits.some((el) => el.closest(LAYER_BOX));
-  return inBox && Math.hypot(point.x - pressed.ax, point.y - pressed.ay) > dotR;
+): Element | null {
+  const atLayer = live && Math.abs(pressed.x - live.x) < 0.5 && Math.abs(pressed.y - live.y) < 0.5;
+  return (
+    controlUnder(e) ?? (atLayer ? e.currentTarget.ownerDocument.querySelector(LAYER_BOX) : null)
+  );
 }
 
-/** Hands a press to the selected layer's box; true when the box started a gesture with it. */
-export function pressSelectedLayer(e: React.PointerEvent): boolean {
-  const box = e.currentTarget.ownerDocument.querySelector(LAYER_BOX);
-  if (!box || getComputedStyle(box).pointerEvents === "none") return false;
-  return !box.dispatchEvent(new PointerEvent("pointerdown", e.nativeEvent));
+/** Hands a press to `control`; true when it started a gesture with it. */
+export function pressControl(e: React.PointerEvent, control: Element | null): boolean {
+  if (!control || getComputedStyle(control).pointerEvents === "none") return false;
+  return !control.dispatchEvent(new PointerEvent("pointerdown", e.nativeEvent));
 }

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

@@ -130,6 +130,26 @@ describe("reapplyPositionEditsAfterSeek", () => {
     delete win.__timelines;
   });
 
+  it("reapplies and migrates marks in the preview, whichever window built its node", () => {
+    const frame = document.body.appendChild(document.createElement("iframe"));
+    const doc = frame.contentDocument!;
+    // The frame builds one node; the editor builds the other, as on loads where they differ.
+    const nodes = [doc.createElement("div"), document.createElement("div")];
+    for (const el of nodes) {
+      el.setAttribute(`data-${STUDIO_PATH_OFFSET_ATTR}`, "true");
+      el.setAttribute(STUDIO_ROTATION_ATTR, "true");
+      el.style.setProperty(STUDIO_ROTATION_PROP, "8deg");
+      doc.body.append(el);
+    }
+
+    reapplyPositionEditsAfterSeek(doc);
+
+    for (const el of nodes) {
+      expect(el.getAttribute(STUDIO_PATH_OFFSET_ATTR)).toBe("true");
+      expect(el.style.getPropertyValue("rotate")).toContain(STUDIO_ROTATION_PROP);
+    }
+  });
+
   it("still migrates a legacy double-prefixed edit mark", () => {
     document.body.innerHTML = `<div id="a" data-${STUDIO_PATH_OFFSET_ATTR}="true"></div>`;
 

package/src/components/editor/studioMotion.ts

@@ -35,6 +35,7 @@ export {
   clearStudioMotionFromElement,
 } from "./studioMotionOps";
 
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import { readStudioMotionFromElement as readMotionAttr } from "./studioMotionOps";
 import {
   STUDIO_MOTION_ATTR,
@@ -71,21 +72,17 @@ function elementMatchesSourceFile(
 }
 
 function querySelectorCandidates(document: Document, selector: string): HTMLElement[] {
-  const isCandidate = (element: Element): element is HTMLElement => {
-    const HTMLElementCtor = element.ownerDocument.defaultView?.HTMLElement;
-    return Boolean(HTMLElementCtor && element instanceof HTMLElementCtor);
-  };
   const className = selector.match(/^\.([A-Za-z0-9_-]+)$/)?.[1];
   if (className) {
     return Array.from(document.getElementsByTagName("*")).filter(
       (element): element is HTMLElement =>
-        isCandidate(element) && element.classList.contains(className),
+        isHtmlElement(element) && element.classList.contains(className),
     );
   }
   if (/^[A-Za-z][A-Za-z0-9-]*$/.test(selector)) {
-    return Array.from(document.getElementsByTagName(selector)).filter(isCandidate);
+    return Array.from(document.getElementsByTagName(selector)).filter(isHtmlElement);
   }
-  return Array.from(document.querySelectorAll(selector)).filter(isCandidate);
+  return Array.from(document.querySelectorAll(selector)).filter(isHtmlElement);
 }
 
 function resolveTarget(
@@ -93,12 +90,10 @@ function resolveTarget(
   target: StudioMotionTarget,
   activeCompositionPath: string | null,
 ): HTMLElement | null {
-  const HTMLElementCtor = document.defaultView?.HTMLElement;
   if (target.id) {
     const byId = document.getElementById(target.id);
     if (
-      HTMLElementCtor &&
-      byId instanceof HTMLElementCtor &&
+      isHtmlElement(byId) &&
       elementMatchesSourceFile(byId, target.sourceFile, activeCompositionPath)
     ) {
       return byId;
@@ -135,10 +130,8 @@ function restoreStudioMotionElement(element: HTMLElement, gsap: StudioMotionWind
 }
 
 function restoreStudioMotionElements(document: Document, gsap: StudioMotionWindow["gsap"]): void {
-  const HTMLElementCtor = document.defaultView?.HTMLElement;
-  if (!HTMLElementCtor) return;
   for (const element of Array.from(document.querySelectorAll(`[${STUDIO_MOTION_ATTR}]`))) {
-    if (element instanceof HTMLElementCtor) restoreStudioMotionElement(element, gsap);
+    if (isHtmlElement(element)) restoreStudioMotionElement(element, gsap);
   }
 }
 
@@ -238,11 +231,6 @@ export function applyStudioMotionFromDom(document: Document, currentTime?: numbe
   win.__timelines[STUDIO_MOTION_TIMELINE_ID]?.kill?.();
   delete win.__timelines[STUDIO_MOTION_TIMELINE_ID];
 
-  // Restore elements that had GSAP motion applied previously but whose attribute
-  // is now just the legacy marker "true" (i.e. they were restored/cleared).
-  const HTMLElementCtor = document.defaultView?.HTMLElement;
-  if (!HTMLElementCtor) return 0;
-
   // Collect elements that have JSON motion data in their attribute
   const motionElements: Array<{
     element: HTMLElement;
@@ -257,7 +245,7 @@ export function applyStudioMotionFromDom(document: Document, currentTime?: numbe
   }> = [];
 
   for (const el of Array.from(document.querySelectorAll(`[${STUDIO_MOTION_ATTR}]`))) {
-    if (!(el instanceof HTMLElementCtor)) continue;
+    if (!isHtmlElement(el)) continue;
     const motionData = readMotionAttr(el);
     if (motionData) {
       motionElements.push({ element: el, motion: motionData });