@hyperframes/studio 0.7.75 → 0.7.77

package/src/player/components/useTimelinePlayhead.ts

@@ -3,9 +3,8 @@ import { liveTime, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
-  GUTTER,
-  TRACKS_LEFT_PAD,
   getTimelinePlayheadLeft,
+  getTimelineScrubTime,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
@@ -31,6 +30,7 @@ interface UseTimelinePlayheadInput {
   setZoomMode: (mode: ZoomMode) => void;
   setManualZoomPercent: (percent: number) => void;
   onSeek?: (time: number) => void;
+  contentOrigin: number;
 }
 
 export function useTimelinePlayhead({
@@ -52,6 +52,7 @@ export function useTimelinePlayhead({
   setZoomMode,
   setManualZoomPercent,
   onSeek,
+  contentOrigin,
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
@@ -60,6 +61,8 @@ export function useTimelinePlayhead({
   // anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
   const previousAnchorPpsRef = useRef(pps);
   const skipCenterAnchorRef = useRef(false);
+  const contentOriginRef = useRef(contentOrigin);
+  contentOriginRef.current = contentOrigin;
 
   useLayoutEffect(() => {
     const scroll = scrollRef.current;
@@ -74,21 +77,21 @@ export function useTimelinePlayhead({
     const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
       pointerX: scroll.clientWidth / 2,
       currentScrollLeft: scroll.scrollLeft,
-      gutter: GUTTER + TRACKS_LEFT_PAD,
+      contentOrigin,
       currentPixelsPerSecond: prevPps,
       nextPixelsPerSecond: pps,
       duration: durationRef.current,
     });
     const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
     scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
-  }, [pps, scrollRef, durationRef]);
+  }, [pps, scrollRef, durationRef, contentOrigin]);
 
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current)}px`;
+      playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current, contentOrigin)}px`;
     },
-    [playheadRef, durationRef, ppsRef],
+    [playheadRef, durationRef, ppsRef, contentOrigin],
   );
 
   useEffect(() => {
@@ -120,7 +123,7 @@ export function useTimelinePlayhead({
       if (!playheadRef.current || durationRef.current <= 0) return;
       // Playback deliberately does NOT scroll the viewport to chase the playhead —
       // the user's scroll position is theirs; the playhead may run off-screen.
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(t, ppsRef.current)}px`;
+      playheadRef.current.style.left = `${getTimelinePlayheadLeft(t, ppsRef.current, contentOriginRef.current)}px`;
     });
     return unsub;
   });
@@ -130,13 +133,18 @@ export function useTimelinePlayhead({
       const el = scrollRef.current;
       if (!el || effectiveDuration <= 0) return;
       const rect = el.getBoundingClientRect();
-      const x = clientX - rect.left + el.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
-      if (x < 0) return;
-      const time = Math.max(0, Math.min(effectiveDuration, x / pps));
+      const time = getTimelineScrubTime({
+        clientX,
+        viewportLeft: rect.left,
+        scrollLeft: el.scrollLeft,
+        contentOrigin,
+        pixelsPerSecond: pps,
+        duration: effectiveDuration,
+      });
       liveTime.notify(time);
       onSeek?.(time);
     },
-    [scrollRef, effectiveDuration, pps, onSeek],
+    [scrollRef, effectiveDuration, pps, onSeek, contentOrigin],
   );
 
   const autoScrollDuringDrag = useCallback(
@@ -186,7 +194,7 @@ export function useTimelinePlayhead({
       const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
         pointerX: e.clientX - rect.left,
         currentScrollLeft: scroll.scrollLeft,
-        gutter: GUTTER + TRACKS_LEFT_PAD,
+        contentOrigin,
         currentPixelsPerSecond: ppsRef.current,
         nextPixelsPerSecond: nextPps,
         duration: durationRef.current,
@@ -209,6 +217,7 @@ export function useTimelinePlayhead({
       manualZoomPercentRef,
       setManualZoomPercent,
       setZoomMode,
+      contentOrigin,
     ],
   );
 

package/src/player/components/useTimelineRangeSelection.ts

@@ -7,7 +7,7 @@ import {
 } from "./timelineEditing";
 import type { TimelineElement } from "../store/playerStore";
 import { liveTime, usePlayerStore } from "../store/playerStore";
-import { GUTTER, TRACKS_LEFT_PAD } from "./timelineLayout";
+import { getTimelineScrubTime } from "./timelineLayout";
 import {
   computeMarqueeSelection,
   getMarqueeRect,
@@ -30,7 +30,9 @@ interface UseTimelineRangeSelectionInput {
   setShowPopover: (v: boolean) => void;
   elementsRef: React.RefObject<TimelineElement[]>;
   trackOrderRef: React.RefObject<number[]>;
+  rowHeightsRef: React.RefObject<readonly number[]>;
   onSelectElement?: (element: TimelineElement | null) => void;
+  contentOrigin: number;
 }
 
 interface MarqueeDragState {
@@ -72,12 +74,16 @@ function commitMarqueeSelection(
   marquee: MarqueeDragState,
   elements: TimelineElement[],
   trackOrder: number[],
+  rowHeights: readonly number[],
   pps: number,
+  contentOrigin: number,
 ): void {
   const { ids, primaryId } = computeMarqueeSelection({
     clips: toMarqueeClips(elements),
     trackOrder,
+    rowHeights,
     pps,
+    contentOrigin,
     marquee: rect,
     baseSelection: additive ? marquee.baseIds : undefined,
   });
@@ -101,7 +107,9 @@ export function useTimelineRangeSelection({
   setShowPopover,
   elementsRef,
   trackOrderRef,
+  rowHeightsRef,
   onSelectElement,
+  contentOrigin,
 }: UseTimelineRangeSelectionInput) {
   const isRangeSelecting = useRef(false);
   const rangeAnchorTime = useRef(0);
@@ -168,10 +176,12 @@ export function useTimelineRangeSelection({
         marquee,
         elementsRef.current ?? [],
         trackOrderRef.current ?? [],
+        rowHeightsRef.current,
         ppsRef.current,
+        contentOrigin,
       );
     },
-    [toContentPoint, elementsRef, trackOrderRef, ppsRef],
+    [toContentPoint, elementsRef, trackOrderRef, rowHeightsRef, ppsRef, contentOrigin],
   );
 
   const stopMarqueeAutoScroll = useCallback(() => {
@@ -228,14 +238,13 @@ export function useTimelineRangeSelection({
       setShowPopover(false);
       const rect = scrollRef.current?.getBoundingClientRect();
       if (rect) {
-        const x =
-          e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER - TRACKS_LEFT_PAD;
+        const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - contentOrigin;
         const time = Math.max(0, x / pps);
         rangeAnchorTime.current = time;
         setRangeSelection({ start: time, end: time, anchorX: e.clientX, anchorY: e.clientY });
       }
     },
-    [scrollRef, pps, setShowPopover],
+    [scrollRef, pps, setShowPopover, contentOrigin],
   );
 
   const handlePointerDown = useCallback(
@@ -286,11 +295,16 @@ export function useTimelineRangeSelection({
       const el = scrollRef.current;
       if (el) {
         const rect = el.getBoundingClientRect();
-        const x = clientX - rect.left + el.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
-        if (x >= 0) {
-          const dur = el.scrollWidth / pps;
-          liveTime.notify(Math.max(0, Math.min(dur, x / pps)));
-        }
+        liveTime.notify(
+          getTimelineScrubTime({
+            clientX,
+            viewportLeft: rect.left,
+            scrollLeft: el.scrollLeft,
+            contentOrigin,
+            pixelsPerSecond: pps,
+            duration: el.scrollWidth / pps,
+          }),
+        );
       }
       if (!seekRafRef.current) {
         seekRafRef.current = requestAnimationFrame(() => {
@@ -302,7 +316,7 @@ export function useTimelineRangeSelection({
         });
       }
     },
-    [scrollRef, pps, seekFromX, autoScrollDuringDrag, isDragging],
+    [scrollRef, pps, seekFromX, autoScrollDuringDrag, isDragging, contentOrigin],
   );
 
   const handlePointerMove = useCallback(
@@ -310,8 +324,7 @@ export function useTimelineRangeSelection({
       if (isRangeSelecting.current) {
         const rect = scrollRef.current?.getBoundingClientRect();
         if (rect) {
-          const x =
-            e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER - TRACKS_LEFT_PAD;
+          const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - contentOrigin;
           setRangeSelection((prev) =>
             prev
               ? { ...prev, end: Math.max(0, x / pps), anchorX: e.clientX, anchorY: e.clientY }
@@ -331,7 +344,15 @@ export function useTimelineRangeSelection({
       if (!isDragging.current) return;
       updateScrubDrag(e.clientX);
     },
-    [pps, scrollRef, isDragging, applyMarqueeAtClient, syncMarqueeAutoScroll, updateScrubDrag],
+    [
+      pps,
+      scrollRef,
+      isDragging,
+      applyMarqueeAtClient,
+      syncMarqueeAutoScroll,
+      updateScrubDrag,
+      contentOrigin,
+    ],
   );
 
   // Release of a shift time-range gesture: keep a real range (or a shift-click

package/src/player/components/useTimelineTrackLayout.test.ts

@@ -0,0 +1,53 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { afterEach, describe, expect, it } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { LANE_H, TRACK_H } from "./timelineLayout";
+import { useTimelineTrackLayout } from "./useTimelineTrackLayout";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+});
+
+describe("useTimelineTrackLayout", () => {
+  it("counts a flat tween lane and reserves its expanded row height", () => {
+    const elements: TimelineElement[] = [
+      { id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
+    ];
+    const animations = new Map<string, GsapAnimation[]>([
+      [
+        "clip-1",
+        [
+          {
+            id: "position-tween",
+            targetSelector: "#clip-1",
+            method: "to",
+            position: 0,
+            duration: 1,
+            properties: { x: 420 },
+            propertyGroup: "position",
+          },
+        ],
+      ],
+    ]);
+    usePlayerStore.setState({ expandedClipIds: new Set(["clip-1"]) });
+
+    let layout: ReturnType<typeof useTimelineTrackLayout> | undefined;
+    function Probe() {
+      layout = useTimelineTrackLayout(elements, animations, null, new Set());
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe)));
+
+    expect(layout?.laneCounts.get("clip-1")).toBe(1);
+    expect(layout?.rowHeights).toEqual([TRACK_H + LANE_H]);
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineTrackLayout.ts

@@ -0,0 +1,162 @@
+import { useMemo, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { animationContributesLane } from "./TimelinePropertyLanes";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
+import {
+  TRACK_H,
+  getTimelineCanvasHeight,
+  getTimelineRowHeight,
+  trackHeights,
+  type TimelineTrackHeightClip,
+} from "./timelineLayout";
+
+export { getTrackStyle } from "./timelineIcons";
+
+/**
+ * The single keyframed element whose property lanes a track shows when expanded.
+ * A track can hold several elements (same z-index is common), but keyframes are
+ * per-element, so we scope to ONE active element — the selected one if it's on
+ * this track, otherwise the element with the most lanes. Selecting a clip is how
+ * you switch which element you're keyframing. Returns null when no element on the
+ * track has keyframes.
+ */
+export function resolveTrackKeyframeClip(
+  elements: readonly TimelineElement[],
+  laneCounts: ReadonlyMap<string, number>,
+  selectedElementId: string | null,
+  selectedElementIds: ReadonlySet<string>,
+): TimelineElement | null {
+  const keyframed = elements.filter(
+    (element) => (laneCounts.get(element.key ?? element.id) ?? 0) >= 1,
+  );
+  if (keyframed.length === 0) return null;
+  const selected = keyframed.find((element) => {
+    const key = element.key ?? element.id;
+    return key === selectedElementId || selectedElementIds.has(key);
+  });
+  if (selected) return selected;
+  // Most lanes wins, first one on a tie (same as the old stable sort), but as a
+  // reduce over the already non-empty list so there's no index to assert on.
+  const lanesOf = (element: TimelineElement) => laneCounts.get(element.key ?? element.id) ?? 0;
+  return keyframed.reduce((best, element) => (lanesOf(element) > lanesOf(best) ? element : best));
+}
+
+/** Lanes per clip: the count of distinct property groups whose tween contributes
+ *  a lane (real keyframes or a synthesizable flat tween). */
+function computeLaneCounts(
+  tracks: [number, TimelineElement[]][],
+  gsapAnimations: Map<string, GsapAnimation[]>,
+): Map<string, number> {
+  const laneCounts = new Map<string, number>();
+  for (const [, elements] of tracks) {
+    for (const element of elements) {
+      const clipId = element.key ?? element.id;
+      const propertyGroups = new Set<string>();
+      for (const animation of gsapAnimations.get(clipId) ?? []) {
+        if (animation.propertyGroup && animationContributesLane(animation)) {
+          propertyGroups.add(animation.propertyGroup);
+        }
+      }
+      laneCounts.set(clipId, propertyGroups.size);
+    }
+  }
+  return laneCounts;
+}
+
+function useTimelineRowHeights(
+  tracks: [number, TimelineElement[]][],
+  gsapAnimations: Map<string, GsapAnimation[]>,
+  selectedElementId: string | null,
+  selectedElementIds: ReadonlySet<string>,
+) {
+  const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
+  const { laneCounts, rowHeights } = useMemo(() => {
+    const laneCounts = computeLaneCounts(tracks, gsapAnimations);
+    // Row height follows only the active keyframe clip, so a track with several
+    // keyframed elements never reserves empty lanes for the ones not shown.
+    const heightTracks: TimelineTrackHeightClip[][] = tracks.map(([, elements]) => {
+      const active = resolveTrackKeyframeClip(
+        elements,
+        laneCounts,
+        selectedElementId,
+        selectedElementIds,
+      );
+      if (!active) return [];
+      const clipId = active.key ?? active.id;
+      return [{ clipId, laneCount: laneCounts.get(clipId) ?? 0 }];
+    });
+    return {
+      laneCounts,
+      rowHeights: trackHeights(
+        heightTracks,
+        STUDIO_KEYFRAMES_ENABLED ? expandedClipIds : undefined,
+      ),
+    };
+  }, [expandedClipIds, gsapAnimations, tracks, selectedElementId, selectedElementIds]);
+  const rowHeightsRef = useRef<readonly number[]>(rowHeights);
+  rowHeightsRef.current = rowHeights;
+  return { laneCounts, rowHeights, rowHeightsRef };
+}
+
+export function useTimelineTrackLayout(
+  expandedElements: TimelineElement[],
+  gsapAnimations: Map<string, GsapAnimation[]>,
+  selectedElementId: string | null,
+  selectedElementIds: ReadonlySet<string>,
+) {
+  const { tracks, trackStyles, trackOrder } = useTimelineTrackDerivations(expandedElements);
+  const trackOrderRef = useRef(trackOrder);
+  trackOrderRef.current = trackOrder;
+  const { laneCounts, rowHeights, rowHeightsRef } = useTimelineRowHeights(
+    tracks,
+    gsapAnimations,
+    selectedElementId,
+    selectedElementIds,
+  );
+
+  return {
+    tracks,
+    trackStyles,
+    trackOrder,
+    trackOrderRef,
+    laneCounts,
+    rowHeights,
+    rowHeightsRef,
+  };
+}
+
+function useDisplayRowHeights(
+  displayTrackOrder: readonly number[],
+  trackOrder: readonly number[],
+  rowHeights: readonly number[],
+) {
+  return useMemo(
+    () =>
+      displayTrackOrder.map((track) => {
+        const row = trackOrder.indexOf(track);
+        return row < 0 ? TRACK_H : getTimelineRowHeight(row, rowHeights);
+      }),
+    [displayTrackOrder, trackOrder, rowHeights],
+  );
+}
+
+function useDisplayTrackOrder(draggedClip: DraggedClipState | null, trackOrder: number[]) {
+  return useMemo(() => {
+    if (!draggedClip?.started || trackOrder.includes(draggedClip.previewTrack)) return trackOrder;
+    return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
+  }, [draggedClip, trackOrder]);
+}
+
+export function useTimelineDisplayLayout(
+  draggedClip: DraggedClipState | null,
+  trackOrder: number[],
+  rowHeights: readonly number[],
+) {
+  const displayTrackOrder = useDisplayTrackOrder(draggedClip, trackOrder);
+  const displayRowHeights = useDisplayRowHeights(displayTrackOrder, trackOrder, rowHeights);
+  const totalH = getTimelineCanvasHeight(displayRowHeights);
+  return { displayTrackOrder, displayRowHeights, totalH };
+}

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

@@ -278,6 +278,49 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("scene");
   });
 
+  it("THE BUG: keeps a composition expanded with the playhead parked on its end", () => {
+    // Clip windows are half-open, so at the very end of the timeline the
+    // playhead was inside nothing and every expanded row collapsed.
+    const manifest = [
+      clip({ id: "scene", start: 0, duration: 12 }),
+      clip({ id: "headline", start: 0, duration: 12 }),
+    ];
+    const parentMap = new Map([["headline", "scene"]]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: false,
+        currentTime: 12,
+        manifest,
+        parentMap,
+      }),
+    ).toBe("scene");
+  });
+
+  it("prefers the starting clip over the ending one on a shared seam", () => {
+    const manifest = [
+      clip({ id: "first", start: 0, duration: 5 }),
+      clip({ id: "first-child", start: 0, duration: 5 }),
+      clip({ id: "second", start: 5, duration: 5 }),
+      clip({ id: "second-child", start: 5, duration: 5 }),
+    ];
+    const parentMap = new Map([
+      ["first-child", "first"],
+      ["second-child", "second"],
+    ]);
+
+    expect(
+      resolveTimelineExpansionRawId({
+        selectedElementId: null,
+        isPlaying: false,
+        currentTime: 5,
+        manifest,
+        parentMap,
+      }),
+    ).toBe("second");
+  });
+
   it("auto-expands the innermost active nested composition when paused", () => {
     const manifest = [
       clip({ id: "outer", start: 0, duration: 10 }),

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -2,7 +2,7 @@ import { useMemo } from "react";
 import { usePlayerStore, type TimelineElement, type DomClipChild } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
-import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
+import { buildTimelineElementKey, splitTimelineElementKey } from "../lib/timelineElementHelpers";
 
 function findTopLevelAncestor(id: string, parentMap: Map<string, string>): string | null {
   let current = parentMap.get(id);
@@ -19,18 +19,13 @@ function findTopLevelAncestor(id: string, parentMap: Map<string, string>): strin
   return current;
 }
 
-function extractDomId(key: string): string {
-  const hashIdx = key.lastIndexOf("#");
-  return hashIdx >= 0 ? key.slice(hashIdx + 1) : key;
-}
-
 function resolveRawId(
   selectedId: string | null,
   manifest: ClipManifestClip[],
   parentMap: Map<string, string>,
 ): string | null {
   if (!selectedId) return null;
-  const rawId = extractDomId(selectedId);
+  const rawId = splitTimelineElementKey(selectedId).domId;
   if (parentMap.has(rawId)) return rawId;
   if (parentMap.has(selectedId)) return selectedId;
   const clip = manifest.find((c) => c.label === selectedId || c.label === rawId);
@@ -50,6 +45,11 @@ function clipContainsTime(clip: ClipManifestClip, time: number): boolean {
   return Number.isFinite(time) && time >= clip.start && time < clip.start + clip.duration;
 }
 
+/** Half-open containment plus the closing boundary — see the fallback below. */
+function clipTouchesTime(clip: ClipManifestClip, time: number): boolean {
+  return Number.isFinite(time) && time >= clip.start && time <= clip.start + clip.duration;
+}
+
 function getActiveParentDepth(id: string, parentMap: Map<string, string>, activeIds: Set<string>) {
   let depth = 0;
   let parent = parentMap.get(id);
@@ -70,11 +70,20 @@ function findActiveExpandableCompositionId(
   parentMap: Map<string, string>,
 ): string | null {
   const parentIds = new Set(parentMap.values());
-  const activeIds = new Set<string>();
-  for (const clip of manifest) {
-    if (!clip.id || !parentIds.has(clip.id) || !clipContainsTime(clip, currentTime)) continue;
-    activeIds.add(clip.id);
-  }
+  const collect = (matches: (clip: ClipManifestClip, time: number) => boolean) => {
+    const ids = new Set<string>();
+    for (const clip of manifest) {
+      if (clip.id && parentIds.has(clip.id) && matches(clip, currentTime)) ids.add(clip.id);
+    }
+    return ids;
+  };
+  // Clip windows are half-open, so a playhead parked exactly on a clip's end is
+  // inside nothing — at the end of the timeline that collapsed every expanded
+  // sub-composition row and its keyframe lanes. Only when the strict pass finds
+  // nothing do we accept the closing boundary, so a playhead landing on the seam
+  // between two adjacent clips still expands the one that is starting.
+  const strict = collect(clipContainsTime);
+  const activeIds = strict.size > 0 ? strict : collect(clipTouchesTime);
   let bestId: string | null = null;
   let bestDepth = -1;
   for (const id of activeIds) {

package/src/player/lib/timelineElementHelpers.ts

@@ -298,6 +298,20 @@ export function buildTimelineElementKey(params: {
   return `${scope}:${params.id}:${params.fallbackIndex}`;
 }
 
+/**
+ * Inverse of {@link buildTimelineElementKey} for the `sourceFile#domId` form.
+ * A key with no `#` is a bare dom id and carries no source file of its own, so
+ * the caller supplies the scope it wants to look that id up in.
+ */
+export function splitTimelineElementKey(key: string): {
+  sourceFile: string | null;
+  domId: string;
+} {
+  const hashIndex = key.lastIndexOf("#");
+  if (hashIndex < 0) return { sourceFile: null, domId: key };
+  return { sourceFile: key.slice(0, hashIndex), domId: key.slice(hashIndex + 1) };
+}
+
 export function buildTimelineElementIdentity(params: {
   preferredId?: string | null;
   label: string;
@@ -366,20 +380,21 @@ function numbersNearlyEqual(a: number, b: number): boolean {
   return Math.abs(a - b) < 0.001;
 }
 
+const MANIFEST_CLIP_ATTRS: ReadonlyArray<[string, (clip: ClipManifestClip) => number]> = [
+  ["data-start", (clip) => clip.start],
+  ["data-duration", (clip) => clip.duration],
+  ["data-track-index", (clip) => clip.track],
+];
+
 function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean {
   const tagName = clip.tagName?.toLowerCase();
   if (tagName && node.tagName.toLowerCase() !== tagName) return false;
-
-  const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
-  if (Number.isFinite(start) && !numbersNearlyEqual(start, clip.start)) return false;
-
-  const duration = Number.parseFloat(node.getAttribute("data-duration") ?? "");
-  if (Number.isFinite(duration) && !numbersNearlyEqual(duration, clip.duration)) return false;
-
-  const track = Number.parseInt(node.getAttribute("data-track-index") ?? "", 10);
-  if (Number.isFinite(track) && track !== clip.track) return false;
-
-  return true;
+  // An attribute only constrains the match when it parses to a finite number:
+  // missing or garbled reads as "unknown", not "mismatch".
+  return MANIFEST_CLIP_ATTRS.every(([attr, expected]) => {
+    const actual = Number.parseFloat(node.getAttribute(attr) ?? "");
+    return !Number.isFinite(actual) || numbersNearlyEqual(actual, expected(clip));
+  });
 }
 
 function findTimelineDomNode(doc: Document, id: string): Element | null {