@hyperframes/studio 0.8.125 → 0.8.126

package/src/components/editor/useMotionPathData.test.tsx

@@ -1,7 +1,9 @@
 // @vitest-environment happy-dom
+import { gsap } from "gsap";
 import { act, useRef } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { elementHome } from "./motionPathHome";
 import { useMotionPathData } from "./useMotionPathData";
 import { resetOverlayFrameLoopForTests } from "./overlayFrameLoop";
 import { usePlayerStore } from "../../player/store/playerStore";
@@ -92,3 +94,237 @@ it("reads no layout per frame until there is a path or a create ring to draw", (
     act(() => root.unmount());
   }
 });
+
+it("finds the layer whichever window built its node, so the path draws on every load", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 100, y: 0 } },
+    ],
+  };
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const box = iframe.contentDocument!.createElement("div");
+  box.id = "box";
+  iframe.contentDocument!.body.append(box);
+  // happy-dom shares one realm, so the frame's own constructor stands in for another window's.
+  Object.defineProperty(iframe.contentWindow!, "HTMLElement", { value: class {} });
+  let home: unknown = null;
+  function Probe() {
+    const ref = useRef(iframe);
+    home = useMotionPathData(ref, "#box").home;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    runFrames(3);
+    expect(home).not.toBeNull();
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+it("redraws a node whose keyframe changes only its size", () => {
+  const read = (width: number) => ({
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60, width } },
+      { percentage: 100, properties: { x: 120, width: 320 } },
+    ],
+  });
+  runtime.read = read(280);
+  runtime.gsapPosition = { x: 50, y: 30 };
+  let w: number | undefined;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    w = useMotionPathData(ref, "#box").geometry?.nodes[0]?.w;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(w).toBe(280);
+    runtime.read = read(300);
+    act(() => vi.advanceTimersByTime(250));
+    expect(w).toBe(300);
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+/** A layer laid out at (960, 540), 240 x 160, with `css` inline and `cache` as GSAP's `_gsap`. */
+function layer(css: Partial<CSSStyleDeclaration>, cache?: Record<string, number>) {
+  const el = document.body.appendChild(document.createElement("div"));
+  Object.assign(el.style, css);
+  const box = {
+    offsetLeft: 960,
+    offsetTop: 540,
+    offsetWidth: 240,
+    offsetHeight: 160,
+    offsetParent: null,
+  };
+  for (const [key, value] of Object.entries(box)) Object.defineProperty(el, key, { value });
+  return cache ? Object.assign(el, { _gsap: cache }) : el;
+}
+
+it("anchors a layer GSAP centres with xPercent/yPercent -50 on its centre", () => {
+  const el = layer(
+    { position: "absolute", left: "50%", top: "50%" },
+    { x: 0, y: 0, xPercent: -50, yPercent: -50 },
+  );
+  expect(elementHome(el)).toEqual({ x: 960, y: 540, w: 240, h: 160, ax: 0, ay: 0 });
+});
+
+it("moves a resized layer's centre by half the change from a set left, against it from a set right, and not in flow", () => {
+  const fromLeft = layer({ position: "absolute", left: "10px", top: "10px" });
+  expect(elementHome(fromLeft)).toMatchObject({ x: 1080, y: 620, ax: 0.5, ay: 0.5 });
+  const fromRight = layer({ position: "absolute", right: "10px", bottom: "10px" });
+  const auto = new Set(["left", "top"]);
+  fromRight.computedStyleMap = () =>
+    ({
+      get: (side: string) => (auto.has(side) ? "auto" : "10px"),
+    }) as unknown as StylePropertyMapReadOnly;
+  expect(elementHome(fromRight)).toMatchObject({ ax: -0.5, ay: -0.5 });
+  expect(elementHome(layer({}))).toMatchObject({ x: 1080, ax: 0, ay: 0 });
+});
+
+const resolved = (style: CSSStyleDeclaration) =>
+  (style.translate ?? "").replace(/var\((--[\w-]+)\)/g, (_, name) =>
+    style.getPropertyValue(name),
+  ) || "none";
+
+/** Computes `translate` and `transform` as Chromium does (happy-dom does not), so GSAP's parse would fold them. */
+function computeTranslate() {
+  const real = window.getComputedStyle.bind(window);
+  const computed = (node: Element, pseudo?: string | null) =>
+    new Proxy(real(node, pseudo), {
+      get(style, key) {
+        if (key === "translate") return resolved((node as HTMLElement).style);
+        if (key === "transform") return (node as HTMLElement).style.transform || "none";
+        if (key === "scale" || key === "rotate") return "none";
+        const value = Reflect.get(style, key);
+        return typeof value === "function" ? value.bind(style) : value;
+      },
+    });
+  vi.stubGlobal("getComputedStyle", computed);
+  vi.spyOn(window, "getComputedStyle").mockImplementation(
+    computed as typeof window.getComputedStyle,
+  );
+}
+
+it("leaves a layer's CSS translate alone and anchors where GSAP's parse will put it (real GSAP)", () => {
+  vi.stubGlobal("gsap", gsap);
+  computeTranslate();
+  try {
+    const offset = "var(--hf-studio-offset-x) var(--hf-studio-offset-y)";
+    const cases: [string, number, number][] = [
+      // GSAP folds these into x, which a created path sets.
+      ["40px 30px", 1080, 620],
+      [offset, 1080, 620],
+      // Minus half the size becomes xPercent/yPercent -50.
+      ["-50% -50%", 960, 540],
+      ["-120px -80px", 960, 540],
+    ];
+    // GSAP sums the layer's own transform with its translate: Chromium's matrix for translate(-50%, -50%).
+    const centred = layer({ position: "absolute", transform: "matrix(1, 0, 0, 1, -120, -80)" });
+    expect(elementHome(centred)).toMatchObject({ x: 960, y: 540 });
+    for (const [translate, x, y] of cases) {
+      const el = layer({ position: "absolute", left: "10px", top: "10px", translate });
+      el.style.setProperty("--hf-studio-offset-x", "40px");
+      el.style.setProperty("--hf-studio-offset-y", "30px");
+      expect(elementHome(el), translate).toMatchObject({ x, y });
+      expect([el.style.translate, el.style.transform]).toEqual([translate, ""]);
+    }
+    // A drag's offset on a layer GSAP already parsed composes with its transform.
+    const dragged = layer({ position: "absolute", left: "10px", top: "10px" });
+    gsap.set(dragged, { x: 20 });
+    dragged.style.setProperty("--hf-studio-offset-x", "40px");
+    dragged.style.setProperty("--hf-studio-offset-y", "30px");
+    dragged.style.translate = offset;
+    expect(elementHome(dragged)).toMatchObject({ x: 1120, y: 650 });
+    // After clearProps GSAP marks its cache uncache and its next parse folds the translate again.
+    const css = { position: "absolute", left: "10px", top: "10px", translate: "40px 30px" };
+    expect(elementHome(layer(css, { x: 0, y: 0, uncache: 1 }))).toMatchObject({ x: 1080, y: 620 });
+    // A fade gives GSAP a cache with no transform in it yet, so its next parse still folds.
+    expect(elementHome(layer(css, { opacity: 1 }))).toMatchObject({ x: 1080, y: 620 });
+    const owned = layer({ position: "absolute", left: "50%", top: "50%" });
+    gsap.set(owned, { xPercent: -50, yPercent: -50 });
+    expect(elementHome(owned)).toMatchObject({ x: 960, y: 540, ax: 0, ay: 0 });
+  } finally {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  }
+});
+
+it("redraws the start ring when only GSAP's start changes", () => {
+  const read = (start?: Record<string, number>) => ({
+    keyframes: [
+      { percentage: 50, properties: { x: 60 } },
+      { percentage: 100, properties: { x: 120 } },
+    ],
+    ...(start && { start }),
+  });
+  runtime.read = read();
+  runtime.gsapPosition = { x: 50, y: 30 };
+  let start: unknown;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    start = useMotionPathData(ref, "#box").geometry?.start;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(start).toBeUndefined();
+    runtime.read = read({ x: 40 });
+    act(() => vi.advanceTimersByTime(250));
+    expect(start).toEqual({ x: 40, y: 30 });
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+it("updates the home when the layer's size or anchoring changes but its centre does not", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 0, width: 200 } },
+      { percentage: 100, properties: { x: 100, width: 240 } },
+    ],
+  };
+  const iframe = document.body.appendChild(document.createElement("iframe"));
+  const layout = { offsetLeft: 100, offsetWidth: 200 };
+  const box = iframe.contentDocument!.body.appendChild(
+    iframe.contentDocument!.createElement("div"),
+  );
+  box.id = "box";
+  for (const key of ["offsetLeft", "offsetWidth"] as const)
+    Object.defineProperty(box, key, { get: () => layout[key] });
+  let w: number | undefined;
+  let ax: number | undefined;
+  function Probe() {
+    const ref = useRef(iframe);
+    ({ w, ax } = useMotionPathData(ref, "#box").home ?? {});
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    runFrames(2);
+    expect(w).toBe(200);
+    Object.assign(layout, { offsetLeft: 80, offsetWidth: 240 });
+    runFrames(2);
+    expect(w).toBe(240);
+    // Re-anchored from the left to the right edge without moving: the share a size change moves changes.
+    Object.assign(box.style, { position: "absolute", left: "10px" });
+    runFrames(2);
+    expect(ax).toBe(0.5);
+    box.computedStyleMap = () =>
+      ({
+        get: (side: string) => (side === "left" ? "auto" : "0px"),
+      }) as unknown as StylePropertyMapReadOnly;
+    runFrames(2);
+    expect(ax).toBe(-0.5);
+  } finally {
+    act(() => root.unmount());
+  }
+});

package/src/components/editor/useMotionPathData.ts

@@ -1,31 +1,19 @@
 import { useEffect, useRef, useState, type RefObject } from "react";
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
 import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
-import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
+import {
+  buildMotionPathGeometry,
+  type MotionPathGeometry,
+  type MotionPathHome,
+} from "./motionPathGeometry";
+import { elementHome } from "./motionPathHome";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
 import { usePlayerStore } from "../../player/store/playerStore";
 
 type Rect = { left: number; top: number; width: number; height: number };
 
-// The translate (e/f) components of an element's computed transform, in comp px.
-// A group wrapper dragged via GSAP carries its offset here, not in offsetLeft/Top.
-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 };
-}
-
 // Perspective foreshortening of the element's OWN transform (matrix3d m44). A
 // depth element (translateZ toward the viewer) renders 1/m44× larger, so its
 // animated x/y offsets travel 1/m44× further on screen than the flat preview
@@ -40,43 +28,6 @@ export function transformWDivisor(el: HTMLElement): number {
   return Number.isFinite(w) && w > 0 ? w : 1;
 }
 
-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;
-    // Ancestor transforms (e.g. a group wrapper moved via GSAP) shift where the
-    // element actually renders, so the path must anchor on top of them. The element's
-    // OWN transform is excluded — that's the animated offset the path itself draws.
-    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;
-  }
-  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 &&
@@ -104,7 +55,7 @@ export function useMotionPathData(
   geometry: MotionPathGeometry | null;
   geometryResolved: boolean;
   visibleInPreview: boolean;
-  home: { x: number; y: number } | null;
+  home: MotionPathHome | null;
   pScale: number;
 } {
   const [rect, setRect] = useState<Rect | null>(null);
@@ -112,7 +63,7 @@ export function useMotionPathData(
   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);
+  const [home, setHome] = useState<MotionPathHome | null>(null);
   // Perspective magnification (1/m44) of the selected element — applied to the
   // path's offset points so depth (translateZ) elements' paths track on screen.
   const [pScale, setPScale] = useState(1);
@@ -146,13 +97,21 @@ export function useMotionPathData(
         } catch {
           /* cross-origin guard */
         }
-        const live = isPreviewHtmlElement(target, el) ? target : null;
+        const live = isHtmlElement(target) ? 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,
+            prev &&
+            Math.abs(prev.x - h.x) < 0.5 &&
+            Math.abs(prev.y - h.y) < 0.5 &&
+            prev.w === h.w &&
+            prev.h === h.h &&
+            prev.ax === h.ax &&
+            prev.ay === h.ay
+              ? prev
+              : h,
           );
           const ps = 1 / transformWDivisor(live);
           setPScale((p) => (Math.abs(p - ps) < 0.001 ? p : ps));
@@ -173,7 +132,10 @@ export function useMotionPathData(
       const base = read ? readGsapPositionFromIframe(iframeRef.current, selector) : null;
       const next = buildMotionPathGeometry(read, base ?? undefined);
       setGeometry((prev) =>
-        prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
+        prev?.kind === next?.kind &&
+        JSON.stringify([prev?.nodes, prev?.start]) === JSON.stringify([next?.nodes, next?.start])
+          ? prev
+          : next,
       );
       resolvedForRef.current = selector;
     };

package/src/components/sidebar/CompositionsTab.thumbnails.test.tsx

@@ -39,6 +39,7 @@ class ViewportObserver {
     const entry = { isIntersecting: true } as IntersectionObserverEntry;
     this.callback([entry], this as unknown as IntersectionObserver);
   }
+  unobserve() {}
   disconnect() {}
 }
 

package/src/hooks/gsapParsedTween.ts

@@ -2,6 +2,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { elementTargets } from "../utils/elementGsap";
 import { resolveTweenStart } from "../utils/globalTimeCompiler";
 import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
+import type { ReadTween } from "./gsapRuntimeKeyframes";
 
 // GSAP 3 internals: a property tween in a tween's `_pt` chain; CSSPlugin keeps its own under `d._pt`.
 interface PropTween {
@@ -57,6 +58,21 @@ function endsIn(tween: ParsedTween, prop: string): [number, number] | null {
   return tween._from ? [pair[1], pair[0]] : pair;
 }
 
+/** `read` plus GSAP's start for a step list or a first key past 0%, read per channel. */
+export function withParsedStart(read: ReadTween, live: unknown): ReadTween {
+  const tween = live as ParsedTween;
+  const first = read.keyframes[0];
+  if (!Array.isArray(tween.vars?.keyframes) && !((first?.percentage ?? 0) > 0)) return read;
+  const children = tween.timeline?.getChildren?.() ?? [tween];
+  const start: Record<string, number> = {};
+  for (const prop of ["x", "y", "width", "height"]) {
+    const ends = children.map((child) => endsIn(child, prop)).find(Boolean);
+    if (ends) start[prop] = ends[0];
+  }
+  const moved = Object.entries(start).some(([prop, value]) => value !== first?.properties[prop]);
+  return moved ? { ...read, start } : read;
+}
+
 /** The live tween GSAP built from `anim`: same element, start and channels, parsed. */
 // fallow-ignore-next-line complexity
 export function findParsedTween(

package/src/hooks/gsapRuntimeKeyframes.realGsap.test.ts

@@ -0,0 +1,48 @@
+// @vitest-environment happy-dom
+import { gsap } from "gsap";
+import { expect, it } from "vitest";
+import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+
+/** The edit bench's `keys` layer: GSAP starts it at x 40, 260 wide, and plays it to 1 s. */
+function read(keyframes: string) {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  box.style.width = "260px";
+  gsap.set(box, { x: 40 });
+  const win = { __timelines: {} as Record<string, gsap.core.Timeline> };
+  new Function(
+    "gsap",
+    "window",
+    `var tl = gsap.timeline({ paused: true });
+tl.to("#x", { keyframes: ${keyframes} }, 0);
+window.__timelines["t"] = tl;`,
+  )(gsap, win);
+  const timeline = win.__timelines.t!;
+  timeline.progress(0.0001, true).seek(1);
+  const iframe = { contentWindow: { ...win, gsap }, contentDocument: document };
+  const got = readRuntimeKeyframes(iframe as unknown as HTMLIFrameElement, "#x");
+  timeline.kill();
+  box.remove();
+  return got;
+}
+
+it("reads where GSAP started a step list whose first keyframe comes later", () => {
+  const got = read(
+    `[{ x: 60, width: 280, duration: 2, ease: "none" }, { x: 120, width: 320, duration: 1, ease: "none" }]`,
+  );
+  expect(got?.start).toEqual({ x: 40, width: 260 });
+});
+
+it.each([
+  [`{ "50%": { x: 60, y: 20 }, "100%": { x: 120, y: 40 } }, duration: 2`, { x: 40, y: 0 }],
+  [
+    `{ "50%": { x: 60, width: 280 }, "100%": { x: 120, width: 320 } }, duration: 2`,
+    { x: 40, width: 260 },
+  ],
+])("reads every channel's start for a percentage list past 0%: %s", (keyframes, start) => {
+  expect(read(keyframes)?.start).toEqual(start);
+});
+
+it("reads no start for keyframes that begin at 0%, or a step list that begins where GSAP started", () => {
+  expect(read(`{ "0%": { x: 10 }, "100%": { x: 120 } }, duration: 3`)?.start).toBeUndefined();
+  expect(read(`[{ x: 40, duration: 0 }, { x: 120, duration: 1 }]`)?.start).toBeUndefined();
+});

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -11,6 +11,7 @@
 import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
+import { withParsedStart } from "./gsapParsedTween";
 import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
 import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
 
@@ -43,7 +44,13 @@ export interface RuntimeTimeline {
 }
 
 type Pct = { percentage: number; properties: Record<string, number | string> };
-export type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+export type ReadTween = {
+  keyframes: Pct[];
+  easeEach?: string;
+  arcPath?: ArcPathConfig;
+  /** GSAP's start values when the first keyframe is after 0%. */
+  start?: Record<string, number>;
+};
 
 export interface RuntimeKeyframeEntry {
   keyframes: Pct[];
@@ -365,11 +372,11 @@ export function readRuntimeKeyframes(
       const read = readTween(tween.vars);
       if (!read) continue;
       if (requireChannels && !readCarriesChannel(read, requireChannels)) continue;
-      if (firstRead === null) firstRead = read;
+      if (firstRead === null) firstRead = withParsedStart(read, tween);
       // Prefer the tween whose [start, start+dur] contains the playhead.
       if (now != null) {
         const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
-        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return read;
+        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return withParsedStart(read, tween);
       }
     }
   }

package/src/hooks/gsapShared.ts

@@ -3,6 +3,7 @@
  * Centralises duplicated interfaces, constants, and small utilities
  * to reduce drift risk.
  */
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -223,7 +224,7 @@ function structuralSelector(element: Element): string | null {
   const parts: string[] = [];
   for (let node: Element | null = element; node; node = node.parentElement) {
     if (node !== element) {
-      const id = node instanceof HTMLElement ? node.id : "";
+      const id = isHtmlElement(node) ? node.id : "";
       const hfId = node.getAttribute("data-hf-id");
       if (id) {
         parts.unshift(idSelector(id));

package/src/hooks/gsapShared.writeTarget.test.ts

@@ -110,6 +110,16 @@ describe("writeTargetSelector", () => {
     expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
   });
 
+  it("anchors on an ancestor's id in the preview, whichever window built its nodes", () => {
+    const frame = document.body.appendChild(document.createElement("iframe"));
+    const doc = frame.contentDocument!;
+    doc.body.innerHTML = `<div id="scene"><div></div><div></div></div>`;
+    const el = doc.querySelectorAll<HTMLElement>("#scene > div")[1]!;
+    const selection = { ...stableSelectionFor(el), selector: "div[unclosed" } as DomEditSelection;
+
+    expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
+  });
+
   it("returns null when a live DOM is present and no rung addresses one element", () => {
     document.body.innerHTML = `<div id="scene"><div class="group"></div><div class="group"></div></div>`;
     const el = document.querySelectorAll<HTMLElement>(".group")[1]!;

package/src/hooks/intersectionObserverTestUtils.ts

@@ -0,0 +1,16 @@
+// Test-only IntersectionObserver stand-in: everything observed is reported near the screen, asynchronously.
+export function NearScreenIntersectionObserver(callback: IntersectionObserverCallback) {
+  const observer = {
+    observe(target: Element) {
+      queueMicrotask(() =>
+        callback(
+          [{ isIntersecting: true, target } as IntersectionObserverEntry],
+          observer as unknown as IntersectionObserver,
+        ),
+      );
+    },
+    unobserve() {},
+    disconnect() {},
+  };
+  return observer;
+}

package/src/hooks/resizeObserverTestUtils.ts

@@ -1,14 +1,21 @@
 // Test-only ResizeObserver stand-in: a test delivers a size by hand with `reportResize`.
 let resizeCallback: ResizeObserverCallback | null = null;
+let observed: Element | null = null;
 
 export function MockResizeObserver(callback: ResizeObserverCallback) {
   resizeCallback = callback;
-  return { observe() {}, disconnect() {}, unobserve() {} };
+  return {
+    observe(target: Element) {
+      observed = target;
+    },
+    disconnect() {},
+    unobserve() {},
+  };
 }
 
 export function reportResize(width: number, height: number): void {
   resizeCallback!(
-    [{ contentRect: { width, height } } as ResizeObserverEntry],
+    [{ contentRect: { width, height }, target: observed } as ResizeObserverEntry],
     {} as ResizeObserver,
   );
 }

package/src/hooks/timelineEditingHelpers.ts

@@ -1,3 +1,4 @@
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import { type TimelineElement, usePlayerStore } from "../player/store/playerStore";
 import { toAuthoredStart } from "../player/store/timelineElement";
 import {
@@ -35,14 +36,6 @@ import {
 } from "../components/editor/domEditingElement";
 export { deleteSelectedKeyframes } from "./deleteSelectedKeyframes";
 export { readFileContent };
-function isHTMLElement(element: Element | null): element is HTMLElement {
-  if (!element) return false;
-  // Use the element's OWN realm's HTMLElement: timeline clips live in the preview
-  // iframe, and cross-realm `element instanceof HTMLElement` (main window) is
-  // always false — which silently dropped every timeline z-index commit.
-  const Ctor = element.ownerDocument?.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return element instanceof Ctor;
-}
 /**
  * Resolve a timeline vertical move to a z-index stacking reorder and commit it
  * through the shared layers-panel reorder path. Reads live sibling z-index from
@@ -96,7 +89,7 @@ export function applyTimelineStackingReorder(input: {
           input.activeCompPath,
         )
       : null;
-    if (!isHTMLElement(element)) return Promise.resolve();
+    if (!isHtmlElement(element)) return Promise.resolve();
     if (getElementZIndex(element) === change.zIndex) continue;
     commitEntries.push({
       element,