@hyperframes/studio 0.8.48 → 0.8.50

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/components/useTimelineTrackDerivations.ts

@@ -98,7 +98,7 @@ function buildGroupInfo(
     id: groupId,
     label: membership.labelByGroup.get(groupId) ?? groupId,
     // Exactly x.5, which sub-composition child rows are now kept strictly below
-    // (`useExpandedTimelineElements`) — they used to be able to land here and
+    // (`useTimelineRowElements`) — they used to be able to land here and
     // collide, duplicating the group header.
     anchorKey: (memberTracks[0] ?? fallbackTrackNum) - 0.5,
     memberTracks,

package/src/player/hooks/timelineDomBinding.test.ts

@@ -73,9 +73,6 @@ describe("live DOM manifest hydration", () => {
       canTrimEnd: true,
     });
     expect(getTimelineEditCapabilities({ ...input, timelineLocked: true }).canMove).toBe(false);
-    expect(getTimelineEditCapabilities({ ...input, timingSource: "implicit" }).canTrimEnd).toBe(
-      false,
-    );
   });
   it("uses at most one fallback candidate snapshot per hydration pass", () => {
     const doc = documentWith(

package/src/player/hooks/timelineSyncHydration.test.ts

@@ -3,6 +3,7 @@
 import { describe, expect, it } from "vitest";
 import {
   collectSubCompositionDomChildren,
+  collectTopLevelElementIds,
   collectSubCompositionHostState,
 } from "./timelineSyncHydration";
 import type { ClipManifestClip } from "../lib/playbackTypes";
@@ -94,3 +95,20 @@ describe("collectSubCompositionHostState", () => {
     expect(state.size).toBe(0);
   });
 });
+
+describe("collectTopLevelElementIds", () => {
+  const docOf = (html: string) => new DOMParser().parseFromString(html, "text/html");
+
+  it("names the sub-composition host and a timed element, not what is nested inside them", () => {
+    const doc = docOf(`<div data-composition-id="root">
+      <div id="wrap"><div id="a" data-start="0" data-duration="2"><div id="inner" data-start="0"></div></div></div>
+      <div id="scene" data-composition-id="scene" data-composition-src="scene.html"><div id="box" data-start="0"></div></div>
+    </div>`);
+    expect([...collectTopLevelElementIds(doc)!].sort()).toEqual(["a", "scene"]);
+  });
+
+  it("is null when the document has no composition root", () => {
+    expect(collectTopLevelElementIds(docOf("<p>hi</p>"))).toBeNull();
+    expect(collectTopLevelElementIds(null)).toBeNull();
+  });
+});

package/src/player/hooks/timelineSyncHydration.ts

@@ -14,12 +14,12 @@ import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { ClipTree } from "@hyperframes/core/runtime/clipTree";
+import { topLevelElements, type StructureNode } from "@hyperframes/parsers/top-level-elements";
 import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { groupInfoFor } from "../lib/timelineGroupInfo";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
   buildStandaloneRootTimelineElement,
-  createImplicitTimelineLayersFromDOM,
   createTimelineElementFromManifestClip,
   getTimelineElementSelector,
   parseTimelineFromDOM,
@@ -137,6 +137,28 @@ export function collectSubCompositionDomChildren(
   return out;
 }
 
+interface DomStructureNode extends StructureNode<DomStructureNode> {
+  id: string;
+}
+
+function toStructureNode(el: Element): DomStructureNode {
+  const attrs: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes)) attrs[attr.name] = attr.value;
+  return {
+    tag: el.tagName,
+    attrs,
+    id: el.id,
+    children: Array.from(el.children).map(toStructureNode),
+  };
+}
+
+/** DOM ids of the timeline's rows, by the definition the structure lint shares; null when there is no readable root. */
+export function collectTopLevelElementIds(doc: Document | null): Set<string> | null {
+  const root = doc?.querySelector("[data-composition-id]");
+  if (!root) return null;
+  return new Set(topLevelElements(toStructureNode(root)).flatMap((n) => (n.id ? [n.id] : [])));
+}
+
 /** The host-element `data-*` state one element carries, or null when it has none. */
 function readSubCompositionHostState(el: Element): SubCompositionHostState | null {
   const state: SubCompositionHostState = {};
@@ -214,28 +236,25 @@ export function buildTimelineElementsFromClips(
   });
 }
 
-/**
- * The clamped manifest elements plus the layers that exist only in the DOM.
- * Both halves need the same resolved duration, which is why they land together.
- */
-export function withImplicitDomLayers(
-  els: readonly TimelineElement[],
-  iframeDoc: Document | null,
-  effectiveDuration: number,
-): TimelineElement[] {
-  const clamped = clampElementsToDuration(els, effectiveDuration);
-  if (!iframeDoc || effectiveDuration <= 0) return clamped;
-  return [
-    ...clamped,
-    ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clamped),
-  ];
-}
-
 /**
  * Drop elements that start past the composition's end and trim the ones that
  * straddle it. A non-positive duration means "not known yet" — pass through
  * untouched rather than clamping everything to nothing.
  */
+/** Commits the manifest elements, including none. An empty manifest carries a 1s floor, not a duration. */
+export function syncManifestTimeline(
+  els: readonly TimelineElement[],
+  manifestDuration: number,
+  storeDuration: number,
+  sync: (els: TimelineElement[], duration?: number) => void,
+): void {
+  const hasDuration = manifestDuration > 0 && els.length > 0;
+  sync(
+    clampElementsToDuration(els, hasDuration ? manifestDuration : storeDuration),
+    hasDuration ? manifestDuration : undefined,
+  );
+}
+
 function clampElementsToDuration(
   els: readonly TimelineElement[],
   effectiveDuration: number,

package/src/player/hooks/useTimelinePlayer.test.ts

@@ -330,34 +330,17 @@ describe("findTimelineDomNodeForClip", () => {
 });
 
 describe("anonymous timeline identity", () => {
-  it("adds root-level untimed DOM layers as implicit full-duration layers", () => {
+  it("does not invent rows for root-level untimed wrappers", () => {
     const doc = createDocument(`
       <div data-composition-id="compare" data-start="0" data-duration="18">
-        <link rel="stylesheet" href="styles.css" />
-        <div class="scene-shell">
-          <div class="topline">Title</div>
-        </div>
+        <div class="scene-shell"><div class="topline">Title</div></div>
         <video id="main-video" class="clip main-video" data-start="0" data-duration="18" data-track-index="1"></video>
-        <script></script>
       </div>
     `);
 
     const elements = parseTimelineFromDOM(doc, 18);
 
-    expect(elements).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          duration: 18,
-          label: "Scene Shell",
-          selector: ".scene-shell",
-          start: 0,
-          tag: "div",
-          timingSource: "implicit",
-        }),
-      ]),
-    );
-    expect(elements.find((element) => element.tag === "link")).toBeUndefined();
-    expect(elements.find((element) => element.tag === "script")).toBeUndefined();
+    expect(elements.map((element) => element.tag)).toEqual(["video"]);
   });
 
   it("keeps fallback-parsed anonymous clips distinct when labels match", () => {

package/src/player/hooks/useTimelineRowElements.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { selectTimelineRowElements } from "./useTimelineRowElements";
+
+const el = (id: string, domId?: string): TimelineElement => ({
+  id,
+  domId,
+  start: 0,
+  duration: 1,
+  track: 0,
+  tag: "div",
+});
+
+describe("selectTimelineRowElements", () => {
+  it("drops an element the shared definition does not call top-level", () => {
+    const rows = selectTimelineRowElements([el("a", "a"), el("b", "b")], new Set(["a"]));
+    expect(rows.map((r) => r.id)).toEqual(["a"]);
+  });
+
+  it("keeps everything until the document has been read", () => {
+    const all = [el("a", "a"), el("b", "b")];
+    expect(selectTimelineRowElements(all, null)).toBe(all);
+  });
+
+  it("keeps an element with no DOM id", () => {
+    expect(selectTimelineRowElements([el("k")], new Set())).toHaveLength(1);
+  });
+});

package/src/player/hooks/useTimelineRowElements.ts

@@ -0,0 +1,17 @@
+import { useMemo } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+/** Rows are the ids `topLevelElements` names, as the lint does; id-less ones are kept. */
+export function selectTimelineRowElements(
+  elements: TimelineElement[],
+  topLevelIds: ReadonlySet<string> | null,
+): TimelineElement[] {
+  if (!topLevelIds) return elements;
+  return elements.filter((el) => el.domId === undefined || topLevelIds.has(el.domId));
+}
+
+export function useTimelineRowElements(): TimelineElement[] {
+  const elements = usePlayerStore((s) => s.elements);
+  const topLevelIds = usePlayerStore((s) => s.topLevelIds);
+  return useMemo(() => selectTimelineRowElements(elements, topLevelIds), [elements, topLevelIds]);
+}