@hyperframes/studio 0.8.48 → 0.8.49

package/src/player/components/useTimelineFocusCoordinator.ts

@@ -11,6 +11,7 @@ import {
   type TimelineLogicalTarget,
 } from "./timelineKeyboardNavigation";
 import { computeRevealScroll } from "./timelineRevealScroll";
+import { recordRetryAttempt, type RetryBudgetState } from "../../utils/retryBudget";
 
 interface TimelineFocusCoordinatorInput {
   scrollRef: RefObject<HTMLDivElement | null>;
@@ -24,6 +25,7 @@ interface TimelineFocusCoordinatorInput {
   projectId: string | null;
   sessionEpoch: number;
   syncScrollViewport: (element: HTMLDivElement) => void;
+  lastScrollLeftRef: RefObject<number>;
 }
 
 export interface TimelineFocusCoordinatorState {
@@ -77,6 +79,7 @@ function scrollToTarget(
   pixelsPerSecond: number,
   contentOrigin: number,
   allowHorizontal: boolean,
+  lastScrollLeftRef: RefObject<number>,
 ): boolean {
   const rowIndex = rowGeometry.getRowIndex(resolution.row.physicalTrackKey);
   if (rowIndex < 0) return false;
@@ -103,11 +106,26 @@ function scrollToTarget(
     stickyTop: RULER_H,
     allowHorizontal: allowHorizontal && left !== null,
   });
-  if (target.left !== null) container.scrollLeft = target.left;
+  if (target.left !== null) {
+    container.scrollLeft = target.left;
+    // Keep the geometry effect's "restore scroll after an edit re-derives the
+    // elements" in sync, or it reads the pre-reveal position on the next tick
+    // and scrolls the freshly-revealed clip back out of view.
+    lastScrollLeftRef.current = target.left;
+  }
   if (target.top !== null) container.scrollTop = target.top;
   return target.left !== null || target.top !== null;
 }
 
+// A request racing a fresh element's own creation (drop/paste) resolves within
+// a render or two; past this many misses on the same nonce it truly never will.
+const MAX_UNRESOLVED_FOCUS_RETRIES = 5;
+
+// Backstop for a request whose target never appears and nothing else ever
+// re-renders: the retry budget above can't advance without a rerun, so this
+// bounds it by wall time instead, independent of re-renders.
+const UNRESOLVED_FOCUS_TIMEOUT_MS = 4000;
+
 /** Model-first focus actor; mounting is a consequence of its returned pins. */
 // Resolution, fallback, reveal, and focus form one ordered state machine.
 // fallow-ignore-next-line complexity
@@ -123,11 +141,13 @@ export function useTimelineFocusCoordinator({
   projectId,
   sessionEpoch,
   syncScrollViewport,
+  lastScrollLeftRef,
 }: TimelineFocusCoordinatorInput): TimelineFocusCoordinatorState {
   const request = usePlayerStore((state) => state.timelineFocus);
   const previousRowsRef = useRef(logicalRows);
   const resolvedRef = useRef<{ nonce: number; id: string } | null>(null);
   const appliedRef = useRef<{ nonce: number; id: string } | null>(null);
+  const unresolvedFocusAttemptsRef = useRef<RetryBudgetState<number>>({ id: -1, count: 0 });
   const resolution = useMemo<ResolvedFocus | null>(() => {
     if (isCurrentRequest(request, projectId, sessionEpoch)) {
       if (resolvedRef.current?.nonce !== request.nonce) {
@@ -163,8 +183,26 @@ export function useTimelineFocusCoordinator({
   useEffect(() => {
     if (!isCurrentRequest(request, projectId, sessionEpoch)) return;
     if (!resolution) {
-      usePlayerStore.getState().clearTimelineFocus(request.nonce);
-      return;
+      // A request issued the same tick as its element (a fresh drop/paste) can
+      // outrun logicalRows by a render or two; only give up once it clearly
+      // never resolves, so the reveal isn't lost to that ordinary race.
+      const withinBudget = recordRetryAttempt(
+        unresolvedFocusAttemptsRef,
+        request.nonce,
+        MAX_UNRESOLVED_FOCUS_RETRIES,
+      );
+      if (!withinBudget) {
+        usePlayerStore.getState().clearTimelineFocus(request.nonce);
+        return;
+      }
+      const nonce = request.nonce;
+      const timeout = setTimeout(() => {
+        usePlayerStore.getState().clearTimelineFocus(nonce);
+      }, UNRESOLVED_FOCUS_TIMEOUT_MS);
+      return () => clearTimeout(timeout);
+    }
+    if (unresolvedFocusAttemptsRef.current.count !== 0) {
+      unresolvedFocusAttemptsRef.current = { id: -1, count: 0 };
     }
     if (resolution.target.id !== request.id) {
       usePlayerStore.getState().requestTimelineFocus(resolution.target.id);
@@ -187,6 +225,7 @@ export function useTimelineFocusCoordinator({
         pixelsPerSecond,
         contentOrigin,
         allowHorizontal,
+        lastScrollLeftRef,
       )
     ) {
       syncScrollViewport(container);
@@ -197,6 +236,7 @@ export function useTimelineFocusCoordinator({
     allowHorizontal,
     contentOrigin,
     elements,
+    lastScrollLeftRef,
     pixelsPerSecond,
     projectId,
     request,

package/src/player/components/useTimelineGeometry.test.tsx

@@ -0,0 +1,117 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { useTimelineGeometry } from "./useTimelineGeometry";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const element: TimelineElement = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+function Harness({
+  expandedElements,
+  lastScrollLeftRef,
+  scrollWidth = 20_000,
+}: {
+  expandedElements: TimelineElement[];
+  lastScrollLeftRef: React.RefObject<number>;
+  scrollWidth?: number;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  useTimelineGeometry({
+    viewportWidth: 1600,
+    effectiveDuration: 60,
+    zoomMode: "manual",
+    manualZoomPercent: 100,
+    ppsRef,
+    fitPpsRef,
+    draggedClip: null,
+    resizingClip: null,
+    expandedElements,
+    isDragging,
+    scrollRef,
+    lastScrollLeftRef,
+    contentOrigin: 32,
+  });
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: 1600 });
+          Object.defineProperty(node, "scrollWidth", { configurable: true, value: scrollWidth });
+        }
+      }}
+    />
+  );
+}
+
+let host: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "project-a" });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe("useTimelineGeometry restore-scroll effect", () => {
+  it("reads lastScrollLeftRef at frame time, not effect time, so a same-commit reveal isn't undone", async () => {
+    // A sibling effect in the same commit (a fresh timeline-focus reveal) can
+    // update lastScrollLeftRef and the DOM scrollLeft together after this
+    // effect has already scheduled its frame. The frame must see that update,
+    // not the value that was current when it was scheduled.
+    const lastScrollLeftRef = { current: 132 };
+    act(() => {
+      root.render(<Harness expandedElements={[]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    scroll.scrollLeft = 132;
+
+    // Flush this effect (it schedules a frame, capturing whatever it reads
+    // right now) BEFORE the sibling mutates the ref, exactly as in a real
+    // commit where this effect registers and runs ahead of the reveal's.
+    act(() => {
+      root.render(<Harness expandedElements={[element]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    // Simulate the sibling reveal effect: it runs after this one in the same
+    // commit and updates both the DOM and the ref before the frame fires.
+    lastScrollLeftRef.current = 450;
+    scroll.scrollLeft = 450;
+    await act(async () => {
+      await nextFrame();
+    });
+
+    expect(scroll.scrollLeft).toBe(450);
+  });
+
+  it("still restores the pre-edit position when nothing else changed the ref mid-frame", async () => {
+    const lastScrollLeftRef = { current: 300 };
+    act(() => {
+      root.render(<Harness expandedElements={[]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    scroll.scrollLeft = 0;
+
+    act(() => {
+      root.render(<Harness expandedElements={[element]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    await act(async () => {
+      await nextFrame();
+    });
+
+    expect(scroll.scrollLeft).toBe(300);
+  });
+});

package/src/player/components/useTimelineGeometry.ts

@@ -93,9 +93,14 @@ export function useTimelineGeometry({
   useEffect(() => {
     if (zoomMode !== "manual" || isDragging.current) return;
     const el = scrollRef.current;
-    const target = lastScrollLeftRef.current;
-    if (!el || target <= 0) return;
+    if (!el) return;
+    // Read the ref inside the frame, not here: a sibling effect in the same
+    // commit (a fresh reveal) can still update lastScrollLeftRef before this
+    // frame runs, and a value captured now would fight that reveal with a
+    // stale target.
     const raf = requestAnimationFrame(() => {
+      const target = lastScrollLeftRef.current;
+      if (target <= 0) return;
       const max = Math.max(0, el.scrollWidth - el.clientWidth);
       const next = Math.min(target, max);
       if (Math.abs(el.scrollLeft - next) > 0.5) el.scrollLeft = next;

package/src/player/components/useTimelineGeometryFocusOrder.test.tsx

@@ -0,0 +1,184 @@
+// @vitest-environment happy-dom
+
+import React, { act, useMemo, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { timelineClipFocusId, timelineTrackRowId } from "./timelineNavigationIdentity";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+import { useTimelineGeometry } from "./useTimelineGeometry";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+const oldElement = { id: "old", tag: "div", start: 0, duration: 1, track: 1 };
+const heroElement = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+const clipId = timelineClipFocusId("hero");
+const rowId = timelineTrackRowId(1);
+const beforeRows: readonly TimelineLogicalRow[] = [
+  {
+    id: rowId,
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [],
+  },
+];
+const afterRows: readonly TimelineLogicalRow[] = [
+  {
+    id: rowId,
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [{ id: clipId, kind: "clip", rowId, elementId: "hero", time: 21 }],
+  },
+];
+
+// Renders the two real production hooks side by side, in a caller-chosen call
+// order, to test whether their interaction actually depends on that order —
+// as opposed to simulating one hook's effect by hand.
+function OrderHarness({
+  order,
+  expandedElements,
+  logicalRows,
+  lastScrollLeftRef,
+}: {
+  order: "geometry-first" | "coordinator-first";
+  expandedElements: (typeof oldElement)[];
+  logicalRows: readonly TimelineLogicalRow[];
+  lastScrollLeftRef: React.RefObject<number>;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  const rowGeometry = useMemo(() => createTimelineRowGeometry([1], [48]), []);
+
+  const runGeometry = () =>
+    useTimelineGeometry({
+      viewportWidth: 300,
+      effectiveDuration: 60,
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      ppsRef,
+      fitPpsRef,
+      draggedClip: null,
+      resizingClip: null,
+      expandedElements,
+      isDragging,
+      scrollRef,
+      lastScrollLeftRef,
+      contentOrigin: 32,
+    });
+  const runFocus = () =>
+    useTimelineFocusCoordinator({
+      scrollRef,
+      logicalRows,
+      elements: expandedElements,
+      rowGeometry,
+      pixelsPerSecond: 100,
+      contentOrigin: 32,
+      allowHorizontal: true,
+      viewportVersion: logicalRows.length,
+      projectId: "project-a",
+      sessionEpoch: 1,
+      syncScrollViewport: () => {},
+      lastScrollLeftRef,
+    });
+
+  // `order` is fixed for the lifetime of one mounted harness, so this call
+  // order is stable across that instance's renders.
+  if (order === "geometry-first") {
+    runGeometry();
+    runFocus();
+  } else {
+    runFocus();
+    runGeometry();
+  }
+
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: 300 });
+          Object.defineProperty(node, "clientHeight", { configurable: true, value: 100 });
+          Object.defineProperty(node, "scrollWidth", { configurable: true, value: 20_000 });
+        }
+      }}
+    />
+  );
+}
+
+let host: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "project-a", timelineSessionEpoch: 1 });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe.each(["geometry-first", "coordinator-first"] as const)(
+  "useTimelineGeometry + useTimelineFocusCoordinator, %s",
+  (order) => {
+    it("a same-commit reveal survives the geometry restore effect regardless of hook registration order", async () => {
+      const lastScrollLeftRef = { current: 132 };
+      await act(async () => {
+        root.render(
+          <OrderHarness
+            order={order}
+            expandedElements={[oldElement]}
+            logicalRows={beforeRows}
+            lastScrollLeftRef={lastScrollLeftRef}
+          />,
+        );
+      });
+      const scroll = host.firstElementChild as HTMLDivElement;
+      scroll.scrollLeft = 132;
+      await act(async () => {
+        await nextFrame();
+      });
+      expect(scroll.scrollLeft).toBe(132);
+
+      // One commit: the drop both adds the element (expandedElements changes,
+      // arming the geometry restore effect) and resolves the focus request
+      // (arming the coordinator's reveal), exactly as Timeline.tsx renders them.
+      usePlayerStore.getState().requestTimelineFocus(clipId);
+      await act(async () => {
+        root.render(
+          <OrderHarness
+            order={order}
+            expandedElements={[oldElement, heroElement]}
+            logicalRows={afterRows}
+            lastScrollLeftRef={lastScrollLeftRef}
+          />,
+        );
+      });
+      await act(async () => {
+        await nextFrame();
+      });
+
+      expect(scroll.scrollLeft).toBe(1_944);
+      expect(lastScrollLeftRef.current).toBe(1_944);
+    });
+  },
+);

package/src/player/components/useTimelineLogicalFocus.ts

@@ -63,6 +63,7 @@ export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
     projectId,
     sessionEpoch: input.sessionEpoch,
     syncScrollViewport: input.syncScrollViewport,
+    lastScrollLeftRef: input.lastScrollLeftRef,
   });
   const rows = useTimelineRowVirtualization({
     scrollRef: input.scrollRef,

package/src/player/lib/timelineElementHelpers.ts

@@ -392,6 +392,14 @@ export function deriveTimelineStoreKey(params: {
   return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
 }
 
+/**
+ * {@link deriveTimelineStoreKey} for a caller that already has a DOM id in
+ * hand (e.g. one it just minted), so the undefined branch never applies.
+ */
+export function deriveTimelineStoreKeyForDomId(domId: string, sourceFile?: string): string {
+  return deriveTimelineStoreKey({ domId, sourceFile })!;
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------

package/src/player/store/readinessSlice.ts

@@ -1,7 +1,8 @@
 /** Gates `timelineReady` on the composition's declared readiness inputs
- * (media, for now) instead of just a known duration. The generation counter
- * is module-scope, not store state: it guards an in-flight settlement, not
- * something a component reads, so bumping it shouldn't trigger a render. */
+ * (media, compute, and the paint-and-idle default) instead of just a known
+ * duration. The generation counter is module-scope, not store state: it
+ * guards an in-flight settlement, not something a component reads, so
+ * bumping it shouldn't trigger a render. */
 import type { StoreApi } from "zustand";
 import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
 

package/src/utils/blockInstaller.test.ts

@@ -63,5 +63,9 @@ describe("addBlockToProject", () => {
     expect(source).toContain('data-start="2.5"');
     expect(source).toContain('data-duration="4.25"');
     expect(source).toContain('data-track-index="3"');
+    // hostKey addresses the new element the same way the timeline selects
+    // clips (sourceFile#domId), so the caller can select and reveal it.
+    expect(result?.hostKey).toBe("compositions/scene.html#camcorder-hud");
+    expect(source).toContain('id="camcorder-hud"');
   });
 });

package/src/utils/blockInstaller.ts

@@ -11,6 +11,7 @@ import { formatTimelineAttributeNumber } from "../player/components/timelineEdit
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import type { EditHistoryKind } from "./editHistory";
 import { extendRootDurationInSource } from "./rootDuration";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
 function getMaxZIndexFromIframe(iframe: HTMLIFrameElement | null): number {
   try {
@@ -174,7 +175,7 @@ function buildSubCompositionHtml({
 
 export async function addBlockToProject(
   opts: AddBlockOptions,
-): Promise<{ block: RegistryItem; compositionPath: string } | null> {
+): Promise<{ block: RegistryItem; compositionPath: string; hostKey: string } | null> {
   const {
     projectId,
     blockName,
@@ -213,8 +214,9 @@ export async function addBlockToProject(
       currentTime: opts.currentTime ?? 0,
     });
     const { width, height } = resolveTimelineAssetCompositionSize(originalContent);
+    const hostId = buildUniqueCompositionId(block.name, collectHtmlIds(originalContent));
     const subComposition = buildSubCompositionHtml({
-      id: buildUniqueCompositionId(block.name, collectHtmlIds(originalContent)),
+      id: hostId,
       compositionFile,
       start,
       duration,
@@ -242,7 +244,11 @@ export async function addBlockToProject(
     await refreshFileTree();
     reloadPreview();
 
-    return { block, compositionPath: compositionFile };
+    return {
+      block,
+      compositionPath: compositionFile,
+      hostKey: deriveTimelineStoreKeyForDomId(hostId, targetPath),
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : "Failed to add block";
     showToast(message);

package/src/utils/retryBudget.ts

@@ -0,0 +1,20 @@
+import type { MutableRefObject } from "react";
+
+export interface RetryBudgetState<K> {
+  id: K;
+  count: number;
+}
+
+// A target still resolving (a just-dropped/pasted/duplicated element, or a
+// preview still reloading) heals within a few retries; one that never will
+// would otherwise retry forever. A new id resets the count.
+export function recordRetryAttempt<K>(
+  ref: MutableRefObject<RetryBudgetState<K>>,
+  id: K,
+  maxRetries: number,
+): boolean {
+  const previous = ref.current;
+  const count = previous.id === id ? previous.count + 1 : 1;
+  ref.current = { id, count };
+  return count <= maxRetries;
+}

package/src/utils/sdkCutover.familyGate.test.ts

@@ -41,6 +41,10 @@ describe("SDK family gate mapping", () => {
         {} as never,
         deps,
       ),
-    ).resolves.toMatchObject({ status: "declined", reason: "ineligible_operation" });
+      // The dom family is off, so the gate declines on the FLAG, not on the op
+      // batch (which is a perfectly eligible inline-style edit). Before the
+      // reason split this reported `ineligible_operation`, which read as "the
+      // SDK cannot express this edit" when the truth was "this family is off".
+    ).resolves.toMatchObject({ status: "declined", reason: "feature_disabled" });
   });
 });

package/src/utils/sdkCutover.ts

@@ -7,8 +7,8 @@ import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
 import {
   isResolverDisagreement,
+  sdkCutoverIneligibleReason,
   shouldDeclineTextCutoverForTarget,
-  shouldUseSdkCutover,
 } from "./sdkCutoverEligibility";
 import {
   asCutoverError,
@@ -81,11 +81,14 @@ export async function sdkCutoverPersist(
   deps: CutoverDeps,
   options?: CutoverOptions,
 ): Promise<CutoverResult> {
-  if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation", "dom");
+  // Name WHICH eligibility check failed: on v0.8.47 this one string covered 26 of
+  // 30 dom declines. The two below aren't properties of the batch, so they differ.
+  if (!sdkFamilyEnabled("dom")) return declinedCutover("feature_disabled", "dom");
   if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable", "dom");
+  const ineligible = sdkCutoverIneligibleReason(hfId, ops);
+  // `!hfId` is already a reason; testing it again narrows the type for the rest.
+  if (ineligible || !hfId) return declinedCutover(ineligible ?? "target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
   if (!target)
     return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));