@hyperframes/studio 0.8.125 → 0.8.127

package/src/hooks/gsapWholePropertyOffsetCommit.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import { commitWholePathOffset, type GsapDragCommitCallbacks } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 
 // Regression (#1808): with auto-keyframe recording off, a manual edit on an
@@ -203,3 +203,74 @@ describe("commitWholePropertyOffset", () => {
     expect(mutations[0]).toMatchObject({ easeEach: "none" });
   });
 });
+
+it.each([
+  [{ rotation: "+=40" }, "array-step-relative"],
+  [{ rotation: 40, onComplete: "__raw:done" }, "array-step-callback"],
+  [{ rotation: "random(0, 90)" }, "array-step-random"],
+])("refuses to rewrite a step list holding %o and writes nothing", async (last, detail) => {
+  const steps = [{ rotation: 10 }, last].map((properties, i) => ({
+    percentage: (i + 1) * 50,
+    properties,
+  }));
+  const anim = {
+    id: "#box-steps",
+    targetSelector: "#box",
+    method: "to",
+    resolvedStart: 0,
+    duration: 2,
+    keyframes: { format: "object-array", keyframes: steps },
+  } as unknown as GsapAnimation;
+  const { mutations, callbacks } = recordingCallbacks();
+  const rotate = commitWholePropertyOffset(
+    selection(),
+    anim,
+    { rotation: 50 },
+    100,
+    null,
+    callbacks,
+    "Rotate",
+  );
+  await expect(rotate).rejects.toMatchObject({ reason: "keyframes-uneditable", detail });
+  expect(mutations).toEqual([]);
+});
+
+it("refuses to shift a layer's step list whose step has its own delay, writing nothing", async () => {
+  // No drag baseline on the element: the move starts from a zero offset.
+  const el = {
+    style: { getPropertyValue: () => "", setProperty: () => {} },
+    getAttribute: () => null,
+    removeAttribute: () => {},
+    getBoundingClientRect: () => ({ top: 0, left: 0 }),
+  };
+  const anim = {
+    id: "#box-steps",
+    targetSelector: "#box",
+    method: "to",
+    resolvedStart: 0,
+    duration: 2,
+    keyframes: {
+      format: "object-array",
+      keyframes: [
+        { percentage: 50, properties: { x: 100, delay: 0.5 } },
+        { percentage: 100, properties: { x: 200 } },
+      ],
+    },
+  } as unknown as GsapAnimation;
+  const { mutations, callbacks } = recordingCallbacks();
+  const sel = { ...selection(), element: el } as DomEditSelection;
+  const move = commitWholePathOffset(
+    sel,
+    anim,
+    { x: 40, y: 0 },
+    { x: 0, y: 0 },
+    null,
+    "#box",
+    callbacks,
+  );
+  await expect(move).rejects.toMatchObject({
+    reason: "keyframes-uneditable",
+    detail: "array-step-delay",
+  });
+  expect(mutations).toEqual([]);
+});

package/src/hooks/gsapWholePropertyOffsetCommit.ts

@@ -8,7 +8,11 @@ import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeComp
 import { roundTo3 } from "../utils/rounding";
 import { keyframeEases, PROPERTY_DEFAULTS } from "./gsapShared";
 import { synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
-import { materializeIfDynamic, type GsapDragCommitCallbacks } from "./gsapDragCommit";
+import {
+  materializeIfDynamic,
+  refuseStepListRewrite,
+  type GsapDragCommitCallbacks,
+} from "./gsapDragCommit";
 
 /**
  * Generic sibling of commitWholePathOffset for property groups other than
@@ -32,6 +36,7 @@ export async function commitWholePropertyOffset(
   // fallow-ignore-next-line code-duplication
   let effectiveAnim = anim;
   if (anim.keyframes) {
+    refuseStepListRewrite(anim);
     const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
     if (newId) effectiveAnim = { ...anim, id: newId };
   }

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,

package/src/hooks/useCommitPreflightCapabilities.ts

@@ -3,7 +3,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { dragEditOutcome, preflightGsapRotationIntercept } from "./gsapRuntimeBridge";
 import { preflightGsapResizeIntercept } from "./gsapResizePreflight";
-import { GSAP_EDIT_BLOCK_COPY, type GsapEditOutcome } from "./gsapEditOutcome";
+import { gsapEditBlockMessage, type GsapEditOutcome } from "./gsapEditOutcome";
 import { fetchParsedAnimations, parseCacheKey } from "./keyframeCacheAstLoad";
 import { getAnimationsForElement } from "./gsapElementMatch";
 import { gsapSourceFileForSelection } from "./useGsapAnimationFetchFallback";
@@ -44,7 +44,7 @@ const MANUAL_FLAGS = [
 function refusal(preflight: CommitPreflight | null, check: keyof CommitPreflight): string | null {
   const outcome = preflight?.[check];
   if (!outcome) return "";
-  return outcome.status === "blocked" ? GSAP_EDIT_BLOCK_COPY[outcome.reason] : null;
+  return outcome.status === "blocked" ? gsapEditBlockMessage(outcome.reason, outcome.detail) : null;
 }
 
 /** Closes each manual flag whose commit Studio would refuse, and says why. */

package/src/hooks/useGsapAwareEditing.groupPlan.test.tsx

@@ -127,6 +127,31 @@ describe("a group drag plans every member before its first write", () => {
     act(() => h.root.unmount());
   });
 
+  it("with auto-keyframe off, refuses the whole group when one member's step list holds a step delay", async () => {
+    usePlayerStore.setState({ autoKeyframeEnabled: false });
+    const steps = {
+      format: "object-array",
+      keyframes: [
+        { percentage: 50, properties: { x: 100, y: 0, delay: 0.5 } },
+        { percentage: 100, properties: { x: 200, y: 0 } },
+      ],
+    };
+    const h = mountGroup([
+      positionTween("a"),
+      positionTween("b", { keyframes: steps } as Partial<GsapAnimation>),
+      positionTween("c"),
+    ]);
+
+    await expect(h.groupCommit(h.updates)).rejects.toMatchObject({
+      reason: "keyframes-uneditable",
+      detail: "array-step-delay",
+    });
+
+    expect(h.written()).toEqual([]);
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(expect.objectContaining({ targetId: "b" }));
+    act(() => h.root.unmount());
+  });
+
   it("refuses members animated in two files, since the batch writes one file", async () => {
     const h = mountGroup(["a", "b", "c"].map((id) => positionTween(id)));
     const updates = h.updates.map((u, i) => ({

package/src/hooks/useThumbnailStripSize.test.tsx

@@ -1,7 +1,9 @@
 // @vitest-environment happy-dom
 import { act } from "react";
 import { createRoot } from "react-dom/client";
-import { expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "../player/components/testRootHarness";
+import { NearScreenIntersectionObserver } from "./intersectionObserverTestUtils";
 import { MockResizeObserver, reportResize } from "./resizeObserverTestUtils";
 import { useThumbnailStripSize } from "./useThumbnailStripSize";
 
@@ -45,3 +47,236 @@ it("does not re-render the strip when the observer reports the size it already h
     globalThis.ResizeObserver = originalResizeObserver;
   }
 });
+
+describe("on a scroll", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  const originalIntersectionObserver = globalThis.IntersectionObserver;
+  const frames: FrameRequestCallback[] = [];
+  const harness = createHappyDomRootHarness();
+  let host: HTMLDivElement;
+  let root: ReturnType<typeof createRoot>;
+  let left = 0;
+  let top = 0;
+  let scrolled = 0;
+  let scrolledDown = 0;
+  let stripWidth = 1_000_000;
+  let renders = 0;
+
+  function Strip() {
+    renders += 1;
+    const [size, ref] = useThumbnailStripSize();
+    return (
+      <div>
+        <div ref={ref} data-in-view={`${size.inViewStart}-${size.inViewEnd}`} />
+      </div>
+    );
+  }
+
+  const mountStrips = (count: number) =>
+    act(async () =>
+      root.render(Array.from({ length: count }, (_, index) => <Strip key={index} />)),
+    );
+
+  const spans = () =>
+    [...host.querySelectorAll("[data-in-view]")].map((strip) => strip.getAttribute("data-in-view"));
+
+  /** The timeline scrolls so the strips' left edge lands at `nextLeft`, then one frame runs. */
+  const scrollTo = (nextLeft: number) => {
+    scrolled += left - nextLeft;
+    left = nextLeft;
+    act(() => host.dispatchEvent(new Event("scroll")));
+    expect(window.requestAnimationFrame).toHaveBeenCalledTimes(1);
+    act(() => frames.splice(0).forEach((frame) => frame(0)));
+  };
+
+  const neverReportedNear = () => {
+    globalThis.IntersectionObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    } as unknown as typeof IntersectionObserver;
+  };
+
+  beforeEach(() => {
+    globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+    globalThis.IntersectionObserver =
+      NearScreenIntersectionObserver as unknown as typeof IntersectionObserver;
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((frame) => frames.push(frame));
+    vi.spyOn(Element.prototype, "getBoundingClientRect").mockImplementation(
+      () => ({ left, top, width: stripWidth, height: 40 }) as DOMRect,
+    );
+    vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockImplementation(() => stripWidth);
+    left = 0;
+    top = 0;
+    scrolled = 0;
+    scrolledDown = 0;
+    stripWidth = 1_000_000;
+    renders = 0;
+    host = document.body.appendChild(document.createElement("div"));
+    host.setAttribute("data-timeline-scroll-viewport", "");
+    Object.defineProperty(host, "scrollLeft", { configurable: true, get: () => scrolled });
+    Object.defineProperty(host, "scrollTop", { configurable: true, get: () => scrolledDown });
+    root = harness.mount(host);
+  });
+
+  afterEach(() => {
+    frames.length = 0;
+    vi.restoreAllMocks();
+    globalThis.ResizeObserver = originalResizeObserver;
+    globalThis.IntersectionObserver = originalIntersectionObserver;
+  });
+
+  it("re-measures every near strip in one shared frame, so a full timeline lays out once", async () => {
+    await mountStrips(50);
+
+    scrollTo(-10_000);
+
+    expect(spans()).toEqual(Array(50).fill("9216-11776"));
+  });
+
+  it("keeps a visible strip measured when it is read after a scroll but before that scroll's frame", async () => {
+    stripWidth = 5_000;
+    left = -1_000;
+    await mountStrips(1);
+
+    scrolled += 3_000;
+    left = -4_000;
+    act(() => reportResize(stripWidth, 40));
+    act(() => host.dispatchEvent(new Event("scroll")));
+    act(() => frames.splice(0).forEach((frame) => frame(0)));
+
+    expect(spans()).toEqual(["3072-5000"]);
+  });
+
+  it("keeps a strip on screen measured after a move without a scroll, then a scroll", async () => {
+    await mountStrips(1);
+    expect(spans()).toEqual(["0-1536"]);
+
+    left = -3_000;
+    scrollTo(-1_000);
+    expect(spans()).toEqual(["0-2560"]);
+  });
+
+  it("measures a strip a vertical scroll brings on screen in that same frame", async () => {
+    neverReportedNear();
+    top = 5_000;
+    await mountStrips(1);
+    expect(spans()).toEqual(["0-0"]);
+
+    scrolledDown += 4_900;
+    top = 100;
+    act(() => host.dispatchEvent(new Event("scroll")));
+    act(() => frames.splice(0).forEach((frame) => frame(0)));
+
+    expect(spans()).toEqual(["0-1536"]);
+  });
+
+  it("keeps the tiles of a strip that ends just off screen", async () => {
+    await mountStrips(1);
+
+    scrollTo(-(stripWidth + 100));
+
+    expect(spans()).toEqual(["999424-1000000"]);
+  });
+
+  it("measures the strips a jump brings on screen in that same frame", async () => {
+    neverReportedNear();
+    left = 50_000;
+    await mountStrips(50);
+    expect(spans()).toEqual(Array(50).fill("0-0"));
+
+    scrollTo(0);
+
+    expect(spans()).toEqual(Array(50).fill("0-1536"));
+  });
+
+  it("does not re-render a strip wholly on screen when it moves", async () => {
+    stripWidth = 300;
+    left = 100;
+    await mountStrips(1);
+    const settled = renders;
+
+    scrollTo(700);
+
+    expect(renders).toBe(settled);
+  });
+
+  it("does not re-render strips that a jump carries from one side of the screen to the other", async () => {
+    left = 50_000;
+    await mountStrips(50);
+    const settled = renders;
+
+    scrollTo(-2_000_000);
+
+    expect(renders).toBe(settled);
+  });
+
+  it("keeps every tile of a short clip, even far from the screen", async () => {
+    stripWidth = 4_096;
+    top = 5_000;
+    await mountStrips(1);
+
+    expect(spans()).toEqual(["0-4096"]);
+  });
+
+  it("never re-measures a short clip on a scroll", async () => {
+    stripWidth = 300;
+    left = 100;
+    await mountStrips(1);
+    const reads = vi.mocked(Element.prototype.getBoundingClientRect);
+    reads.mockClear();
+
+    scrollTo(50);
+
+    expect(reads).not.toHaveBeenCalled();
+  });
+
+  it("mounts nothing for a strip far above or below the screen", async () => {
+    top = 5_000;
+    await mountStrips(1);
+
+    expect(spans()).toEqual(["0-0"]);
+  });
+
+  it("measures a strip as it comes near the screen, without waiting for a frame", async () => {
+    const reports: IntersectionObserverCallback[] = [];
+    globalThis.IntersectionObserver = class {
+      constructor(callback: IntersectionObserverCallback) {
+        reports.push(callback);
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    } as unknown as typeof IntersectionObserver;
+    await mountStrips(1);
+    const strip = host.querySelector("[data-in-view]")!;
+
+    left = -10_000;
+    const [presence] = reports;
+    act(() =>
+      presence!(
+        [
+          {
+            isIntersecting: true,
+            target: strip.parentElement!,
+          } as unknown as IntersectionObserverEntry,
+        ],
+        {} as IntersectionObserver,
+      ),
+    );
+
+    expect(frames).toHaveLength(0);
+    expect(strip.getAttribute("data-in-view")).toBe("9216-11776");
+  });
+
+  it("reads no strip far from the screen, however many clips the timeline mounts", async () => {
+    left = 50_000;
+    await mountStrips(50);
+    const reads = vi.mocked(Element.prototype.getBoundingClientRect);
+    reads.mockClear();
+
+    scrollTo(49_900);
+
+    expect(reads).not.toHaveBeenCalled();
+  });
+});