@hyperframes/studio 0.6.122-alpha.0 → 0.7.1

package/src/components/editor/motionPathCommit.ts

@@ -0,0 +1,83 @@
+/**
+ * Commit helpers for the motion-path overlay. Each maps a canvas gesture to a
+ * GSAP source mutation routed through the (selection-bound) commit facade, which
+ * handles the soft reload, undo snapshot, and save-failure feedback.
+ */
+import type { MotionNodeRef } from "./motionPathGeometry";
+
+export type CommitFn = (
+  mutation: Record<string, unknown>,
+  options: { label: string; softReload?: boolean },
+) => Promise<void>;
+
+const NEW_PATH_DURATION = 1.5;
+
+export function commitNode(
+  ref: MotionNodeRef,
+  x: number,
+  y: number,
+  animationId: string,
+  commit: CommitFn,
+): Promise<void> {
+  const mutation: Record<string, unknown> =
+    ref.type === "keyframe"
+      ? { type: "update-keyframe", animationId, percentage: ref.pct, properties: { x, y } }
+      : { type: "update-motion-path-point", animationId, pointIndex: ref.index, x, y };
+  return commit(mutation, {
+    label: ref.type === "keyframe" ? "Move keyframe" : "Move waypoint",
+    softReload: true,
+  });
+}
+
+export function commitAddWaypoint(
+  animationId: string,
+  index: number,
+  x: number,
+  y: number,
+  commit: CommitFn,
+): Promise<void> {
+  return commit(
+    { type: "add-motion-path-point", animationId, index, x, y },
+    { label: "Add waypoint", softReload: true },
+  );
+}
+
+export function commitAddKeyframe(
+  animationId: string,
+  percentage: number,
+  x: number,
+  y: number,
+  commit: CommitFn,
+): Promise<void> {
+  // percentage is tween-relative (matches MotionNodeRef.keyframe.pct). The parser's
+  // addKeyframeToScript inserts a new "P%": { x, y } stop (or merges if one exists
+  // at that pct) and converts a flat tween to keyframes form when needed.
+  return commit(
+    { type: "add-keyframe", animationId, percentage, properties: { x, y } },
+    { label: "Add keyframe", softReload: true },
+  );
+}
+
+export function commitRemoveWaypoint(
+  animationId: string,
+  index: number,
+  commit: CommitFn,
+): Promise<void> {
+  return commit(
+    { type: "remove-motion-path-point", animationId, index },
+    { label: "Remove waypoint", softReload: true },
+  );
+}
+
+export function commitCreatePath(
+  targetSelector: string,
+  position: number,
+  x: number,
+  y: number,
+  commit: CommitFn,
+): Promise<void> {
+  return commit(
+    { type: "add-motion-path", targetSelector, position, duration: NEW_PATH_DURATION, x, y },
+    { label: "Create motion path", softReload: true },
+  );
+}

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

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { buildMotionPathGeometry, nearestPointOnPath } from "./motionPathGeometry";
+import type { ReadTween } from "../../hooks/gsapRuntimeKeyframes";
+
+const kf = (percentage: number, x: number, y: number) => ({ percentage, properties: { x, y } });
+
+describe("buildMotionPathGeometry", () => {
+  it("builds a linear path with keyframe-ref nodes from an x/y tween", () => {
+    const read: ReadTween = { keyframes: [kf(0, 10, 20), kf(100, 200, 80)] };
+    const geo = buildMotionPathGeometry(read);
+    expect(geo).not.toBeNull();
+    expect(geo!.kind).toBe("linear");
+    expect(geo!.points).toBe("10,20 200,80");
+    expect(geo!.nodes).toEqual([
+      { x: 10, y: 20, ref: { type: "keyframe", pct: 0 } },
+      { x: 200, y: 80, ref: { type: "keyframe", pct: 100 } },
+    ]);
+  });
+
+  it("preserves order and percentages for intermediate keyframes", () => {
+    const read: ReadTween = { keyframes: [kf(0, 0, 0), kf(50, 50, 90), kf(100, 100, 0)] };
+    const geo = buildMotionPathGeometry(read);
+    expect(geo!.nodes.map((n) => n.ref)).toEqual([
+      { type: "keyframe", pct: 0 },
+      { type: "keyframe", pct: 50 },
+      { type: "keyframe", pct: 100 },
+    ]);
+  });
+
+  it("builds an arc path with waypoint-index refs when arcPath is present", () => {
+    const read: ReadTween = {
+      keyframes: [kf(0, 0, 0), kf(50, 60, 40), kf(100, 120, 10)],
+      arcPath: { enabled: true, autoRotate: false, segments: [{ curviness: 1 }, { curviness: 1 }] },
+    };
+    const geo = buildMotionPathGeometry(read);
+    expect(geo!.kind).toBe("arc");
+    expect(geo!.nodes.map((n) => n.ref)).toEqual([
+      { type: "waypoint", index: 0 },
+      { type: "waypoint", index: 1 },
+      { type: "waypoint", index: 2 },
+    ]);
+  });
+
+  it("returns null for a tween with no positional keyframes", () => {
+    const read: ReadTween = {
+      keyframes: [
+        { percentage: 0, properties: { opacity: 0 } },
+        { percentage: 100, properties: { opacity: 1 } },
+      ],
+    };
+    expect(buildMotionPathGeometry(read)).toBeNull();
+  });
+
+  it("draws a single-axis (x-only) tween, defaulting the missing axis to 0", () => {
+    // Regression: an `x`-only tween (e.g. `to({ x: -260 })`) carries no `y`, so the
+    // builder used to skip every node → no path until the user added the 2nd axis.
+    const read: ReadTween = {
+      keyframes: [
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: -260 } },
+      ],
+    };
+    const geo = buildMotionPathGeometry(read);
+    expect(geo).not.toBeNull();
+    expect(geo!.points).toBe("0,0 -260,0"); // y defaults to 0 → horizontal path
+  });
+
+  it("draws a y-only tween too (x defaults to 0)", () => {
+    const read: ReadTween = {
+      keyframes: [
+        { percentage: 0, properties: { y: 0 } },
+        { percentage: 100, properties: { y: 500 } },
+      ],
+    };
+    expect(buildMotionPathGeometry(read)!.points).toBe("0,0 0,500");
+  });
+
+  it("excludes keyframes missing a coordinate without throwing", () => {
+    const read: ReadTween = {
+      keyframes: [kf(0, 10, 20), { percentage: 50, properties: { x: 100 } }, kf(100, 200, 80)],
+    };
+    const geo = buildMotionPathGeometry(read);
+    expect(geo!.nodes).toHaveLength(2);
+    expect(geo!.points).toBe("10,20 200,80");
+  });
+
+  it("returns null when fewer than two valid nodes remain", () => {
+    const read: ReadTween = { keyframes: [kf(0, 10, 20)] };
+    expect(buildMotionPathGeometry(read)).toBeNull();
+  });
+
+  it("returns null for null input", () => {
+    expect(buildMotionPathGeometry(null)).toBeNull();
+  });
+});
+
+describe("nearestPointOnPath", () => {
+  const nodes = [
+    { x: 0, y: 0 },
+    { x: 100, y: 0 },
+    { x: 100, y: 100 },
+  ];
+
+  it("projects onto the nearest segment and reports its index + fraction", () => {
+    const p = nearestPointOnPath(50, 20, nodes);
+    expect(p).toEqual({ x: 50, y: 0, segIndex: 0, t: 0.5, dist: 20 });
+  });
+
+  it("reports t at the segment endpoints (0 at start, clamps to 1 past the end)", () => {
+    expect(nearestPointOnPath(0, 5, nodes)).toMatchObject({ segIndex: 0, t: 0 });
+    expect(nearestPointOnPath(110, 0, nodes)).toMatchObject({ segIndex: 0, t: 1 });
+  });
+
+  it("picks the second segment when closer to it", () => {
+    const p = nearestPointOnPath(120, 50, nodes);
+    expect(p).toMatchObject({ x: 100, y: 50, segIndex: 1 });
+  });
+
+  it("clamps to an endpoint when the projection falls past the segment", () => {
+    const p = nearestPointOnPath(-40, -10, nodes);
+    expect(p).toMatchObject({ x: 0, y: 0, segIndex: 0 });
+  });
+
+  it("returns null for fewer than two nodes", () => {
+    expect(nearestPointOnPath(0, 0, [{ x: 0, y: 0 }])).toBeNull();
+  });
+});

package/src/components/editor/motionPathGeometry.ts

@@ -0,0 +1,116 @@
+/**
+ * Convert a live tween (from `readRuntimeKeyframes`) into renderable motion-path
+ * geometry for the on-canvas overlay. Pure — no React/DOM — so it unit-tests in
+ * isolation. Coordinates are in composition space (the same space the overlay's
+ * viewBox uses), so the caller renders nodes/points directly.
+ */
+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: "waypoint"; index: number }; // motionPath waypoint (anchor) at this index
+
+export interface MotionPathNode {
+  x: number;
+  y: number;
+  ref: MotionNodeRef;
+}
+
+export interface MotionPathGeometry {
+  /** "linear" = x/y keyframes; "arc" = motionPath tween. */
+  kind: "linear" | "arc";
+  /** SVG polyline points: "x,y x,y ...". */
+  points: string;
+  nodes: MotionPathNode[];
+}
+
+/**
+ * Build motion-path geometry, or null when the tween carries no positional path
+ * (fewer than two keyframes with both x and y). For motionPath tweens the
+ * keyframes are the arc waypoints (anchors), index-aligned with the source path
+ * — so a waypoint node at index `i` rewrites source waypoint `i`.
+ *
+ * ponytail: the arc is drawn as a polyline through its waypoints (matching the
+ * angular dotted look of the reference), not GSAP's resolved curve. Dense
+ * curve sampling is a later refinement if the straight-segment preview proves
+ * insufficient.
+ */
+/**
+ * Nearest point on a polyline to (px, py), with the index of the segment it
+ * lies on and `t` = how far along that segment the returned point sits.
+ *
+ * `t` semantics: clamped to the inclusive range [0, 1].
+ *   - `t === 0` → the point is at (or projects before) the segment's start node
+ *     (`segIndex`); a perpendicular dropped from (px, py) falls at or behind `a`.
+ *   - `0 < t < 1` → the point is strictly interior to the segment.
+ *   - `t === 1` → the point is at (or projects PAST) the segment's end node
+ *     (`segIndex + 1`); past-the-end projections are clamped back onto the endpoint,
+ *     so the returned (x, y) is exactly `nodes[segIndex + 1]`. Callers can read
+ *     `t === 1` as "snapped to the end anchor of this segment" (equivalently, the
+ *     start anchor of the next segment).
+ * A degenerate zero-length segment (`a === b`) yields `t === 0`.
+ *
+ * Used to position the ghost "add" node and decide where a new node goes: a
+ * motionPath waypoint inserts between `segIndex`/`segIndex + 1`, a keyframe
+ * interpolates its tween-% from the two adjacent keyframes via `t`.
+ * Coordinates are whatever space the caller passes (overlay uses absolute px).
+ */
+export function nearestPointOnPath(
+  px: number,
+  py: number,
+  nodes: Array<{ x: number; y: number }>,
+): { x: number; y: number; segIndex: number; t: number; dist: number } | null {
+  if (nodes.length < 2) return null;
+  let best: { x: number; y: number; segIndex: number; t: number; dist: number } | null = null;
+  for (let i = 0; i < nodes.length - 1; i++) {
+    const a = nodes[i]!;
+    const b = nodes[i + 1]!;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const len2 = dx * dx + dy * dy;
+    const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((px - a.x) * dx + (py - a.y) * dy) / len2));
+    const cx = a.x + t * dx;
+    const cy = a.y + t * dy;
+    const dist = Math.hypot(px - cx, py - cy);
+    if (!best || dist < best.dist) best = { x: cx, y: cy, segIndex: i, t, dist };
+  }
+  return best;
+}
+
+export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeometry | null {
+  if (!read) return null;
+  const isArc = Boolean(read.arcPath);
+  const nodes: MotionPathNode[] = [];
+
+  // Index by source position so a waypoint node maps to the matching source
+  // anchor. Arc waypoints always carry x/y (never filtered), so source index
+  // and node order stay aligned.
+  // Which axes does the tween animate at all? A single-axis tween (e.g.
+  // `to({ x: -260 })`) only carries x; its y stays at the base (0, the GSAP
+  // transform identity), 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));
+  if (!tweenHasX && !tweenHasY) return null; // no positional motion (opacity/scale only)
+
+  read.keyframes.forEach((kf, i) => {
+    if (tweenHasX && !finite(kf.properties.x)) return;
+    if (tweenHasY && !finite(kf.properties.y)) return;
+    nodes.push({
+      x: tweenHasX ? (kf.properties.x as number) : 0,
+      y: tweenHasY ? (kf.properties.y as number) : 0,
+      ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
+    });
+  });
+
+  if (nodes.length < 2) return null;
+
+  return {
+    kind: isArc ? "arc" : "linear",
+    points: nodes.map((n) => `${n.x},${n.y}`).join(" "),
+    nodes,
+  };
+}

package/src/components/editor/motionPathSelection.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolving the selected element and the animation whose path is editable.
+ * Shared by the overlay and its diagnostics (kept here to avoid a circular
+ * import between the two).
+ */
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "./domEditing";
+
+export function selectorFor(sel: DomEditSelection | null): string | null {
+  if (!sel) return null;
+  if (sel.id) return `#${CSS.escape(sel.id)}`;
+  return sel.selector ?? null;
+}
+
+/** The animation whose path is editable on-canvas: literal, statically resolved,
+ *  and matching the rendered geometry kind. Returns null when the path can only
+ *  be displayed (dynamic/helper tweens) — those nodes stay read-only. */
+export function editableAnimationId(
+  animations: GsapAnimation[],
+  kind: "linear" | "arc",
+): string | null {
+  const ok = (a: GsapAnimation) =>
+    !a.hasUnresolvedKeyframes && !a.hasUnresolvedSelector && !a.provenance;
+  if (kind === "arc") return animations.find((a) => a.arcPath?.enabled && ok(a))?.id ?? null;
+  const a = animations.find(
+    (anim) =>
+      anim.keyframes &&
+      ok(anim) &&
+      (anim.propertyGroup === "position" ||
+        anim.keyframes.keyframes.some((k) => "x" in k.properties || "y" in k.properties)),
+  );
+  return a?.id ?? null;
+}

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -9,6 +9,7 @@ import { type DomEditSelection } from "./domEditing";
 import {
   applyManualOffsetDragCommit,
   applyManualOffsetDragDraft,
+  applyRotationDraftViaGsap,
   endManualOffsetDragMembers,
   restoreManualOffsetDragMembers,
   resumeGsapTimelines,
@@ -161,19 +162,21 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     let dy = e.clientY - g.startY;
 
     if (g.kind === "rotate") {
-      applyStudioRotationDraft(
-        sel.element,
-        resolveDomEditRotationGesture({
-          centerX: g.centerX,
-          centerY: g.centerY,
-          startX: g.startX,
-          startY: g.startY,
-          currentX: e.clientX,
-          currentY: e.clientY,
-          actualAngle: g.actualRotation,
-          snap: e.shiftKey,
-        }),
-      );
+      // Single source of truth: preview the rotation through the GSAP channel (the
+      // same channel the commit lands in), not the `--hf-studio-rotation` CSS var.
+      const rotated = resolveDomEditRotationGesture({
+        centerX: g.centerX,
+        centerY: g.centerY,
+        startX: g.startX,
+        startY: g.startY,
+        currentX: e.clientX,
+        currentY: e.clientY,
+        actualAngle: g.actualRotation,
+        snap: e.shiftKey,
+      });
+      if (!applyRotationDraftViaGsap(sel.element, rotated.angle)) {
+        applyStudioRotationDraft(sel.element, rotated);
+      }
       return;
     }
 
@@ -393,25 +396,38 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualAngle: g.actualRotation,
         snap: e.shiftKey,
       });
+      const restoreRotation = () => {
+        // Single source of truth: snap the GSAP rotation back to the gesture's base
+        // angle; fall back to the legacy CSS-var restore when gsap is unavailable.
+        if (!applyRotationDraftViaGsap(sel.element, g.actualRotation)) {
+          restoreStudioRotation(sel.element, g.initialRotation);
+        }
+      };
       if (!hasDomEditRotationChanged(g.actualRotation, finalRotation.angle)) {
-        restoreStudioRotation(sel.element, g.initialRotation);
+        restoreRotation();
         endStudioManualEditGesture(sel.element, g.manualEditDragToken);
         return;
       }
-      applyStudioRotation(sel.element, finalRotation);
+      // Keep the preview at the final angle through the GSAP channel (NOT the CSS var)
+      // while the commit lands a `tl.set`/keyframe rotation on the timeline.
+      if (!applyRotationDraftViaGsap(sel.element, finalRotation.angle)) {
+        applyStudioRotation(sel.element, finalRotation);
+      }
       void Promise.resolve(opts.onRotationCommitRef.current(sel, finalRotation))
         .catch(() => {
           if (
             g.manualEditDragToken &&
             isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
           )
-            restoreStudioRotation(sel.element, g.initialRotation);
+            restoreRotation();
         })
         .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
     } else if (g.kind === "drag") {
       const dx = g.lastSnappedDx ?? e.clientX - g.startX;
       const dy = g.lastSnappedDy ?? e.clientY - g.startY;
-      if (!g.pathOffsetMember) return;
+      if (!g.pathOffsetMember) {
+        return;
+      }
       const finalOffset = applyManualOffsetDragCommit(g.pathOffsetMember, dx, dy);
       const nextBoxLeft = g.originLeft + dx;
       const nextBoxTop = g.originTop + dy;
@@ -427,7 +443,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         box.style.left = `${nextBoxLeft}px`;
         box.style.top = `${nextBoxTop}px`;
       }
-      void Promise.resolve(opts.onPathOffsetCommitRef.current(sel, finalOffset))
+      void Promise.resolve(
+        opts.onPathOffsetCommitRef.current(sel, finalOffset, { altKey: e.altKey }),
+      )
         .catch(() => {
           if (
             g.pathOffsetMember?.gestureToken &&

package/src/components/editor/useDomEditOverlayRects.ts

@@ -148,6 +148,12 @@ export function useDomEditOverlayRects({
           activeCompositionPathRef.current,
           resolvedElementRef as ResolvedElementRef,
         );
+        // An explicitly-selected element's overlay must track it whenever it's laid
+        // out and not display:none/visibility:hidden/opacity:0 — use basic visibility,
+        // NOT the occlusion heuristic. Occlusion (isElementVisibleInPreview) treats any
+        // opacity:1 ancestor as an opaque cover even when it paints nothing (e.g. a
+        // backgroundless full-bleed scene above a subcomposition), which would wrongly
+        // hide the selection box. Occlusion stays for hover, where a false hide is cheap.
         if (el && isElementVisibleForOverlay(el)) {
           const nextRect = toOverlayRect(overlayEl, iframe, el);
           setOverlayRect(nextRect);

package/src/components/editor/useMotionPathData.ts

@@ -0,0 +1,135 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
+import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
+import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
+
+type Rect = { left: number; top: number; width: number; height: number };
+
+export function elementHome(el: HTMLElement): { x: number; y: number } {
+  let left = 0;
+  let top = 0;
+  let node: HTMLElement | null = el;
+  while (node) {
+    left += node.offsetLeft;
+    top += node.offsetTop;
+    const parent = node.offsetParent as HTMLElement | null;
+    if (!parent || parent.hasAttribute("data-composition-id")) break;
+    node = parent;
+  }
+  let x = left + el.offsetWidth / 2;
+  let y = top + el.offsetHeight / 2;
+  if ((el.style.translate ?? "").includes("var(")) {
+    x += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-x")) || 0;
+    y += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-y")) || 0;
+  }
+  return { x, y };
+}
+
+export function isPreviewHtmlElement(
+  node: Element | null | undefined,
+  iframe: HTMLIFrameElement | null,
+): node is HTMLElement {
+  const Ctor = (iframe?.contentWindow as unknown as { HTMLElement?: typeof HTMLElement } | null)
+    ?.HTMLElement;
+  return Boolean(node && Ctor && node instanceof Ctor);
+}
+
+function rectsClose(a: Rect, b: Rect): boolean {
+  return (
+    Math.abs(a.left - b.left) < 0.5 &&
+    Math.abs(a.top - b.top) < 0.5 &&
+    Math.abs(a.width - b.width) < 0.5 &&
+    Math.abs(a.height - b.height) < 0.5
+  );
+}
+
+export function hasMotionPathPlugin(iframe: HTMLIFrameElement | null): boolean {
+  try {
+    return Boolean(
+      (iframe?.contentWindow as unknown as { MotionPathPlugin?: unknown })?.MotionPathPlugin,
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function useMotionPathData(
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+  selector: string | null,
+): {
+  rect: Rect | null;
+  geometry: MotionPathGeometry | null;
+  geometryResolved: boolean;
+  visibleInPreview: boolean;
+  home: { x: number; y: number } | null;
+} {
+  const [rect, setRect] = useState<Rect | null>(null);
+  const [geometry, setGeometry] = useState<MotionPathGeometry | null>(null);
+  const resolvedForRef = useRef<string | null>(null);
+  const geometryResolved = resolvedForRef.current === selector;
+  const [visibleInPreview, setVisibleInPreview] = useState(true);
+  const [home, setHome] = useState<{ x: number; y: number } | null>(null);
+
+  useEffect(() => {
+    if (!selector) {
+      setRect(null);
+      setHome(null);
+      return;
+    }
+    setHome(null);
+    let raf = 0;
+    const tick = () => {
+      const el = iframeRef.current;
+      if (el) {
+        const r = el.getBoundingClientRect();
+        const surface = el.ownerDocument?.querySelector("[data-preview-pan-surface]");
+        const sRect = surface?.getBoundingClientRect();
+        const next = {
+          left: sRect ? r.left - sRect.left : r.left,
+          top: sRect ? r.top - sRect.top : r.top,
+          width: r.width,
+          height: r.height,
+        };
+        setRect((prev) => (prev && rectsClose(prev, next) ? prev : next));
+        let target: Element | null = null;
+        try {
+          target = el.contentDocument?.querySelector(selector) ?? null;
+        } catch {
+          /* cross-origin guard */
+        }
+        const live = isPreviewHtmlElement(target, el) ? target : null;
+        const vis = live ? isElementVisibleForOverlay(live) : true;
+        setVisibleInPreview((prev) => (prev === vis ? prev : vis));
+        if (live) {
+          const h = elementHome(live);
+          setHome((prev) =>
+            prev && Math.abs(prev.x - h.x) < 0.5 && Math.abs(prev.y - h.y) < 0.5 ? prev : h,
+          );
+        }
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [selector, iframeRef]);
+
+  useEffect(() => {
+    if (!selector) {
+      setGeometry(null);
+      return;
+    }
+    const recompute = () => {
+      const read = readRuntimeKeyframes(iframeRef.current, selector);
+      const next = buildMotionPathGeometry(read);
+      setGeometry((prev) =>
+        prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
+      );
+      resolvedForRef.current = selector;
+    };
+    recompute();
+    const id = window.setInterval(recompute, 250);
+    return () => window.clearInterval(id);
+  }, [selector, iframeRef]);
+
+  return { rect, geometry, geometryResolved, visibleInPreview, home };
+}

package/src/components/nle/NLELayout.tsx

@@ -16,11 +16,13 @@ import { CompositionBreadcrumb } from "./CompositionBreadcrumb";
 import { usePreviewBlockDrop } from "./usePreviewBlockDrop";
 import { useCompositionStack } from "./useCompositionStack";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
+import { setCompositionSourceMap } from "../editor/domEditingDom";
 import { trackStudioExpandedClipEdit } from "../../telemetry/events";
 import {
   TIMELINE_TOGGLE_SHORTCUT_LABEL,
   getTimelineToggleTitle,
 } from "../../utils/timelineDiscovery";
+import { ensureMotionPathPluginLoaded } from "../../utils/gsapSoftReload";
 
 interface NLELayoutProps {
   projectId: string;
@@ -122,12 +124,14 @@ export const NLELayout = memo(function NLELayout({
     refreshPlayer,
   } = useTimelinePlayer();
 
-  // Reset timeline state when the project changes
-  const prevProjectIdRef = useRef(projectId);
-  if (prevProjectIdRef.current !== projectId) {
-    prevProjectIdRef.current = projectId;
+  // Reset timeline state when the project changes. Done in an effect, not during
+  // render: reset() updates the player store, and updating another store/component
+  // mid-render triggers React's "Cannot update a component while rendering a
+  // different component" warning. The effect runs right after commit, so the new
+  // project's first frame may briefly show prior timeline state before it clears.
+  useEffect(() => {
     usePlayerStore.getState().reset();
-  }
+  }, [projectId]);
 
   const stageRefForDrop = useRef<HTMLDivElement | null>(null);
   const handleStageRef = useCallback((ref: React.RefObject<HTMLDivElement | null>) => {
@@ -158,6 +162,10 @@ export const NLELayout = memo(function NLELayout({
 
   const onIframeLoad = useCallback(() => {
     baseOnIframeLoad();
+    // Pre-load + register MotionPathPlugin once so adding a motion path in the
+    // studio doesn't take the async plugin-load flash path on the first soft
+    // reload (the comp may not ship the plugin until it actually uses one).
+    ensureMotionPathPluginLoaded(iframeRef.current);
     onIframeRef?.(iframeRef.current);
   }, [baseOnIframeLoad, iframeRef, onIframeRef]);
 
@@ -294,6 +302,9 @@ export const NLELayout = memo(function NLELayout({
           if (id && src) map.set(id, src);
         }
         setCompIdToSrc(map);
+        // Let DOM source-resolution recover a subcomposition element's source file
+        // (the runtime drops the linkage when inlining — see getSourceFileForElement).
+        setCompositionSourceMap(map);
         onCompIdToSrcChange?.(map);
       })
       .catch(() => {});
@@ -427,7 +438,7 @@ export const NLELayout = memo(function NLELayout({
       {/* Preview + player controls */}
       <div className="flex-1 min-h-0 flex flex-col">
         <div
-          className="flex-1 min-h-0 relative"
+          className="flex-1 min-h-0 relative overflow-hidden"
           data-preview-pan-surface="true"
           onPointerDown={(e) => {
             const el = iframeRef.current?.parentElement ?? iframeRef.current;