@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/components/TimelineClipDiamonds.tsx

@@ -8,6 +8,7 @@ import {
 import { TimelineDiamondConnectors } from "./TimelineDiamondConnectors";
 import { clipToTweenPercentage } from "../../components/editor/KeyframeNavigation";
 import { LANE_H } from "./timelineLayout";
+import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import { timelineKeyframeSelectionKey } from "./timelineKeyframeIdentity";
 import {
   DIAMOND_RATIO,
@@ -22,11 +23,10 @@ import {
 
 export type { TimelineDiamondKeyframe } from "./timelineDiamondTypes";
 
-// Floor for a diamond's clickable width. The visual size still narrows to the
-// neighbour gap so packed diamonds stay individually readable, but the hit box
-// stops there: at the zoom floor the gap alone left a ~7px target, which is
-// neither hittable nor selectable with any accuracy. Boxes may overlap slightly
-// below this width; each diamond still owns the half-gap around its own centre.
+// Floor for a diamond's clickable width. The visible diamond stays full-size
+// even when neighbours overlap; shrinking recorded-gesture keyframes into dots
+// makes the timeline unreadable. The hit box still follows the neighbour gap
+// and stops at this floor so nearby timestamps remain separately targetable.
 //
 // Deliberately below the 24px WCAG 2.2 (2.5.8) minimum, under that criterion's
 // own spacing exception: at normal keyframe density the neighbour gap is under
@@ -40,10 +40,36 @@ function roundPct(percentage: number): number {
   return Math.round(percentage * 1000) / 1000;
 }
 
+/** Find the closest authored keyframe without scanning the full lane on every playhead tick. */
+function nearestKeyframeWithin(
+  sorted: TimelineDiamondKeyframe[],
+  percentage: number,
+  tolerance: number,
+): TimelineDiamondKeyframe | null {
+  if (!Number.isFinite(percentage) || tolerance <= 0 || sorted.length === 0) return null;
+  let low = 0;
+  let high = sorted.length;
+  while (low < high) {
+    const mid = (low + high) >>> 1;
+    if (sorted[mid]!.percentage < percentage) low = mid + 1;
+    else high = mid;
+  }
+  const before = sorted[low - 1];
+  const after = sorted[low];
+  const nearest =
+    before && after
+      ? percentage - before.percentage <= after.percentage - percentage
+        ? before
+        : after
+      : (before ?? after);
+  return nearest && Math.abs(nearest.percentage - percentage) <= tolerance ? nearest : null;
+}
+
 export const TimelineDiamondLane = memo(function TimelineDiamondLane({
   keyframesData,
   clipWidthPx,
   clipHeightPx,
+  clipDuration,
   beatsActive,
   accentColor,
   isSelected,
@@ -197,14 +223,24 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
     const previousGap = previous ? centerX - centerXOf(previous.percentage) : Infinity;
     const nextGap = next ? centerXOf(next.percentage) - centerX : Infinity;
     const nearestGap = Math.max(1, Math.min(previousGap, nextGap));
-    const gapWidth = Math.min(diamondSize, nearestGap);
+    const hitWidth = Math.min(diamondSize, nearestGap);
     return {
       keyframe,
       centerX,
-      hitWidth: Math.max(KF_MIN_HIT_W, gapWidth),
-      visualSize: gapWidth === diamondSize ? diamondSize : Math.max(2, gapWidth - 2),
+      hitWidth: Math.max(KF_MIN_HIT_W, hitWidth),
+      visualSize: diamondSize,
     };
   });
+  // The playhead is a cursor, not a selection. Resolve one nearest keyframe per
+  // rendered property lane and only while it is within half an output frame.
+  // A fixed clip-% tolerance grows with duration and lit whole clusters of
+  // gesture-recorded keyframes at once on long clips.
+  const halfFramePct =
+    clipDuration && clipDuration > 0 ? 50 / STUDIO_PREVIEW_FPS / clipDuration : 0;
+  const playheadKeyframe =
+    isSelected && halfFramePct > 0
+      ? nearestKeyframeWithin(sorted, currentPercentage, halfFramePct)
+      : null;
   const baseColor = isSelected ? accentColor : "#a3a3a3";
   const baseOpacity = isSelected ? 0.4 : 0.25;
   const canDrag = isSelected && !!onMoveKeyframe;
@@ -251,9 +287,9 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
         // fully visible instead of being clipped by the sticky label column.
         const leftPx = (renderPct / 100) * clipWidthPx - marker.hitWidth / 2;
         const isKfSelected = selectedKeyframes.has(kfKey);
-        const atPlayhead = isSelected && Math.abs(kf.percentage - currentPercentage) < 0.5;
+        const atPlayhead = kf === playheadKeyframe;
         const isHighlighted = isKfSelected || atPlayhead;
-        const color = isHighlighted ? accentColor : "#a3a3a3";
+        const color = isKfSelected ? accentColor : "#a3a3a3";
 
         const onPointerDown = (e: React.PointerEvent<HTMLButtonElement>) => {
           if (e.button !== 0) return;
@@ -417,6 +453,10 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
             data-keyframe-percentage={
               groupAware ? (kf.tweenPercentage ?? kf.percentage) : undefined
             }
+            data-keyframe-at-playhead={String(atPlayhead)}
+            data-keyframe-selected={String(isKfSelected)}
+            aria-current={atPlayhead ? "time" : undefined}
+            aria-pressed={isKfSelected}
             style={{
               left: leftPx,
               top: centerY,
@@ -461,19 +501,19 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
               viewBox="0 0 10 10"
               style={{ flexShrink: 0, pointerEvents: "none" }}
             >
-              {isKfSelected && (
+              {(isKfSelected || atPlayhead) && (
                 <path
                   d="M5 0L10 5L5 10L0 5Z"
                   fill="none"
                   stroke={accentColor}
                   strokeWidth="0.8"
-                  opacity={0.5}
+                  opacity={isKfSelected ? 0.5 : 1}
                 />
               )}
               <path
                 d="M5 1L9 5L5 9L1 5Z"
                 fill={color}
-                opacity={isKfSelected || atPlayhead ? 1 : 0.55}
+                opacity={isKfSelected ? 1 : atPlayhead ? 0.9 : 0.55}
               />
             </svg>
           </button>

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

@@ -7,7 +7,8 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { TimelineLanes } from "./TimelineLanes";
 import { getTrackStyle } from "./timelineIcons";
 import { defaultTimelineTheme } from "./timelineTheme";
-import { TRACK_H } from "./timelineLayout";
+import { TRACK_H, getTimelineRowGeometry } from "./timelineLayout";
+import { createTimelineClipIndex } from "../lib/timelineClipIndex";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -78,6 +79,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
     const laneCounts = new Map(
       elements.map((el) => [el.id, (gsapAnimations.get(el.id) ?? []).length]),
     );
+    const rowHeights = displayTrackOrder.map(() => TRACK_H);
     act(() => {
       usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
       root.render(
@@ -88,7 +90,13 @@ function renderLanes(options: RenderLanesOptions = {}): {
           trackContentWidth={800}
           theme={defaultTimelineTheme}
           displayTrackOrder={displayTrackOrder}
-          rowHeights={displayTrackOrder.map(() => TRACK_H)}
+          rowHeights={rowHeights}
+          rowGeometry={getTimelineRowGeometry(rowHeights)}
+          virtualRows={displayTrackOrder.map((_, index) => ({ index, rowKey: index }))}
+          rowsVirtualized={false}
+          clipIndex={createTimelineClipIndex(tracks)}
+          renderTimeRange={{ start: 0, end: Number.POSITIVE_INFINITY }}
+          pinnedClipIdentities={new Set()}
           trackOrder={displayTrackOrder}
           tracks={tracks}
           trackStyles={new Map()}
@@ -144,6 +152,7 @@ describe("TimelineLanes track numbering", () => {
     });
 
     expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
+    expect(view.host.querySelectorAll("[data-timeline-row]")).toHaveLength(2);
     expect(view.host.innerHTML).not.toContain("0.16666666666666666");
     act(() => view.root.unmount());
   });
@@ -171,8 +180,10 @@ describe("TimelineLanes track numbering", () => {
       onContextMenuLane,
     });
 
-    // Row children: [sticky header column, time-mapped track content].
-    const rows = Array.from(view.host.children);
+    // Row children: [sticky header column, time-mapped track content]. The rows
+    // sit inside the lanes list, which is what carries the virtualization
+    // positioning context.
+    const rows = Array.from(view.host.querySelectorAll('[role="listitem"]'));
     const secondTrackContent = rows[1]?.children.item(1);
     act(() => {
       secondTrackContent?.dispatchEvent(

package/src/player/components/TimelineLanes.tsx

@@ -1,4 +1,4 @@
-import { useId } from "react";
+import { Fragment, useId } from "react";
 import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
@@ -8,12 +8,14 @@ import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
 import { trackDisplayNumber, trackDisplaySuffix } from "./timelineTrackDisplay";
 import { clipTimingStart } from "../../hooks/gsapShared";
 import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
-import { CLIP_Y, CLIP_HANDLE_W, TRACK_H, getTimelineRowHeight } from "./timelineLayout";
+import { CLIP_Y, CLIP_HANDLE_W, TRACK_H } from "./timelineLayout";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import {
+  isMultiDragActive,
   isMultiDragPassenger,
-  multiDragPassengerOffsetPx,
+  multiDragDeltaSeconds,
   type MultiDragPreviewInput,
+  multiDragPassengerOffsetPx,
 } from "./timelineMultiDragPreview";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -21,6 +23,10 @@ import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
 import { renderClipChildren } from "./timelineClipChildren";
+import { TimelineTrackRow } from "./TimelineTrackRow";
+import { isTimelineClipActive } from "./useTimelineActiveClips";
+import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 
 interface TimelineLanesProps extends TimelineLaneBaseProps {
   /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
@@ -41,7 +47,12 @@ export function TimelineLanes({
   trackContentWidth,
   theme,
   displayTrackOrder,
-  rowHeights,
+  rowGeometry,
+  virtualRows,
+  rowsVirtualized,
+  clipIndex,
+  renderTimeRange,
+  pinnedClipIdentities,
   trackOrder,
   tracks,
   trackStyles,
@@ -102,19 +113,45 @@ export function TimelineLanes({
     trackStudioKeyframeLaneExpand({ expanded: willExpand });
     toggleClipExpanded(key);
   };
+  const multiDragDelta =
+    multiDragPreview && isMultiDragActive(multiDragPreview)
+      ? multiDragDeltaSeconds(multiDragPreview)
+      : 0;
+  const actorWindows =
+    rowsVirtualized && multiDragPreview && multiDragDelta !== 0
+      ? [
+          {
+            range: {
+              start: renderTimeRange.start - multiDragDelta,
+              end: renderTimeRange.end - multiDragDelta,
+            },
+            identities: multiDragPreview.selectedKeys,
+          },
+        ]
+      : [];
   return (
-    <>
+    <div
+      role="list"
+      aria-label="Timeline tracks"
+      className={rowsVirtualized ? "absolute inset-0" : undefined}
+    >
       {
-        // NOTE (deliberate no-virtualization): lanes and their clips render via a
-        // plain `.map()` inside the scroll container rather than a windowing/virtualized
-        // list. NLE clip counts are small (dozens to low hundreds), so the DOM cost is
-        // bounded and virtualization's complexity isn't worth it. TODO: revisit and swap
-        // in a virtualizer if editorial workflows ever push very high clip counts.
         // fallow-ignore-next-line complexity
-        displayTrackOrder.map((trackNum, row) => {
+        virtualRows.map(({ index: row, rowKey }) => {
+          const trackNum = displayTrackOrder[row];
+          if (trackNum === undefined) return null;
           const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
-          const rowHeight = getTimelineRowHeight(row, rowHeights);
+          const rowHeight = rowGeometry.getRowHeight(row);
           const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
+          const renderElements = rowsVirtualized
+            ? queryTimelineClipIndex(
+                clipIndex,
+                trackNum,
+                renderTimeRange,
+                pinnedClipIdentities,
+                actorWindows,
+              )
+            : els;
           const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
           const isPendingTrack =
             draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
@@ -148,14 +185,16 @@ export function TimelineLanes({
           // fractional sort key and would mint ids like `...-0.16666666666666666`.
           const lanesId = `${lanesIdPrefix}-track-${row}`;
           return (
-            <div
-              key={trackNum}
-              className="relative flex"
-              style={{
-                height: rowHeight,
-                background: rowBackground,
-                borderBottom: `1px solid ${theme.rowBorder}`,
-              }}
+            <TimelineTrackRow
+              key={rowKey}
+              index={row}
+              rowKey={rowKey}
+              rowCount={displayTrackOrder.length}
+              top={rowGeometry.getRowTop(row)}
+              height={rowHeight}
+              virtualized={rowsVirtualized}
+              background={rowBackground}
+              borderColor={theme.rowBorder}
             >
               <TimelineTrackHeader
                 trackNumber={trackNum}
@@ -218,6 +257,7 @@ export function TimelineLanes({
                       ? draggedClip.snapTime
                       : null
                   }
+                  renderTimeRange={rowsVirtualized ? renderTimeRange : undefined}
                 />
                 {/* Beat dots on the active track (the one holding the selection),
                     falling back to the music track when nothing is selected. */}
@@ -226,6 +266,7 @@ export function TimelineLanes({
                     beatTimes={beatAnalysis?.beatTimes}
                     beatStrengths={beatAnalysis?.beatStrengths}
                     pps={pps}
+                    renderTimeRange={rowsVirtualized ? renderTimeRange : undefined}
                   />
                 )}
                 {isPendingTrack && (
@@ -245,9 +286,9 @@ export function TimelineLanes({
                 )}
                 {
                   // fallow-ignore-next-line complexity
-                  els.map((el) => {
+                  renderElements.map((el) => {
                     const clipStyle = getTrackStyle(el.tag);
-                    const elementKey = el.key ?? el.id;
+                    const elementKey = getTimelineElementIdentity(el);
                     // Only the track's active keyframe clip shows expanded lanes;
                     // other clips (incl. siblings on a shared track) show compact
                     // diamonds on their own bar instead.
@@ -263,7 +304,8 @@ export function TimelineLanes({
                     const clipKey = elementKey;
                     const isDraggingClip =
                       draggedClip?.started === true &&
-                      (draggedElement?.key ?? draggedElement?.id) === elementKey;
+                      draggedElement != null &&
+                      getTimelineElementIdentity(draggedElement) === elementKey;
                     if (isDraggingClip) return null;
                     const previewElement = getPreviewElement(el);
                     // Passenger of a live multi-drag: slide by the SAME formation
@@ -290,6 +332,7 @@ export function TimelineLanes({
                         isSelected={isSelected}
                         isHovered={hoveredClip === clipKey}
                         isDragging={false}
+                        isActive={isTimelineClipActive(previewElement, currentTime)}
                         hasCustomContent={!!renderClipContent}
                         capabilities={capabilities}
                         theme={theme}
@@ -434,6 +477,7 @@ export function TimelineLanes({
                             keyframesData={keyframeCache.get(elementKey)!}
                             clipWidthPx={Math.max(previewElement.duration * pps, 4)}
                             clipHeightPx={rowHeight - 2 * CLIP_Y}
+                            clipDuration={previewElement.duration}
                             beatsActive={beatStripOnTrack}
                             accentColor={clipStyle.accent}
                             isSelected={isSelected}
@@ -499,7 +543,18 @@ export function TimelineLanes({
                         suppressClickRef={suppressClickRef}
                       />
                     );
-                    if (!isPassenger) return [clip, propertyLanes];
+                    // Keep one keyed top-level child per element. Returning an
+                    // array here makes React reconcile the outer array by
+                    // position, so a window shift remounts otherwise stable
+                    // clip keys and can tear down focus mid-reveal.
+                    if (!isPassenger) {
+                      return (
+                        <Fragment key={clipKey}>
+                          {clip}
+                          {propertyLanes}
+                        </Fragment>
+                      );
+                    }
                     return (
                       <div
                         key={clipKey}
@@ -518,10 +573,10 @@ export function TimelineLanes({
                   })
                 }
               </div>
-            </div>
+            </TimelineTrackRow>
           );
         })
       }
-    </>
+    </div>
   );
 }

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

@@ -126,6 +126,19 @@ const POSITION_SEGMENT_ANIMATION = animation("position-tween", "position", [
   { percentage: 50, properties: { x: 50 } },
 ]);
 
+function boundaryKeyframeAnimations(): GsapAnimation[] {
+  return [
+    animation("position-tween", "position", [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 100 } },
+    ]),
+    animation("visual-tween", "visual", [
+      { percentage: 0, properties: { opacity: 0 } },
+      { percentage: 100, properties: { opacity: 1 } },
+    ]),
+  ];
+}
+
 /** A tween the parser leaves unclassified because it spans several groups. */
 function ungroupedAnimation(
   id: string,
@@ -306,16 +319,7 @@ describe("TimelinePropertyLanes", () => {
   });
 
   it("keeps both groups' diamonds when their source keyframes share 0% and 100%", () => {
-    const animations = [
-      animation("position-tween", "position", [
-        { percentage: 0, properties: { x: 0 } },
-        { percentage: 100, properties: { x: 100 } },
-      ]),
-      animation("visual-tween", "visual", [
-        { percentage: 0, properties: { opacity: 0 } },
-        { percentage: 100, properties: { opacity: 1 } },
-      ]),
-    ];
+    const animations = boundaryKeyframeAnimations();
 
     const { host, root } = renderPropertyLanes({ animations });
 
@@ -512,16 +516,7 @@ describe("TimelinePropertyLanes", () => {
   // COLUMN whose children are all absolutely positioned: it computed to 0x0 and
   // held no diamonds. The real lanes had no wrapper at all to point at.
   it("wraps the lanes in the identified element so aria-controls resolves to the diamonds", () => {
-    const animations = [
-      animation("position-tween", "position", [
-        { percentage: 0, properties: { x: 0 } },
-        { percentage: 100, properties: { x: 100 } },
-      ]),
-      animation("visual-tween", "visual", [
-        { percentage: 0, properties: { opacity: 0 } },
-        { percentage: 100, properties: { opacity: 1 } },
-      ]),
-    ];
+    const animations = boundaryKeyframeAnimations();
     const { host, root } = renderPropertyLanes({ id: "timeline-lanes-track-0", animations });
     const wrapper = host.querySelector("#timeline-lanes-track-0");
 
@@ -594,6 +589,7 @@ describe("TimelinePropertyLanes", () => {
           }}
           clipWidthPx={200}
           clipHeightPx={48}
+          clipDuration={10}
           accentColor="#4ba3d2"
           isSelected
           currentPercentage={-10}

package/src/player/components/TimelinePropertyLanes.tsx

@@ -240,6 +240,7 @@ export function TimelinePropertyLanes({
             keyframesData={keyframesData}
             clipWidthPx={clipWidthPx}
             clipHeightPx={LANE_H}
+            clipDuration={clipDuration}
             accentColor={accentColor}
             isSelected={isSelected}
             currentPercentage={currentPercentage}

package/src/player/components/TimelineRuler.tsx

@@ -1,9 +1,11 @@
 import { memo } from "react";
 import type { TimelineTheme } from "./timelineTheme";
-import { RULER_H, formatTimelineTickLabel } from "./timelineLayout";
+import { RULER_H, getTimelineBeatEntries } from "./timelineLayout";
+import { formatTimelineTickLabel } from "./timelineRulerGeometry";
 import { usePlayerStore } from "../store/playerStore";
 import { secondsToFrame } from "../lib/time";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 
 interface TimelineRulerProps {
   major: number[];
@@ -16,6 +18,7 @@ interface TimelineRulerProps {
   theme: TimelineTheme;
   beatAnalysis?: MusicBeatAnalysis | null;
   contentOrigin: number;
+  renderTimeRange?: TimelineTimeRange;
 }
 
 export const TimelineRuler = memo(function TimelineRuler({
@@ -29,10 +32,12 @@ export const TimelineRuler = memo(function TimelineRuler({
   theme,
   beatAnalysis,
   contentOrigin,
+  renderTimeRange,
 }: TimelineRulerProps) {
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const beatTimes = beatAnalysis?.beatTimes ?? [];
   const beatStrengths = beatAnalysis?.beatStrengths ?? [];
+  const beatEntries = getTimelineBeatEntries(beatTimes, beatStrengths, renderTimeRange);
 
   // Only draw beat lines when they'd be at least 5px apart
   const avgBeatInterval =
@@ -51,13 +56,14 @@ export const TimelineRuler = memo(function TimelineRuler({
         height={totalH}
       >
         {showBeats &&
-          beatTimes.map((t, i) => {
+          beatEntries.map(({ time: t, index: i, strength: beatStrength }) => {
             const x = t * pps;
             // Louder beats → brighter line. Gamma curve widens the contrast.
-            const strength = Math.pow(Math.min(1, beatStrengths[i] ?? 0.5), 2.2);
+            const strength = Math.pow(Math.min(1, beatStrength ?? 0.5), 2.2);
             const opacity = 0.08 + strength * 0.62;
             return (
               <line
+                data-timeline-grid-cell="beat"
                 key={`b-${t}-${i}`}
                 x1={x}
                 y1={0}
@@ -103,13 +109,23 @@ export const TimelineRuler = memo(function TimelineRuler({
               contentOrigin + t * pps (see getTimelinePlayheadLeft). Without the shift
               a tick spans [x, x+1) and its center is half a pixel right. */}
           {minor.map((t) => (
-            <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps - 0.5 }}>
+            <div
+              key={`m-${t}`}
+              data-timeline-grid-cell="minor"
+              className="absolute bottom-0"
+              style={{ left: t * pps - 0.5 }}
+            >
               <div className="w-px h-2" style={{ background: theme.tickMinor }} />
             </div>
           ))}
 
           {major.map((t) => (
-            <div key={`M-${t}`} className="absolute top-0" style={{ left: t * pps - 0.5 }}>
+            <div
+              key={`M-${t}`}
+              data-timeline-grid-cell="major"
+              className="absolute top-0"
+              style={{ left: t * pps - 0.5 }}
+            >
               <span
                 className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
                 style={{

package/src/player/components/TimelineTrackRow.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+
+interface TimelineTrackRowProps {
+  index: number;
+  rowKey: number;
+  rowCount: number;
+  top: number;
+  height: number;
+  virtualized: boolean;
+  background: string;
+  borderColor: string;
+  children: ReactNode;
+}
+
+/** Accessible row shell; edit geometry owns its exact top and height. */
+export function TimelineTrackRow({
+  index,
+  rowKey,
+  rowCount,
+  top,
+  height,
+  virtualized,
+  background,
+  borderColor,
+  children,
+}: TimelineTrackRowProps) {
+  return (
+    <div
+      role="listitem"
+      aria-posinset={index + 1}
+      aria-setsize={rowCount}
+      data-index={index}
+      data-timeline-row={index}
+      data-timeline-row-key={rowKey}
+      className={`${virtualized ? "absolute left-0 right-0" : "relative"} flex`}
+      style={{
+        top: virtualized ? top : undefined,
+        height,
+        background,
+        borderBottom: `1px solid ${borderColor}`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/player/components/TimelineTypes.ts

@@ -5,6 +5,8 @@ import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
 
 export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
+  /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
+  sessionEpoch?: number;
   onSeek?: (time: number) => void;
   onDrillDown?: (element: TimelineElement) => void;
   renderClipContent?: (